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