initially the thought of this was pretty stressful, but being a good solutionist i proceeded with dicecting the issues one by one and presistent on finding a solition for them all.

The first thing is prioritizing platoforms, The stats were clear hence shared them with my manager, got iOS, Android prioritized in order and parked Windows for later as usage is extremly low. now the priority is set to the next thing.

The problem was not the workload. it was the cognitive overhead. i can barely understand my own code after a few months. here i am inheriting code from 6-7 people who clearly took shortcuts to ship fast. folder structure was a dump. files everywhere. and on top of reverse-engineering three codebases i had to track what is done, what is next, what is blocked: simultaneously, across all platforms this task alone without AI would be a real pain and would def take more than few months.

I opted to the $20 Claude subscription. so every session i was wasting the first chunk of context re-explaining the same codebase to Claude, re-orienting it to where i left off, re-answering questions it should already know. by lunch i was running out of tokens i had to use my colleague’s accounts to do whole thing again (Thanks Arun!)

out of this mess i needed a single place. one terminal. one browser tab. one AI session that already knows everything and picks up exactly where we left off, an interface for me and claude to read/update/learn about the project im working and it has to be highly structured, organized and prioritized.

so i built one. i call it the Command Center. if you have any other name to suggest, my inbox is open. this post is the full breakdown of what it is, how it works, and how you can shape it for your your own structure if you ever are in that spot, a little future pridction i think by the end of 2026 we all might have to work in this kind of set-up working on multiple projects simultaniously or atleast we will be capabble of that level of productivity.

What is this AI-Command Center

the idea is simple. instead of having our docs, tasks, changelogs in multiple apps and your terminal tabs scattered across screens for different platforms wokfing with different stages of the tasks or even totally different task altogether: and your daily runner claude-code has no means to know about all these instead you put a single shared operational layer above all your repos. not inside them. above them hence the term command center.

MyWorkspace/
├── ios/               ← own git repo, untouched
├── ios-dataKit/       ← own git repo, untouched
├── android/           ← own git repo, untouched
├── win/               ← own git repo, untouched
└── .ops/              ← Command Center (its own git repo)
    ├── docs/          ← documentation per project
    ├── todo/          ← task files per project + daily focus
    ├── memo/          ← decisions, KT notes, research
    ├── diagrams/      ← architecture diagrams + companion notes
    ├── changelog/     ← per-project ship history
    ├── scripts/       ← automation scripts
    └── dashboard/     ← local web dashboard

Don’t worry the project folders stay completely independent. git -C ios/ status never bleeds into git -C android/ status. you can add or remove a project folder without touching anything else, this is very important sepearation for corporate repositories where the restrictions are tight.

almost everything in .ops/ is a markdown, here is where it might looks like the WiKi pattern shared by the Andrej Karpathy. it is readable by me and the AI, diffs cleanly, and has zero dependencies you can stop here is you want a bare simple command-center but if you are like me this is not enough and there are many flaws here like doc’s going stale as we make changes so lets get to the text stage.

The scripts are the real MVP

As i said earlier i still use the 20$ subscription so for me tokens are really valuable running out of limit means one less productive day that might gift me a day of guilt so making use of scripts to save some routine commands that im sure will be helpful for claude to not be too dependent on remote calls, it might be confusting so here is example:

when i ask Claude “what is the git status across all my repos?” Claude tries to figure it out by calling tools one at a time burning tokens on reasoning and multiple tool calls to give me accurate and proper response

but if you have a script that does it:

# .ops/scripts/git_status_all.sh
for dir in android ios ios-dataKit ios-textEditor win; do
    branch=$(git -C "$ROOT/$dir" branch --show-current 2>/dev/null)
    changes=$(git -C "$ROOT/$dir" status --porcelain | wc -l | tr -d ' ')
    if [ "$changes" -gt 0 ]; then
        echo "● $dir — $branch ($changes uncommitted)"
    else
        echo "● $dir — $branch (clean)"
    fi
done

Claude runs the script. gets the answer in one shot. no reasoning, no guessing, no tool call loop you don’t have to write this manually you can just ask it to do, just make sure you get the code though.

the scripts i have accumulated up over time:

the pattern is always same: take something that would require Claude to do many tool calls or make assumptions, turn it into one script, let Claude just run it and read the output. you get a more reliable answer and you spend a fraction of the tokens.

the session_context.sh one is worth explaining. it runs as a session-start hook and injects the project context automatically before i type anything:

=== SESSION BRIEFING (2026-04-26) ===

REPOS
  ios          dev_eganathan   clean
  android      dev_eganathan   clean
  ios-dataKit  dev_eganathan   14 uncommitted  ← needs attention

HIGH PRIORITY (ios)
  - sessionId hardcoded as "" (TIBConverseInteractor.swift:83)
  - Localization migration uncommitted

LAST SESSION: 2026-04-22 — ios folder restructure, Settings flatten done
DOC SYNC: 8 stale docs — run /sync
=====================================

this replaces re-explaining the codebase every session. the entire briefing is generated from actual file state and costs about 100 tokens to inject i shared only a small portion of this but it basically added more relavant contexts that im sure will help claude so compare that to the 500–1000 tokens you’d spend manually orienting Claude each time.

Documentation that doesn’t go stale

the biggest problem with docs is they go stale the moment you stop actively maintaining them. and the honest truth is most people stop maintaining them pretty quickly.

so instead of relying on discipline, i wired it into the workflow. every doc has frontmatter that declares what code it describes:

---
project: ios
watches: ios/Features/Inbox/**, ios/Core/Network/**
lastVerified: a3f9c12
verifiedDate: 2026-04-20
---

watches is a glob pattern over source paths. lastVerified is the git commit hash when i last checked this doc.

doc_sync.js runs at session start: diffs lastVerified against HEAD per project, filtered by watches. if watched files changed, the doc is flagged stale. you get a list of exactly which docs need attention — not all of them, just the ones where the underlying code actually changed.

the workflow: read the diff, update the doc if needed, run --mark-current to stamp it with the new HEAD. stale docs are a session-start action item, not a quarterly effort.

one more thing worth building: a doc_sync_prompt.md template. when doc_sync.js flags a doc as stale, you need to give Claude a consistent prompt for reviewing it. the template fills in {{DOC_PATH}}, {{GIT_DIFF_STAT}}, {{CHANGED_FILES}}, and {{DOC_CONTENT}} — Claude reads the diff, decides what changed, updates only what is wrong or outdated, and preserves the frontmatter format. without a template you end up writing a different prompt every time and the quality of the review varies. one template file in scripts/, referenced whenever /sync runs.

Task management across platforms

one file per platform. ios_todos.md, android_todos.md, win_todos.md. same structure in all of them:

## High Priority
- [ ] Fix session ID bug in TIBConverseInteractor.swift:83

## Medium Priority
- [ ] Add unit test target

## Low Priority
- [ ] Refactor legacy auth flow

## Completed
- [x] 2026-04-20 — Migrated Localizable strings

there is also daily.md — today’s focus, separate from the long-running backlogs. daily_reset.sh resets it each morning, carries over anything incomplete from yesterday, and pulls the top items from each project’s High Priority section so you are never starting from blank. at end of day you move done items back to the project file and carry over the rest.

it is not rocket science but it works because everything is in one place and Claude can read all of it directly — no context switching, no “go check Linear”, no copy-pasting.

Memos, KT notes, and changelogs

these three are the most underrated parts of the system. they get skipped when people think about “what does an AI need to know” but they are exactly what the AI is missing when it gives you advice that misses context.

Memos (memo/) are for anything that does not fit in a doc or a todo. decision logs, architecture choices, research, migration plans, meeting outputs. the key thing about a memo is it captures the why. a doc says “the auth middleware works like this”. a memo says “we rewrote the auth middleware because legal flagged the session token storage in April”. without the memo Claude treats every piece of code as a deliberate, still-valid decision. with the memo it knows what is intentional and what is technical debt inherited from a compliance scramble.

KT notes (memo/kt/<platform>/YYYY-MM-DD_topic.md) are specifically for inheriting a codebase. when someone does a knowledge transfer session, you write it up here. when you figure out something non-obvious about how the code works, you write it up here. these are the things that would take a new person weeks to discover by reading code — undocumented conventions, “we don’t touch that file because”, quirks of the build system, context behind a weird architectural choice. writing them down once means Claude knows them forever.

Changelogs (changelog/<project>.md) are append-only per-project ship logs:

| 2026-04-15 | Migrated inbox to VIPER          | PR #441 |
| 2026-04-08 | Upgraded to AGP 8.3              | PR #438 |
| 2026-03-22 | Added push notification handling | PR #421 |

one row per notable change. the practical use: “did we ship X on all platforms yet?” — you check the changelog instead of grepping git history across five repos. also useful at standup when someone asks what shipped last week.

The local web dashboard

the dashboard is a local Node.js server. no framework, no build step, runs offline, starts in two seconds.

node .ops/dashboard/server.js
# opens at localhost:3000

File browser — tree sidebar over all docs, todos, memos. files render as Markdown. todo files have live checkboxes — clicking one calls POST /api/toggle and writes the change directly to disk.

Git status panel — polls all repos in parallel. branch, last commit, time ago, dirty file count.

Full-text search — index built at startup from every .md, .txt, .sh file. AND-matched with scoring. returns results with line-number snippets. useful when you remember something exists but can not remember which doc it is in.

Doc staleness indicators — green/yellow/red dots next to each doc in the sidebar based on doc_sync.js output. a resync button re-runs the script and refreshes the cache.

Task creation — a form on every page to add a todo at any priority level to any project. finds the right heading and inserts the item, updates the Last updated: stamp.

Shape it to your problems — the CMD tabs and RSS feeds

here is the thing: everyone’s pain is different. the folder structure and scripts above are the common base. but the reason this actually works day-to-day is that you can add whatever else you actually need on top.

for me, the two things i added that made the biggest difference:

CMD view — xterm.js + node-pty over WebSocket. a real terminal embedded in the browser, one tab per project. each tab opens a PTY session in that project’s directory. per-project quick-command buttons — you configure a label and a shell command, they appear as buttons above the terminal. so Build Debug runs ./gradlew assembleDebug in the Android tab. Sync Pods runs pod install in the iOS tab. i click once, watch it run. no switching windows, no remembering the exact command flags.

before this i was constantly switching terminal windows and losing track of which one was which. now everything is in one browser tab.

RSS feeds / newsletters — each platform has its own dev newsletter and release channel. iOS dev forum, Android releases, Kotlin blog. i added an RSS tab. feed URLs live in a feeds.json file, keyed by platform:

{
  "ios": [
    { "label": "iOS Dev Weekly", "url": "https://iosdevweekly.com/issues.rss" },
    { "label": "Swift Blog", "url": "https://swift.org/atom.xml" }
  ],
  "android": [
    { "label": "Android Developers Blog", "url": "https://feeds.feedburner.com/blogspot/hsDu" }
  ]
}

the server fetches them server-side (handles redirects, CDATA stripping), renders as cards per platform. i stop by when i want to catch up. no separate app, no subscriptions, no algorithm deciding what i see — just the feeds i actually want, inside the same tab i already have open.

neither of these exist in anyone else’s command center because they are solving my specific workflow pain. the point is the base layer gives you the foundation. the top layer is yours to build.

other ideas i have seen or thought about that i haven’t built yet: a meeting notes tab that auto-stamps today’s date, a platform-specific analytics panel, a PR review queue for when you work with a team.

The two-tier AI model

the local web dashboard has a built-in AI chat powered by Mistral 7B via Ollama — not Claude. this is the layer that routes cheap questions away from the cloud.

the RAG pipeline:

question
   │
   ▼
embed ──► LanceDB vector search ──► top-k doc chunks
                                          │
                                          ▼
                             Mistral 7B ◄── context + question
                                          │
                                          ▼
                                    streamed answer
                               (with source file citations)

at startup the server walks all docs, chunks them, embeds them and stores the index in LanceDB. conversation history (last 12 turns) is passed with each request. topics can be filtered per platform.

but here is the part that matters more — the local model is also wired directly into Claude as an MCP tool. not just the dashboard chat, but Claude itself can call it:

search_docs(query, project?)  — semantic search over the LanceDB index
ask_local(question, project?) — full RAG query to Mistral 7B

so when you ask Claude “where is the WebSocket manager?” Claude does not think about it, does not run three tool calls, does not burn tokens. it calls ask_local, gets the answer back from the local model as a tool response, and continues. the routing decision is encoded in CLAUDE.md as explicit rules so it happens automatically:

You
 │
 ├── Complex reasoning ──────────────────► Claude (API tokens)
 │    debugging, architecture,
 │    multi-file refactoring, codegen
 │
 └── Lookups + summaries ──► local MCP ──► Mistral 7B (free, local)
      "where is X?", todos,
      file summaries, templates

questions that go local: “where is ClassName defined”, “what files are in folder X”, “summarise this file”, “what todos are open for Android”, “what is the VIPER template for a new scene”, anything answerable by reading the existing docs.

questions that use Claude: multi-file refactoring, debugging across call chains, cross-platform analysis with real reasoning, writing new features.

in practice around 60–70% of session queries route to the local model. those run free on my machine. Claude gets the work that actually needs it.

Tracking what you saved

there is one more hook worth adding: a PostToolUse hook on the local MCP calls. every time Claude calls ask_local or search_docs, a small Python script logs the call to a token_savings.jsonl file with a timestamp, the tool used, and an estimated token count saved:

{"ts": "2026-04-26T10:32:11", "tool": "ask_local",    "estTokensSaved": 400}
{"ts": "2026-04-26T10:33:45", "tool": "search_docs",  "estTokensSaved": 250}

the same hook also outputs a reminder back into Claude’s context: “you just used the local model — append [tib-mcp-info] to the sentence in your response that came from this result.”

that [tib-mcp-info] tag in the response is how you know which parts Claude answered from local knowledge vs the local model. it is easy to skip but worth keeping — after a few weeks you can look at the JSONL and get a rough sense of how many tokens the routing saved. it also keeps you honest about whether the local model is actually being used or whether Claude is quietly doing everything itself.

The session cache — picking up exactly where you left off

the session briefing knows “what was worked on last session” because /callitaday writes a session_summary.json at the end of each day. the structure:

{
  "date": "2026-04-22",
  "platform": "ios",
  "done": [
    "Settings flatten complete — SettingsSUI/NewUI/Settings_base merged into Features/Settings",
    "Helpers restructured — Contacts moved to Features/Contacts"
  ],
  "carriedOver": [
    "Android: edge to edge mandate for Play Store — not checked yet"
  ],
  "decisions": [
    "Contacts gets Features/Contacts/ not buried in Helpers",
    "URLSchemeAnalyser lives in Core/DeepLinker/"
  ],
  "openQuestions": [
    "CustomContextMenu still needs to move to Features/Inbox/Actions/"
  ],
  "keyFiles": [
    "native/TeamInbox.xcodeproj/project.pbxproj",
    "native/TeamInbox/Features/Settings/"
  ]
}

next morning, session_context.sh reads this file and includes the done, carriedOver, decisions, and openQuestions fields in the briefing. Claude starts the session knowing exactly where things were left — no re-reading git log, no “what were we working on?”. the keyFiles field is useful if you want Claude to immediately orient to the relevant parts of the code.

/callitaday is the slash command that writes this. it wraps the session: moves done items from daily.md back to the project todo files, carries over incomplete items, writes the JSON. it is the last thing you run before closing the terminal.

Setting this up yourself

the minimum version of this is five files and an afternoon:

1. create a parent workspace folder above all your repos
2. add a .ops/ folder with docs/, todo/, memo/, scripts/
3. write a CLAUDE.md at the workspace root — folder layout, git command prefixes, working conventions, routing rules
4. write session_context.sh or a simple briefing script that runs git -C <project>/ status across all repos and prints a summary — hook it to session start
5. write one doc per project covering the folder structure and architecture, add the watches frontmatter

that is the base. that alone kills the “re-explain everything every session” problem and the “docs live in Notion somewhere” problem.

layer on top in order of payoff:

• daily_reset.sh and the daily.md workflow — probably adds the most to day-to-day sanity
• doc_sync.js — if you are writing docs and want them to stay honest
• the dashboard — once you want a visual layer over all of it
• the CMD tabs — if you are constantly switching terminal windows for the same commands
• the local model + MCP — when token pressure is real and your doc library is large enough to justify a RAG pipeline

do not build all of it at once. start with the folder structure and the CLAUDE.md. add the rest as you actually feel the pain they solve.

What changed

before: open the right repo in Xcode, find the right Notion page, check Slack for where i left off, re-explain the codebase to Claude, watch the first 30% of my context window fill with boilerplate before writing a single line of actual code.

after: one terminal, one browser tab, one Claude session. the Command Center has the state of every repo, every doc, every task, every recent decision — and the cheap questions never reach the cloud.

the whole system is about 1,500 lines of Node.js, a handful of shell scripts, and Markdown files. no heavy dependencies, no cloud services, runs entirely offline.

if you are managing more than two active repos and you are constantly re-orienting your AI every session — this pattern is worth trying. you do not have to build the whole thing. start with the folder structure and a CLAUDE.md. that alone will change how your sessions feel.

the rest you will figure out as you go, shaped around whatever is actually slowing you down. that is the point.

a note on this post — the ideas, the frustration, the architecture, the decisions are all mine. i used Claude to help structure and articulate things i already knew but was too lazy to write out properly. felt right to mention it given the whole post is about working with AI. use your tools.

after writing this i came across andrej karpathy’s wiki pattern — same instinct around plain files, single source of truth, readable by humans and machines. worth looking up if this resonated.

Want to generate diagrams directly in Claude? Here is the fast track configuration for your claude_desktop_config.json:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": [
        "-y",
        "@drawio/mcp"
      ]
    }
  }
}

Restart Claude Desktop, and then ask: “Create a flowchart for a user login system.”

Why Draw.io with Claude?

If you are like me, explaining architecture or complex flows in text can get wordy and confusing. “Component A talks to B, which then signals C…” is much harder to parse than a simple arrow connecting boxes.

The Official Draw.io MCP Server (@drawio/mcp) bridges this gap. It allows Claude to:

1. Generate Diagrams: Create flowcharts, sequence diagrams, and system architectures from scratch.
2. Edit Existing Diagrams: Update diagrams based on new requirements.
3. Render Visuals: See the diagram directly in the chat interface (depending on the client support).

This is a game-changer for documentation, brainstorming, and technical specs.

Prerequisites

Before we start, ensure you have the following:

• Claude Desktop App: Installed on your Mac or Linux machine.
• Node.js: Version 18 or higher.
  • Check your version: node -v
  • If missing, I recommend using nvm (Node Version Manager) to install it.

Step-by-Step Setup Guide

1. Locate Configuration File

You need to edit the highly specific claude_desktop_config.json file.

On macOS: Open your terminal and run:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

(Or use nano, vim, or open -e if you don’t use VS Code)

On Linux: The file is typically located at:

~/.config/Claude/claude_desktop_config.json

2. Add the Draw.io Server

Add the following entry to the mcpServers object in your config file. If the file is empty, wrap it in curly braces.

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": [
        "-y",
        "@drawio/mcp"
      ]
    }
  }
}

What is this doing?

• It tells Claude to run the npx command.
• The -y flag automatically creates the environment without prompting.
• @drawio/mcp is the official package containing the server logic.

3. Restart Claude

For the changes to take effect:

1. Close the Claude Desktop interface completely.
2. Re-open it.

You should see a generic “MCP” icon or indicator (depending on your version) showing that tools are loaded.

Alternative: Setup with Claude Code CLI

If you prefer using the Claude Code CLI (command line interface) instead of the Desktop app, you can add the server directly using the claude mcp add command.

This is particularly useful if you want to scope the tool to a specific project or your user account without editing JSON files manually.

One-Line Setup

Run this command in your terminal:

claude mcp add drawio --scope user -- npx -y @drawio/mcp

Breakdown of the command:

• claude mcp add drawio: Tells Claude to add a new MCP server named “drawio”.
• --scope user: Installs it globally for your user account (use --scope project to install for the current folder only).
• --: Separator indicating the start of the actual server command.
• npx -y @drawio/mcp: The command to run the Draw.io server.

Once added, you can verify it with:

claude mcp list

How to Use It

Once connected, you can converse with Claude naturally about diagrams.

Creating a New Diagram

Prompt:

“Create a sequence diagram for an OAuth 2.0 authentication flow involving a User, Client App, Authorization Server, and Resource Server.”

Claude will generate the XML or specific format required for Draw.io and often provide a link or a rendered view.

Editing a Diagram

If you have a diagram file (e.g., XML) in your project context, you can ask Claude to modify it.

Prompt:

“Update the attached architecture diagram to include a Redis cache layer between the API and the Database.”

Complex Visualizations

You aren’t limited to simple boxes. You can ask for:

• Mind Maps: “Create a mind map for a marketing strategy.”
• ER Diagrams: “Generate an Entity-Relationship diagram for an e-commerce database schema.”
• Network Topologies: “Draw a high-availability AWS network setup with public and private subnets.”

Troubleshooting

“Command not found: npx”

If Claude complains it can’t find npx, you might need to provide the absolute path.

1. Run which npx in your terminal. (e.g., /usr/local/bin/npx)
2. Update your config:

   "drawio": {
     "command": "/usr/local/bin/npx",
     "args": ["-y", "@drawio/mcp"]
   }
   

Server Error / Disconnection

If the server crashes, check your Node.js version. The Draw.io MCP server requires a modern Node environment. Ensure node -v returns v18.x.x or newer.

Resources

• Official Draw.io MCP GitHub Repository
• Model Context Protocol Documentation
• Draw.io Website

Already know what Serena is? Here’s the fast track:

# 1. Install uv and Serena
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc
uv tool install git+https://github.com/oraios/serena

# 2. Restart terminal, then connect to your project
cd /path/to/your/project
claude mcp add serena -- serena-mcp-server --project $(pwd)
echo ".serena/" >> .gitignore

# 3. Start Claude
claude --allowedTools "mcp__serena*"

Then tell Claude: “Use Serena to onboard this project.”

Want to understand what this does and why? Read on.

A Quick Note

This is a continuation of my Claude Code notes. If you haven’t read that yet, I recommend starting there for the fundamentals. This article focuses on a specific optimization that has dramatically improved my Claude Code experience.

What you’ll learn:

• Why Claude Code can get expensive on large codebases
• How Serena uses LSP to provide semantic code navigation
• Step-by-step setup (takes ~5 minutes)
• Practical usage patterns and prompts
• When to use Serena vs. vanilla Claude Code

The Problem: Token Costs Add Up Fast

If you’ve been using Claude Code for a while, you’ve probably noticed that token costs can spiral quickly - especially on large codebases. Here’s why:

When you ask Claude something like “Where is the authentication logic?”, it often:

1. Reads entire files to understand context
2. Scans through multiple modules looking for patterns
3. Sometimes re-reads files it already looked at

For a medium-sized project (50k+ lines of code), a single exploration session can consume thousands of tokens just reading files. Multiply that across a day’s work, and you’re looking at serious costs.

Worse, when the context window fills up, Claude can start hallucinating - referencing functions that don’t exist or suggesting patterns that don’t match your codebase.

Enter Serena: Semantic Code Navigation

Serena is an open-source MCP (Model Context Protocol) server that gives Claude Code semantic understanding of your codebase. Instead of reading entire files, Claude can now:

• Jump directly to function definitions
• Find all usages of a class or method
• Navigate imports and dependencies
• Understand type hierarchies

It does this by leveraging LSP (Language Server Protocol) - the same technology that powers your IDE’s “Go to Definition” and “Find All References” features.

The Results?

In my testing on a ~100k line Android/KMP project:

That 70% isn’t marketing fluff - it’s real savings from not reading entire files when you only need specific symbols.

How Serena Works Under the Hood

MCP servers extend Claude’s capabilities through a standardized protocol (see Glossary if this is new to you). Serena specifically provides:

1. Code Indexing: When you connect Serena to Claude, it automatically builds an index of your codebase’s symbols, types, and relationships.

2. LSP Integration: Serena wraps language servers (for Kotlin, TypeScript, Python, etc.) to provide semantic navigation.

3. Smart Querying: When Claude asks “Where is UserRepository?”, Serena returns the exact file and line number - not a file dump.

4. Live Updates: The index updates as you modify code, staying in sync with your project.

┌─────────────────┐      MCP Protocol      ┌─────────────────┐
│   Claude Code   │ ◄──────────────────────► │     Serena      │
│    (Client)     │                          │   (MCP Server)  │
└─────────────────┘                          └────────┬────────┘
                                                      │
                                                      │ LSP
                                                      ▼
                                             ┌─────────────────┐
                                             │  Language Server │
                                             │  (kotlin-ls,    │
                                             │   tsserver, etc) │
                                             └─────────────────┘

One-Time Setup

Prerequisites

• Claude Code CLI installed (see my setup guide)
• A supported project (Kotlin, TypeScript, Python, Go, Rust, and more)

Step 1: Install uv Package Manager

Serena uses uv for installation. If you don’t have it:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Why uv? It’s a fast Python package manager that handles Serena’s dependencies cleanly.

Step 2: Install Serena Tools

Install the CLI tools globally:

uv tool install git+https://github.com/oraios/serena

This gives you two commands:

• serena - Project management CLI
• serena-mcp-server - The MCP server that Claude connects to

Step 3: Restart Your Terminal

Important: After installing uv and Serena, close all terminal windows and open a fresh one. This ensures your shell recognizes the new commands.

I spent time debugging “command not found” errors only to realize a terminal restart fixed everything. Save yourself the frustration.

# Close all terminals, then open a new one and verify
which serena
which serena-mcp-server

Both should return valid paths. If not, try running source ~/.zshrc (or ~/.bashrc).

Step 4: Connect Serena to Claude Code

Navigate to your project root and register Serena as an MCP server:

cd /path/to/your/project

# Add the server (this also initializes the project index automatically)
claude mcp add serena -- serena-mcp-server --project $(pwd)

What this does:

• Registers Serena as an MCP server for Claude
• Auto-initializes the project index (creates .serena/ folder)
• Scans your codebase for symbols, types, and relationships

Initial indexing time depends on project size:

You can monitor progress at http://localhost:24282 during indexing.

Important: Add .serena/ to your .gitignore. This folder is local cache and shouldn’t be committed.

echo ".serena/" >> .gitignore

Verify it’s connected:

# Check MCP server status
claude mcp list

You should see serena in the list with a green status.

Handling Permission Prompts

When you start using Serena with Claude Code, you’ll encounter multiple permission prompts. Claude asks for approval each time Serena wants to:

• Read files
• Navigate to definitions
• Search for symbols
• Access the index

This is good for security, but can get tedious during intensive coding sessions.

Option 1: Approve Permissions Individually (Recommended for Learning)

When starting out, approve each permission manually. This helps you understand what Serena is doing and builds trust in the tool.

Option 2: Auto-Accept Permissions for Serena

If you trust Serena and want a smoother experience, you can configure Claude to auto-accept its tool calls:

# Start Claude with auto-accept for the current session
claude --allowedTools "mcp__serena*"

This allows all Serena MCP tools without prompting, while still prompting for other potentially dangerous operations.

Option 3: Dangerously Skip All Permissions (Use with Caution)

For experienced users who understand the risks:

# Skip ALL permission prompts (not just Serena)
claude --dangerously-skip-permissions

Warning: This flag bypasses ALL safety prompts - file writes, shell commands, everything. Only use this if:

• You’re on a development machine (not production)
• You understand Claude can modify/delete files without asking
• You’re working in a git-tracked project (easy to revert mistakes)
• You trust your judgment to review changes before committing

For most users, Option 2 (--allowedTools "mcp__serena*") is the sweet spot - smooth Serena experience while keeping other safeguards in place.

Using Serena with Claude Code

Starting a Session

# Navigate to your project
cd /path/to/your/project

# Start Claude with Serena connected
claude

Onboarding Claude to Your Project

The first time you use Serena on a project, run this prompt:

Use Serena to onboard this project. Understand the architecture,
main modules, and key entry points.

Claude will use Serena’s semantic capabilities to build a mental model of your codebase - without reading every file.

Practical Examples

Finding specific implementations:

Where is the UserRepository interface implemented?

Without Serena: Claude reads multiple files guessing where implementations might be. With Serena: Claude jumps directly to the concrete class.

Understanding call hierarchies:

What functions call the `syncUserData()` method?

Serena traces all callers semantically, giving Claude precise context.

Navigating multi-module projects:

How does the :feature:auth module communicate with :core:network?

Serena understands module boundaries and can trace cross-module dependencies.

Monitoring and Debugging

Live Dashboard

Serena provides a local web dashboard for monitoring and debugging:

http://localhost:24282

Open this URL in your browser while Serena is running. You’ll see:

Index Status Panel

• Total symbols indexed (classes, functions, variables)
• Indexing progress percentage
• Last index update timestamp
• Any indexing errors or warnings

Query Logs

• Real-time log of Claude’s queries to Serena
• Which symbols were requested
• Response times for each query
• Helps you understand what Claude is “thinking”

Language Server Status

• Connected language servers (kotlin-ls, tsserver, etc.)
• Server health and memory usage
• Restart buttons if a server becomes unresponsive

Cache Statistics

• Hit/miss ratios
• Memory usage
• Option to clear cache if things get stale

Tip: Keep the dashboard open in a browser tab during intensive coding sessions. If Claude seems confused or slow, check the dashboard - you might spot a language server that crashed or an indexing error.

Serena Tools Available to Claude

When connected, Claude gains access to these MCP tools (you can see these with claude mcp list):

Claude automatically chooses the right tool based on your question.

Troubleshooting Common Issues

“command not found: serena” after installation:

This is the most common issue. Your terminal doesn’t know about the new commands yet.

# Option 1: Reload shell config
source ~/.zshrc  # or ~/.bashrc

# Option 2 (recommended): Close ALL terminal windows and open a fresh one
# This ensures a clean shell environment

“1 MCP server failed” error:

# Remove and re-add the server
claude mcp remove serena
claude mcp add serena -- serena-mcp-server --project $(pwd)

Index out of sync:

# Rebuild the index
serena project update --name <your-project-name>

Server not starting:

Make sure you’re in the correct project root where you ran the claude mcp add command.

Language not supported:

Check Serena’s supported languages. For Android/KMP projects, Kotlin support works out of the box.

Tip: Simplify with Aliases

These Serena commands are verbose. If you find yourself typing them often, consider setting up shell aliases or using a tool like Aliasly to manage shortcuts across projects.

Best Practices

1. Keep Your Index Updated

After major refactors or pulling new changes:

serena project update --name <your-project-name>

2. Use Specific Queries

Instead of:

How does authentication work?

Try:

Show me the AuthViewModel and its dependencies using Serena.

The more specific your query, the better Serena can target the exact symbols.

3. Combine with CLAUDE.md

Your CLAUDE.md file complements Serena perfectly. Use CLAUDE.md for:

• Project conventions and coding standards
• Build commands and configuration
• Architecture overview

Use Serena for:

• Navigating actual code
• Finding implementations
• Tracing dependencies

4. Monitor Your Savings

Use /cost in Claude Code to track your token usage. Compare sessions before and after Serena to see the actual savings.

Comparison: Claude Code vs. Claude Code + Serena

Supported Languages

Serena works with any language that has LSP support. Here’s the current status:

For Android/KMP projects, Kotlin support is what matters most - and it works great.

Note: Serena auto-detects your project’s languages and starts the appropriate language servers. You don’t need to configure this manually.

Updating and Managing Serena

Update Serena to Latest Version

uv tool upgrade serena

Rebuild Project Index

After major refactors, dependency updates, or pulling large changes:

serena project update --name <your-project-name>

Remove Serena from a Project

# Remove MCP server from Claude
claude mcp remove serena

# Delete the local index (optional)
rm -rf .serena/

Working with Multiple Projects

Serena indexes are project-specific. To switch between projects:

# Project A
cd /path/to/project-a
claude mcp add serena -- serena-mcp-server --project $(pwd)

# Project B (in a different terminal/session)
cd /path/to/project-b
claude mcp add serena -- serena-mcp-server --project $(pwd)

Each project maintains its own .serena/ index.

When NOT to Use Serena

Serena isn’t always the best choice:

• Small scripts or single-file projects: The overhead of indexing doesn’t pay off
• Heavily dynamic languages: LSP works best with typed languages
• Quick one-off questions: Sometimes just asking Claude directly is faster
• Non-code tasks: Documentation, git operations, etc. don’t benefit from Serena

Use judgment - Serena is a tool for navigating complex codebases, not a universal solution.

Integration with My Workflow

Here’s how Serena fits into my daily Claude Code usage:

1. Morning context building: “Use Serena to show me what I worked on yesterday in the :feature:dashboard module”

2. Feature development: “Using Serena, find all places where we handle network errors and show me the patterns”

3. Code review: “Navigate to the UserService implementation and review it for potential issues”

4. Debugging: “Trace all callers of processPayment() and identify where the null check might be failing”

5. Onboarding teammates: “Use Serena to explain the data flow from API response to UI state”

Cost Analysis

Let’s break down the real savings. With Claude Sonnet at ~$3/1M input tokens:

These are conservative estimates. For larger codebases or Opus usage, savings multiply significantly.

Setup Checklist

Quick reference for new projects:

• Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• Install Serena: uv tool install git+https://github.com/oraios/serena
• Restart terminal (close all windows, open fresh)
• Verify install: which serena && which serena-mcp-server
• Connect to Claude (auto-creates index): claude mcp add serena -- serena-mcp-server --project $(pwd)
• Add to .gitignore: echo ".serena/" >> .gitignore
• Test connection: claude mcp list
• Start Claude: claude (or claude --allowedTools "mcp__serena*" to auto-accept Serena permissions)
• Onboard Claude: “Use Serena to onboard this project”

Resources

• Serena GitHub Repository
• Model Context Protocol Documentation
• My Claude Code Notes
• LSP Specification

Final Thoughts

Serena has become an essential part of my Claude Code setup. The token savings are nice, but the real value is better context preservation. Claude makes fewer mistakes when it has precise semantic information instead of guessing from partial file reads.

If you’re working on any non-trivial codebase - especially multi-module Android/KMP projects - give Serena a try. The 10-minute setup pays for itself within the first session.

As always, remember: AI is a copilot, not a pilot. Serena makes the copilot more efficient, but you’re still in control.

This article is a living document. Last updated: February 2026

Glossary

New to some of these terms? Here’s a quick reference:

MCP (Model Context Protocol)

Model Context Protocol is an open standard created by Anthropic that allows AI assistants (like Claude) to connect to external tools and data sources. Think of it as a “USB port” for AI - any tool that implements MCP can plug into Claude and extend its capabilities.

Example: Serena is an MCP server. When you run claude mcp add serena, you’re telling Claude “hey, there’s a new tool you can use.”

Learn more

LSP (Language Server Protocol)

Language Server Protocol is a standard created by Microsoft that powers IDE features like:

• “Go to Definition” (Ctrl/Cmd + Click)
• “Find All References”
• Auto-completion
• Syntax errors and warnings

Instead of each IDE implementing these features separately for every language, LSP provides a common interface. Your IDE talks to a “language server” that understands the specific language.

Example: When you Ctrl+Click a function in VS Code and it jumps to the definition - that’s LSP in action. Serena uses this same technology to give Claude semantic code navigation.

Learn more

uv

uv is a fast Python package and project manager created by Astral. It’s like npm for Python, but significantly faster (written in Rust).

Why Serena uses it: Serena is a Python project. uv tool install installs CLI tools globally, similar to npm install -g.

Key commands:

# Install a tool globally
uv tool install package-name

# Install from git repository
uv tool install git+https://github.com/user/repo

# Update a tool
uv tool upgrade package-name

Learn more

Tokens

Tokens are the fundamental units that AI models process. Roughly:

• 1 token ≈ 4 characters in English
• 1 token ≈ 0.75 words
• 100 tokens ≈ 75 words

When you send a prompt to Claude, it counts tokens. When Claude responds, it generates tokens. Both cost money with the API.

Why this matters: If Claude reads a 1000-line file to answer a simple question, that’s a lot of tokens wasted. Serena helps Claude read only what it needs.

Context Window

The context window is the maximum amount of text (in tokens) that an AI model can “remember” during a conversation. Think of it as the AI’s working memory.

Why this matters: When the context window fills up, older information gets “forgotten” or summarized. With large codebases, this can cause Claude to lose track of important details. Serena’s efficient queries help preserve context.

Semantic vs. Syntactic

• Syntactic: Understanding code as text/patterns (like grep searching for “function”)
• Semantic: Understanding code’s meaning and relationships (knowing that UserRepository implements Repository<User>)

Serena provides semantic navigation - it understands your code’s structure, not just the text.

Index / Indexing

When Serena “indexes” your project, it’s building a searchable database of your code’s structure:

• All classes, functions, and variables
• Their locations (file + line number)
• Their relationships (what calls what, what implements what)

This is similar to how search engines index websites - they pre-process content so searches are fast.

CLI (Command Line Interface)

A CLI is a text-based interface for interacting with software. Instead of clicking buttons in a GUI, you type commands.

Examples:

• git - Version control CLI
• npm - Node.js package manager CLI
• claude - Claude Code’s CLI

MCP Server vs. Client

In the MCP architecture:

• Client: The AI assistant (Claude Code) that uses tools
• Server: The tool that provides capabilities (Serena, file system access, etc.)

When you run claude mcp add serena, you’re registering Serena as a server that Claude (the client) can connect to.

Questions or feedback? Reach out:

• Email
• Website

This article is primarily a self-note that I keep updating as I learn more about Claude Code. The AI tooling landscape evolves rapidly, so some information might be outdated by the time you read this. If you find something that needs updating, feel free to reach out!

Whether you’re a junior developer just getting started or a senior developer looking to boost your workflow, Claude Code has something for everyone.

Why Should You Care?

If you’ve read my Solutionist Mindset talk, you know I believe in using AI as a copilot, not a pilot. Claude Code embodies this philosophy perfectly—it’s a CLI tool that sits alongside your existing workflow, helping you move faster while keeping you in control.

For Android and Compose Multiplatform (KMP) developers like us, having a tool that understands our codebase context is game-changing. Gradle configurations, multi-module architectures, platform-specific implementations—Claude Code can navigate all of this.

What is Claude Code?

Claude Code is Anthropic’s official CLI tool that brings Claude directly into your terminal. Unlike the web interface, it:

• Has full access to your codebase (with your permission)
• Can read, write, and edit files directly
• Runs shell commands for you
• Understands project context across multiple files
• Integrates with Git for version control operations

Think of it as having a senior developer sitting next to you who can:

• Explore your codebase instantly
• Write and refactor code
• Debug issues by reading logs and stack traces
• Create commits and PRs
• Explain complex code sections

Latest Updates (January 2026)

Update available for Claude Code users (v: 2.1.2)!

Model Selection

Opus 4.5 is now available in model selection. While Sonnet is superior for general coding tasks, Opus is amazing for complex features and crazy bugs. You can use -m flag for selecting a specific model for particular task sessions.

[!WARNING] Token Usage Warning: Continuous usage of Opus models will consume your rate limits and quota significantly faster (approx. 5-10x) than Sonnet. Use Opus only for complex debugging or architectural tasks.

# Run with a specific model
claude -m claude-opus-4-20250514

Official Plugins

Check out the official plugins:

• All Plugins
• Code Review Plugin

Getting Started

Installation

# Using npm
npm install -g @anthropic-ai/claude-code

# Using Homebrew (macOS)
brew install claude-code

After installation, run claude in your terminal to start an interactive session. You’ll need to authenticate with your Anthropic API key or use the claude --login command to login via the browser.

Basic Usage

Navigate to your project directory and simply run:

claude

This starts an interactive session where you can ask questions, request code changes, or explore your codebase.

Essential Commands Every Developer Should Know

1️⃣ Slash Commands

Claude Code has built-in slash commands that trigger specific workflows:

2️⃣ The CLAUDE.md File

One of the most powerful features for multi-module Android/KMP projects is the CLAUDE.md file. Create this at your project root:

# Project: MyKMPApp

## Architecture
- Multi-module KMP project
- Shared module: commonMain, androidMain, iosMain
- Android app module with Jetpack Compose UI
- iOS app using SwiftUI

## Key Conventions
- Use Koin for dependency injection
- Room for local database (Android), SQLDelight for shared
- Ktor for networking
- Kotlin Coroutines + Flow for async operations

## Build Commands
- `./gradlew assembleDebug` - Build Android debug
- `./gradlew :shared:build` - Build shared module only
- `./gradlew connectedAndroidTest` - Run instrumented tests

## Module Structure
- :app - Android application entry point
- :shared - KMP shared code
- :feature:home - Home feature module
- :feature:settings - Settings feature module
- :core:network - Networking utilities
- :core:database - Database layer

Claude reads this file and uses it as persistent context for every conversation. This is incredibly useful for:

• Multi-module navigation - Claude knows your module structure
• Consistent coding patterns - Follows your conventions
• Faster builds - Knows the right Gradle commands

3️⃣ Vim-Style Keybindings

For terminal enthusiasts, Claude Code supports vim keybindings:

Practical Use Cases for Android/KMP Developers

Use Case 1: Exploring Unfamiliar Codebases

When you join a new project or inherit legacy code:

You: How is the authentication flow implemented in this app?
     Show me the key files involved.

Claude will search through your codebase, identify relevant files (ViewModels, Repositories, API services), and explain the flow.

Use Case 2: Writing Compose UI Components

You: Create a bottom sheet component for filtering products.
     It should have checkboxes for categories and a price range slider.
     Follow our existing design system in :core:designsystem module.

Claude will:

1. Look at your existing design system
2. Match the patterns and naming conventions
3. Create the component following your architecture

Use Case 3: Debugging Build Issues

You: I'm getting this Gradle error when building the shared module:
     [paste error here]

     Help me understand and fix it.

Claude can read your build.gradle.kts files, understand the dependency graph, and suggest fixes.

Use Case 4: Writing Platform-Specific Implementations

You: I need to implement biometric authentication.
     Create the expect/actual declarations for Android and iOS
     in the :core:auth module.

Claude understands KMP’s expect/actual mechanism and generates appropriate platform-specific code.

Use Case 5: Creating Git Commits

You: /commit

Claude will:

1. Analyze your staged changes
2. Understand the context of modifications
3. Generate a meaningful commit message
4. Create the commit

Use Case 6: Room Database Migrations

You: I need to add a 'lastSyncedAt' column to the UserEntity.
     Create the migration and update the entity.

Claude handles the boilerplate of Room migrations, which can be error-prone manually.

Best Practices for Effective Usage

✅ DO

1. Be specific with context - Instead of “fix this bug”, say “fix the crash in UserRepository.kt when the token expires” make sure you add the file and line-number of the function or scope.

2. Review generated code - Always understand what Claude writes. Don’t blindly accept suggestions.

3. Use it for exploration - Ask Claude to explain complex parts of your codebase or third-party libraries

4. Leverage for boilerplate - Let Claude handle repetitive tasks like:

   • Creating data classes from API responses
   • Writing Room entities and DAOs
   • Setting up Hilt/Koin modules
   • Creating navigation graphs
   • Writing unit test boilerplate

5. Maintain your CLAUDE.md - Keep it updated as your project evolves

6. Use the right model for the task - Haiku for quick questions, Sonnet for general coding, Opus for complex debugging

❌ DON’T

1. Don’t share sensitive data - Avoid passing API keys, secrets, or user data through Claude

2. Don’t skip the review - Especially for security-critical code (authentication, payment processing, encryption etc)

3. Don’t use it as a crutch - You should still understand the fundamentals. AI is a multiplier, not a replacement.

4. Don’t expect perfection - Claude can make mistakes. Treat its output as a starting point.

5. Don’t ignore Gradle sync - After Claude modifies build.gradle.kts, sync manually in Android Studio

Cost Management Tips

Claude Code uses API tokens, which cost money. Here’s how to optimize:

1️⃣ Choose the Right Model

2️⃣ Use /compact Regularly

Long conversations consume more tokens. Use /compact to summarize and reduce context.

3️⃣ Start Fresh for New Tasks

Use /clear when switching to unrelated tasks. No need to carry previous context.

4️⃣ Be Concise

Instead of:

"Hey Claude, I was wondering if you could maybe help me
understand how the user authentication works in this app,
like when someone logs in, what happens step by step?"

Try:

"Explain the login flow. Start from LoginViewModel."

6️⃣ Offload Tasks to Other Models/Tools (Save those Tokens!)

Not everything requires Claude Code’s deep context awareness. Save your tokens by routing tasks to the right tool:

• Use Gemini for Quick Concepts: Need to understand “How LruCache works internally” or “Explain the Builder pattern”? Use Gemini. It’s fast, free/cheap, and great for general knowledge that doesn’t need your private codebase context.
• Use ChatGPT for High-Level Project Questions: If you need advice on “Best practices for modularizing a KMP project” or architecture discussions where providing full code access isn’t necessary, ChatGPT is a great option.
• Use CLI Tools for Quick Answers: If you’re a terminal power user (using tmux, dia, etc.), tools like ddgr (DuckDuckGo from terminal) or Ollama (local models) are fantastic for quick lookups without leaving your flow.

[!TIP] Pro Tip: Reserve Claude Code for tasks that specifically need to read your files, understand your project structure, or perform edits. For everything else, cheaper (or free) alternatives often work just as well!

7️⃣ Check Costs with /cost

Regularly run /cost to monitor your usage.

Integration with Development Workflow

IDE Integration

Claude Code works alongside your IDE, not inside it. A typical workflow:

1. Have your IDE open (Android Studio / Fleet / IntelliJ)
2. Run Claude in a terminal (split screen works great)
3. Ask Claude to make changes
4. Review changes in IDE (they appear instantly)
5. Test and iterate

Git Workflow Integration

Claude Code integrates nicely with Git:

# Start a session
claude

# Create meaningful commits
You: /commit

# Create a pull request
You: Create a PR for these changes. The target branch is develop.

# Review code before pushing
You: Review the changes in the last commit for any issues.

Common Gotchas for Android/KMP Projects

1️⃣ Gradle Sync After Changes

When Claude modifies build.gradle.kts files, you’ll need to sync in Android Studio manually. Claude can’t trigger this for you.

2️⃣ Resource Files

Claude can create/modify XML resources (layouts, strings, drawables), but be careful with:

• Generated resources (R class) - These regenerate on build
• Vector drawables - Complex paths might need manual tweaking

3️⃣ Compose Preview

Claude-generated Compose components might need @Preview annotations added for visibility in Android Studio’s preview pane.

4️⃣ iOS-Specific Code

For KMP projects, Claude can write Swift/Objective-C code for iOS implementations, but:

• You’ll need Xcode to verify it compiles
• Swift interop with Kotlin can be tricky

5️⃣ Version Catalog

If you use libs.versions.toml, make sure Claude knows about it in your CLAUDE.md. Otherwise, it might use hardcoded versions.

My Personal Workflow

Here’s how I typically use Claude Code for Android development:

1. Morning exploration - “What did I work on yesterday? Show me recent changes.”

2. Feature development - Start with asking Claude to explore existing patterns, then implement following those patterns

3. Code review helper - “Review this ViewModel for potential memory leaks or coroutine issues”

4. Documentation - “Generate KDoc comments for the public methods in NetworkClient.kt”

5. Refactoring - “Migrate this callback-based API to use Kotlin Coroutines with Flow”

6. Test writing - “Write unit tests for UserRepository using MockK”

Advanced: MCP Servers

Claude Code supports Model Context Protocol (MCP) servers, which extend its capabilities. For Android developers, interesting MCPs include:

• File system access - Already built-in
• Git operations - Built-in
• Web search - For documentation lookups
• Custom tools - You can create your own MCP servers

Check out the MCP Documentation for more details.

Useful One-Liners

Quick commands I use frequently:

# Start with a specific model for complex tasks
claude -m claude-opus-4-20250514

# Resume last conversation
claude --resume

# Check installation health
claude /doctor

# Quick code review
claude "Review my staged changes for issues"

What’s Next?

This article covers the fundamentals, but Claude Code is constantly evolving. I plan to update this note as I discover:

• New features and capabilities
• Better workflows for KMP development
• Integration patterns with CI/CD
• Team collaboration strategies

Final Thoughts

Claude Code is a powerful addition to the Android/KMP developer toolkit. It’s not about replacing your skills—it’s about amplifying them. Use it to handle boilerplate, explore unfamiliar code, and move faster on repetitive tasks.

But remember: You are still the pilot. Claude is your copilot. Understand what it generates, review its suggestions, and keep learning the fundamentals.

The developers who thrive in the AI age won’t be those who code the fastest—they’ll be the ones who solve problems thoughtfully while leveraging every tool at their disposal.

Resources

• Official Claude Code Documentation
• Claude Code GitHub
• Official Plugins
• Model Context Protocol
• My Solutionist Mindset Talk

Feel free to connect with me on: 📩 Email 🌍 Website

I wish to keep this article as a living document. Last updated: January 2026

This guide will help you set up an automated code review system using Claude Code that runs before every git push, with the option to skip when needed.

Prerequisites

• Claude Code CLI installed and configured
• Git repository with proper remote setup
• Terminal access

Step 1: Create the Pre-Push Hook Script

Create a git hook that will run before every push:

# Navigate to your project root
cd /path/to/your/project

# Create the hooks directory if it doesn't exist
mkdir -p .git/hooks

# Create the pre-push hook file
touch .git/hooks/pre-push

# Make it executable
chmod +x .git/hooks/pre-push

Step 2: Generated Review Reports

Every code review automatically generates a timestamped markdown report with complete analysis:

Report Features

• Filename: claude-review-report_2025-08-20_14-30-45.md
• Complete History: All commits since main branch
• File Changes: List of all modified files
• Project Checks: Linting and type checking results
• Claude Analysis: Detailed security, bug, and quality review
• Action Checklist: Checkboxes for addressing issues

Sample Report Structure

# Claude Code Review Report

**Generated:** 2025-08-20 14:30:45
**Branch:** feature/new-ui
**Compared Against:** origin/main  
**Review Status:** ✅ Passed

## Commits Reviewed
- feat: add new user interface
- fix: resolve navigation bug
- test: add unit tests for new component

## Files Changed
- src/components/UserInterface.tsx
- src/navigation/Router.tsx  
- tests/UserInterface.test.tsx

## Project Checks
### Linting
✅ **Passed** - No linting issues found

### Type Checking
⚠️ **Issues Found** - See type checking output

## Claude Code Review Results
[Claude's detailed analysis here]

## Quick Actions
### If Issues Found:
- [ ] Fix security vulnerabilities
- [ ] Resolve critical bugs
- [ ] Address performance issues
...

Step 3: Write the Pre-Push Hook

Add the following content to .git/hooks/pre-push:

#!/bin/bash

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Check if SKIP_CLAUDE_REVIEW environment variable is set
if [ "$SKIP_CLAUDE_REVIEW" = "true" ]; then
    echo -e "${YELLOW}⚠️  Claude Code review skipped (SKIP_CLAUDE_REVIEW=true)${NC}"
    exit 0
fi

# Check if claude command is available
if ! command -v claude &> /dev/null; then
    echo -e "${RED}❌ Claude Code CLI not found. Install it first or skip with: SKIP_CLAUDE_REVIEW=true git push${NC}"
    exit 1
fi

echo -e "${YELLOW}🤖 Running Claude Code review before push...${NC}"

# Get the current branch
current_branch=$(git branch --show-current)

# Find the main/master branch
main_branch=""
if git show-ref --verify --quiet refs/heads/main; then
    main_branch="main"
elif git show-ref --verify --quiet refs/heads/master; then
    main_branch="master"
elif git show-ref --verify --quiet refs/remotes/origin/main; then
    main_branch="origin/main"
elif git show-ref --verify --quiet refs/remotes/origin/master; then
    main_branch="origin/master"
else
    echo -e "${YELLOW}⚠️  Could not find main/master branch, comparing with HEAD~1${NC}"
    main_branch="HEAD~1"
fi

# Check if there are any changes to review since main branch
if [ "$main_branch" != "HEAD~1" ] && git diff --quiet "$main_branch"..HEAD 2>/dev/null; then
    echo -e "${GREEN}✅ No changes detected since $main_branch${NC}"
    exit 0
elif [ "$main_branch" = "HEAD~1" ] && git diff --quiet HEAD~1 HEAD 2>/dev/null; then
    echo -e "${GREEN}✅ No changes detected since last commit${NC}"
    exit 0
fi

# Show what's being reviewed
echo -e "${YELLOW}📋 Reviewing changes in branch: $current_branch (since $main_branch)${NC}"
if [ "$main_branch" != "HEAD~1" ]; then
    echo -e "${BLUE}Commits to be reviewed:${NC}"
    git log --oneline "$main_branch"..HEAD
    echo -e "${BLUE}Files changed:${NC}"
    git diff --name-only "$main_branch"..HEAD
else
    git log --oneline -5
fi

echo -e "${YELLOW}📝 Running automated code review...${NC}"

# Run project-specific checks first
echo -e "${BLUE}🔧 Running project checks...${NC}"

# Linting
echo -e "${YELLOW}  → Running linter...${NC}"
if npm run lint || yarn lint 2>/dev/null; then
    echo -e "${GREEN}    ✅ Linting passed${NC}"
else
    echo -e "${YELLOW}    ⚠️  Linting issues found (will be reviewed by Claude)${NC}"
fi

# Type checking
echo -e "${YELLOW}  → Running type check...${NC}"
if npm run typecheck || yarn typecheck || tsc --noEmit 2>/dev/null; then
    echo -e "${GREEN}    ✅ Type checking passed${NC}"
else
    echo -e "${YELLOW}    ⚠️  Type issues found (will be reviewed by Claude)${NC}"
fi

# Create a temporary file for the review prompt
review_file=$(mktemp)
cat > "$review_file" << 'EOF'
Please perform a comprehensive code review of ALL changes in this branch before I push to the remote repository.

IMPORTANT: Review ALL commits since the main branch, not just the latest commit. 
Use 'git diff main..HEAD' and 'git log main..HEAD' to see all changes.

The following commits will be pushed:
$(git log --oneline main..HEAD 2>/dev/null || git log --oneline -5)

Files that have been changed:
$(git diff --name-only main..HEAD 2>/dev/null || git diff --name-only HEAD~1 HEAD)

Comprehensive review including security, bugs, performance, code quality, test coverage, and best practices. 

Please also run these project-specific commands and report any issues:
1. Linting: npm run lint || yarn lint
2. Type checking: npm run typecheck || yarn typecheck || tsc --noEmit
3. Tests: npm test || yarn test

Focus areas:
1. **Security issues** - Check for exposed secrets, SQL injection, XSS vulnerabilities
2. **Bug potential** - Logic errors, null pointer exceptions, edge cases  
3. **Code quality** - Following project conventions, proper error handling
4. **Performance** - Inefficient operations, memory issues
5. **All commits** - Review every commit since main branch, not just the latest one

If you find any critical issues, please list them clearly with file locations. 
If the code looks good to push, respond with: "✅ Code review passed - safe to push"

Please review the ENTIRE diff since main branch, including all commits and file changes.
EOF

echo -e "${YELLOW}📝 Running automated code review...${NC}"

# Run Claude Code review
claude code < "$review_file"
review_exit_code=$?

# Clean up
rm "$review_file"

# Check if Claude review was successful
if [ $review_exit_code -ne 0 ]; then
    echo -e "${RED}❌ Claude Code review failed${NC}"
    echo -e "${YELLOW}💡 To skip this review: SKIP_CLAUDE_REVIEW=true git push${NC}"
    exit 1
fi

echo ""
echo -e "${GREEN}🎉 Claude Code review completed!${NC}"
echo -e "${YELLOW}💡 To skip future reviews: SKIP_CLAUDE_REVIEW=true git push${NC}"

# Ask user if they want to proceed
echo ""
read -p "Do you want to proceed with the push? (y/N): " -n 1 -r
echo ""

if [[ $REPLY =~ ^[Yy]$ ]]; then
    echo -e "${GREEN}✅ Proceeding with push...${NC}"
    exit 0
else
    echo -e "${YELLOW}🛑 Push cancelled by user${NC}"
    exit 1
fi

Step 3: Configure Your Project

Add these commands to your CLAUDE.md file (create if it doesn’t exist):

# Project Code Review Commands

## Lint Commands
- `npm run lint` or `yarn lint` - Run ESLint
- `npm run lint:fix` or `yarn lint:fix` - Fix linting issues

## Type Checking
- `npm run typecheck` or `yarn typecheck` - Run TypeScript checking
- `tsc --noEmit` - Alternative TypeScript check

## Testing
- `npm test` or `yarn test` - Run all tests
- `npm run test:coverage` - Run tests with coverage

## Build
- `npm run build` or `yarn build` - Build the project

## Pre-push Checklist
Before pushing code, ensure:
1. All tests pass
2. No linting errors
3. No type errors
4. Build succeeds
5. No security vulnerabilities

Step 4: Test the Setup

Test your setup with these commands:

# Make a small change and commit it
echo "// Test comment" >> src/test-file.js
git add .
git commit -m "test: add test comment for hook testing"

# Try to push (this should trigger Claude review)
git push origin your-branch-name

# Test skipping the review
SKIP_CLAUDE_REVIEW=true git push origin your-branch-name

Usage Examples

Normal push with review:

git push origin feature-branch
# This will automatically run Claude Code review
# Generates: claude-review-report_YYYY-MM-DD_HH-MM-SS.md

Skip review when needed:

# For urgent hotfixes or when review isn't needed
SKIP_CLAUDE_REVIEW=true git push origin hotfix-branch

Set up permanent skip (not recommended):

# Add to your shell profile (.bashrc, .zshrc, etc.)
export SKIP_CLAUDE_REVIEW=true

Advanced Configuration

Custom Review Prompts

Create different review prompts for different scenarios by modifying the hook:

# In your pre-push hook, you can customize based on branch
if [[ $current_branch == hotfix* ]]; then
    # Use lighter review for hotfixes
    review_prompt="Quick security and critical bug check only"
elif [[ $current_branch == feature* ]]; then
    # Full review for features
    review_prompt="Comprehensive code review including performance and best practices"
fi

Integration with CI/CD

You can also integrate this into your CI/CD pipeline:

# .github/workflows/code-review.yml
name: Claude Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Claude Code
        run: |
          # Install Claude Code CLI
          pip install claude-code
      - name: Run Code Review
        run: |
          claude code "Please review this PR for security, bugs, and code quality issues"

Troubleshooting

Hook not running?

# Check if hook is executable
ls -la .git/hooks/pre-push

# Make it executable if needed
chmod +x .git/hooks/pre-push

Claude Code not found?

# Install Claude Code CLI
pip install anthropic-claude-code

# Or using npm
npm install -g @anthropic-ai/claude-code

Want to modify the hook?

# Edit the hook file
nano .git/hooks/pre-push

# Or use your preferred editor
code .git/hooks/pre-push

Key Features

✅ Full Branch Review: Reviews ALL commits since branching from main, not just the latest commit
✅ Smart Branch Detection: Automatically finds main/master/origin/main/origin/master
✅ Auto Project Detection: Identifies JavaScript/TypeScript, Python, Java/Android projects automatically
✅ Timestamped Reports: Generates permanent markdown reports with complete analysis
✅ Comprehensive Analysis: Reviews security, performance, bugs, and code quality
✅ Project-Specific Checks: Runs your lint, typecheck, and test commands
✅ Action Checklists: Provides clear tasks for addressing any issues found
✅ Detailed Reporting: Shows exactly which commits and files will be reviewed
✅ Flexible: Can be skipped when needed for urgent pushes

Benefits

✅ Automated Quality Control: Catches issues before they reach the remote repository
✅ Full Change Visibility: Reviews entire diff since branching from main
✅ Permanent Documentation: Timestamped reports track all reviews and action items
✅ Issue Tracking: Action checklists help systematically address problems
✅ Educational: Learn best practices from Claude’s feedback
✅ Team Consistency: Ensures all team members follow the same review standards
✅ Historical Record: Keep track of code quality improvements over time

Team Setup

Share this setup with your team by:

1. Adding the pre-push hook to your repository (in a scripts/ folder)
2. Creating a setup script that copies it to .git/hooks/
3. Documenting the process in your project’s README
4. Adding the CLAUDE.md configuration to your repository

# scripts/setup-hooks.sh
#!/bin/bash
cp scripts/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push
echo "✅ Claude Code review hook installed!"

Now your code will be automatically reviewed by Claude before every push, helping maintain high code quality while giving you the flexibility to skip when needed!