Table of Contents

• How to use Claude Code with Serena and ccusage (step-by-step)
  • TL;DR: copy/paste quick setup and prompts
  • 1. What you’ll need
  • 2. Quick overview (contract)
  • 3. Install / run Serena (local, minimal)
  • 4. Connect Serena to Claude Code
  • 5. Activate the project and (recommended) index it
  • 6. Install / run ccusage to monitor token usage and cost
  • 7. Typical workflow (step-by-step)
  • 8. Troubleshooting and common pitfalls
  • 9. Security and safety notes
  • 10. Links and resources
  • Conclusion
  • Example prompts (use with Serena + Claude Code)

How to use Claude Code with Serena and ccusage (step-by-step)

This post covers a practical workflow: run the Serena MCP server, connect it to Claude Code, and monitor token usage and cost with ccusage. Follow the steps below for a working local setup.

TL;DR: copy/paste quick setup and prompts

Quick commands (run in a terminal):

1
# Clone & run Serena (uvx)
2
git clone https://github.com/oraios/serena
3
cd serena
4
uvx --from git+https://github.com/oraios/serena serena start-mcp-server
5

6
# From your project dir: register Serena with Claude Code
7
cd /path/to/your/project
8
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
9

10
# Run ccusage (no install required)
11
bunx ccusage    # or: npx ccusage@latest

One-line prompts (copy/paste into Claude):

• Activate & onboard: “Activate the project /abs/path/to/myproj and run onboarding; summarize modules, tests, and missing deps.”

• Find symbol & show references: “Find definition of my_func in module pkg.module; show signature and references.”

• Implement small feature + test: “Implement add_user_profile in users/profile.py and add tests/test_profile.py; run tests and report results.”

• Quick audit for shell commands: “List uses of execute_shell_command in the project, show exact commands proposed in the last 24h, and explain risks.”

Replace placeholders (paths, module names) with real values before running.

1. What you’ll need

• Claude Code installed and configured (claude --version should print a version number)
• Python/uv or uvx available (Serena uses uv tooling)
• Git, to clone repositories
• Node.js / bun / npx, to run ccusage (no global install required)

2. Quick overview (contract)

• Inputs: a project directory with source code, the Claude Code client, a local shell
• Outputs: Serena running as an MCP server connected to Claude Code, plus local token/cost reports from ccusage
• Error modes: missing uv/uvx, wrong paths, permissions blocking MCP startup
• Success: claude mcp list shows Serena, and ccusage prints a usage table

3. Install / run Serena (local, minimal)

1. Clone Serena and change into the repo:

1
git clone https://github.com/oraios/serena
2
cd serena

2. Option A: run with uvx (recommended if you have it):

1
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

If you run the server from outside the Serena directory, pass the directory explicitly:

1
uvx --from git+https://github.com/oraios/serena serena start-mcp-server --directory /abs/path/to/serena

3. Option B: local uv run (if you have uv installed):

1
uv run serena start-mcp-server

4. Optional: run in SSE mode (start the server yourself and connect over HTTP):

1
uv run serena start-mcp-server --transport sse --port 9121

Notes:

• Serena creates a dashboard on localhost by default (for example, http://localhost:24282/dashboard/index.html).
• Edit configuration with uvx serena config edit or directly in ~/.serena/serena_config.yml.

The Serena-specific flags above (--context, --transport, serena config edit) come from Serena’s own CLI, not Claude Code’s. Verify them against your installed Serena version if they seem off; they are unchanged from the original guide and were not re-verified for this update.

4. Connect Serena to Claude Code

From your project directory (the project you want Serena to work on):

1
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

Explanation:

• claude mcp add <name> <command> [args...] registers an MCP server for Claude Code; this syntax is current as of Claude Code 2.1. Swap in your own run command if it differs from the uvx one above.
• Everything after -- is passed straight to Serena’s own process, including --context ide-assistant.
• Add -s project (or -s user) if you want the registration to persist outside this one local checkout; the default scope is local.

If you use Claude Desktop, add an MCP server entry under File → Settings → Developer → MCP Servers. Example claude_desktop_config.json entry for uvx:

1
{
2
  "mcpServers": {
3
    "serena": {
4
      "command": "/path/to/uvx",
5
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant", "--project", "/abs/path/to/your/project"]
6
    }
7
  }
8
}

5. Activate the project and (recommended) index it

In Claude Code, activate the project or ask Claude to “Activate the project $(pwd)”.

Optionally index the project for faster semantic search:

1
uvx --from git+https://github.com/oraios/serena serena project index --directory /abs/path/to/your/project

Indexing helps Serena search larger codebases faster.

6. Install / run ccusage to monitor token usage and cost

ccusage now tracks usage across several coding agents, not just Claude Code: Codex, Gemini CLI, Copilot CLI, and others each get their own subcommand alongside ccusage claude. Run it without installing globally:

1
# using bunx (fast)
2
bunx ccusage
3

4
# or with npx
5
npx ccusage@latest

Common commands, scoped to Claude Code specifically:

• ccusage claude daily: usage grouped by date
• ccusage claude monthly: usage grouped by month
• ccusage claude session: usage grouped by conversation session
• ccusage claude blocks --active: the current 5-hour billing block with a cost projection, useful for live monitoring while you work

Example: a daily JSON report for a date range:

1
ccusage claude daily --since 20250501 --until 20250531 --json > may-report.json

Tips:

• ccusage claude daily --instances --project myproject breaks usage down per project.
• --compact shrinks the table for narrow terminals or screenshots.
• Running bare ccusage daily (without claude) aggregates every agent it detects on the machine, which is useful once you run more than one coding CLI side by side.

7. Typical workflow (step-by-step)

1. Start the Serena MCP server (Option A or B above).
2. Register it with Claude Code using claude mcp add ... from your project directory.
3. Activate the project in Claude Code so Serena knows what it’s working on.
4. Optionally run serena project index to speed up semantic queries.
5. Work with Claude Code as usual; Serena’s tools (find_symbol, insert_after_symbol, execute_shell_command, etc.) become available to the model.
6. Meanwhile, watch usage with ccusage:

1
# current billing block, refreshed on demand
2
ccusage claude blocks --active
3

4
# daily summary broken down by project
5
ccusage claude daily --instances --project myproject

8. Troubleshooting and common pitfalls

• Serena fails to start: confirm uv/uvx is installed and on PATH, or use absolute paths.
• Claude doesn’t see Serena: check that the claude mcp add command matches the one you used to start Serena, and that --project points to the right folder. claude mcp list shows what’s currently registered.
• Long startup or language server errors: some language servers (Java, larger LSPs) are slow to start or need extra installs; check Serena’s docs for language-specific notes.
• Dangerous tools: execute_shell_command can run arbitrary commands. Consider disabling editing tools, or run Serena in read-only mode (read_only: true) for analysis-only usage.

9. Security and safety notes

• Serena can execute shell commands when configured to; always review commands before approving them.
• Keep backups and use Git to review any changes the agent makes.

10. Links and resources

• Serena repository: https://github.com/oraios/serena
• Serena docs: see README.md in the repo
• ccusage repository: https://github.com/ryoppippi/ccusage
• ccusage docs: https://ccusage.com/

Conclusion

Serena gives Claude Code symbolic code tools that cut down on token usage for large codebases. ccusage closes the loop with a clear, local view of what that usage costs, across Claude Code and, as of the latest release, several other coding CLIs, so you can iterate without guessing at your bill.

Example prompts (use with Serena + Claude Code)

Practical prompt templates that lean on Serena’s symbolic tools (find_symbol, insert_after_symbol, execute_shell_command, etc.). Replace placeholders like <MODULE>, <FUNCTION>, and <PROJECT_PATH> with real values.

1. Activate project and do onboarding

“Activate the project <PROJECT_PATH> and run onboarding. Summarize the main modules, tests, and any missing dependencies. If onboarding finds issues, list the commands to fix them and explain why.”

2. Find where a symbol is defined and update it

“Find the definition of <FUNCTION> in module <MODULE> and show me the top-level function signature and docstring. If there are references to this symbol, list the files and line numbers. Then propose a minimal safe change to the function to <GOAL>, and apply it using Serena’s insert/replace tools. Explain the change in 2 to 3 sentences.”

3. Implement a small feature with tests

“Implement a function add_user_profile in users/profile.py that validates input fields (name, email) and writes to users/store.py. Add a unit test in tests/test_profile.py. Run the test suite and if tests fail, provide diagnostic steps and fix the code until tests pass. Use execute_shell_command only after asking for confirmation.”

4. Refactor: move code to a new module

“Refactor the helper calculate_score from old/utils.py into a new module scoring/score.py. Update all references, add an export, and run the type-checker or tests. Provide a short changelog-style summary of modifications.”

5. Quick audit for risky shell commands

“Show me any uses of execute_shell_command in the project and list the exact commands proposed by the agent during the last 24 hours. For each command, explain potential risks and suggest safer alternatives.”

Usage notes:

• Keep prompts specific and include the project path when possible.
• Ask Serena to “read the initial instructions” if you suspect the agent missed the MCP server’s instructions.
• Prefer multi-step workflows: planning prompt, apply-change prompt, test prompt, review prompt.