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

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

This post shows a practical workflow to: (1) run the Serena MCP server, (2) connect it to Claude Code, and (3) monitor token usage and costs with ccusage. Follow the steps below for a working local setup and useful tips.

TL;DR — copy/paste quick setup & prompts

Quick commands (run in a terminal):

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

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

# Run ccusage (no install required)
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 on your machine)
Python/uv or uvx available (Serena uses uv tooling)
Git (to clone repositories)
Node.js / bun / npx (for running ccusage — installation optional)

2. Quick overview (contract)

Inputs: project directory with source code, Claude Code client, local shell
Outputs: Serena MCP server running and connected to Claude Code; local token/cost reports from ccusage
Error modes: missing uv/uvx, incorrect paths, permissions preventing MCP startup
Success: Claude Code lists Serena as an MCP server and ccusage daily shows usage

3. Install / run Serena (local, minimal)

Clone Serena and change into the repo:

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

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

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:

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

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

uv run serena start-mcp-server

Optional: run in SSE mode (start server yourself and connect via HTTP):

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

Notes:

Serena will create a dashboard on localhost by default (e.g. http://localhost:24282/dashboard/index.html).
You can edit configuration with uvx serena config edit or via ~/.serena/serena_config.yml.

4. Connect Serena to Claude Code

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

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

Explanation:

The claude mcp add command registers an MCP server for Claude Code. Replace the uvx ... command with the command you used to run Serena if different.
--context ide-assistant is recommended for IDE-like integrations; other contexts include desktop-app, agent, and codex.

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

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

5. Activate project & (recommended) index

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

Optionally index the project for better performance:

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

Indexing helps Serena perform semantic searches faster in larger codebases.

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

ccusage can be run without installing globally. Quick recommended way (bunx):

# using bunx (fast)
bunx ccusage

# or with npx
npx ccusage@latest

Common commands:

ccusage daily — show daily token usage and cost
ccusage monthly — aggregated monthly report
ccusage session — usage grouped by conversation session
ccusage blocks --live — live monitoring (real-time)

Example: generate a daily JSON report for a specific date range:

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

Tips:

Use --instances to group by project or --project <name> to filter
--compact for narrower terminals or screenshots

7. Typical workflow (step-by-step)

Start Serena MCP server (Option A or B above).
Register the MCP server with Claude Code using claude mcp add ... from your project directory.
Activate the project in Claude Code (so Serena knows the active project).
Optionally run serena project index to speed up semantic queries.
Interact with Claude Code as usual — Serena’s tools (find_symbol, insert_after_symbol, execute_shell_command, etc.) will be available to the model.
Meanwhile, run ccusage locally to watch token usage and costs:

# basic live monitoring
ccusage blocks --live

# daily summary while you work
ccusage daily --instances --project myproject

8. Troubleshooting & common pitfalls

Serena fails to start: ensure uv/uvx is installed and in PATH, or use the correct absolute paths.
Claude doesn’t see Serena: verify the claude mcp add command uses the same run command as you used to start Serena, and that --project points to the right folder.
Long startup / language server errors: some language servers (Java, big LSPs) can be slow or require extra installs. See Serena 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 safer analysis-only usage.

9. Security and safety notes

Serena may execute shell commands when configured; always review any commands before allowing them.
Keep backups and use Git to review changes created by the agent.

10. Links & resources

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

Conclusion

Using Serena with Claude Code can greatly improve code editing efficiency and reduce token usage by enabling symbolic code tools. ccusage complements this setup by giving you clear, local insights into token usage and costs so you can iterate efficiently and stay on budget.

If you’d like, I can also:

add a small screenshots folder and wire images for key commands,
produce a minimal README with one-line commands to start both Serena and ccusage together,
or create a short troubleshooting cheat-sheet.

Example prompts (use with Serena + Claude Code)

Below are practical prompt templates you can use when interacting with Claude + Serena. They are written to make use of Serena’s symbolic tools (find_symbol, insert_after_symbol, execute_shell_command, etc.). Replace placeholders like , , and <PROJECT_PATH> with real values.

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.”

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 , and apply it using Serena’s insert/replace tools. Explain the change in 2-3 sentences.”

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.”

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.”

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 (older setups).
Prefer multi-step workflows: planning prompt → apply change prompt → test prompt → review prompt.

How to use Claude Code with Serena and ccusage in 3 minutes

Table of Contents