cba — Codebase Agent

Semantic code search and explanation tool for humans and AI agents. Like ripgrep, but it understands your code.

cba index .                          # Index a codebase (local embeddings, no API key needed)
cba search 'auth flow'               # Semantic search with AI explanations
cba ask 'How does error handling work?'  # One-shot Q&A grounded in code
cba chat                             # Interactive chat about your codebase
cba mcp                              # Start MCP server for Claude Code / Cursor

What it does

search + explain — returns ranked code chunks AND a brief LLM-generated explanation of each result's relevance.

• Semantic search: Finds code by meaning, not just keywords. "auth flow" finds validateToken(), SessionManager, login middleware — even if they never contain the word "auth".
• AST-aware chunking: Uses tree-sitter to split code into semantic units (functions, classes, interfaces) instead of dumb line windows.
• Local embeddings: Runs all-MiniLM-L6-v2 locally via ONNX — no embedding API key needed. Model downloads (~80MB) on first run and is cached.
• LLM explanations: Claude explains why each result is relevant (optional, requires Anthropic API key).

Architecture

@cba/core  ←──  @cba/cli  (CLI binary)
           ←──  @cba/mcp  (MCP server for AI agents)

Three packages, one engine:

Package	Purpose
@cba/core	Indexing pipeline, vector search, LLM integration, memory
@cba/cli	CLI commands (cba index, cba search, cba ask, cba chat, etc.)
@cba/mcp	MCP server with tools for Claude Code, Cursor, and other AI agents

Setup

Prerequisites

• Node.js 20+
• pnpm 9+

Install

git clone https://github.com/davidgeorgehope/cba.git
cd cba
pnpm install
pnpm build

Configure

Only one API key is needed — and only for LLM features (explain, ask, chat):

# Create a .env file (auto-loaded by the CLI)
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Or set globally
mkdir -p ~/.cba
echo "ANTHROPIC_API_KEY=sk-ant-..." > ~/.cba/.env

Indexing and pure vector search work without any API key.

Run

# From the repo directory:
node packages/cli/dist/bin.js --help

# Or link globally:
pnpm -C packages/cli link --global
cba --help

CLI Commands

cba index [path]

Index a codebase for semantic search. Scans files, parses ASTs with tree-sitter, chunks by semantic boundaries, embeds locally, and stores vectors in LanceDB.

cba index .                    # Index current directory
cba index /path/to/project     # Index a specific project
cba index . --reindex           # Force full re-index
cba index . --exclude '*.test.ts'  # Exclude patterns

Supports incremental re-indexing — only processes changed files on subsequent runs.

cba search <query>

Semantic search with optional AI explanations.

cba search 'authentication flow'         # Search + Claude explanations
cba search 'database queries' --no-explain  # Fast retrieval only
cba search 'error handling' --limit 5    # Limit results
cba search 'api routes' --lang python    # Filter by language
cba search 'config' --path 'src/**'      # Filter by path
cba search 'auth' --json                 # JSON output for piping
cba search 'auth' --json | jq '.[].filePath'

cba ask <question>

One-shot question answering grounded in your code.

cba ask 'How does the app handle authentication?'
cba ask 'What database is used and how is it configured?' --show-sources
cba ask 'What are the main API endpoints?' --context 15  # More context chunks

cba chat

Interactive REPL with streaming responses and conversation memory.

cba chat                    # Start new session
cba chat --resume <id>      # Resume a conversation

In-session commands: /exit, /clear, /sources, /memory

cba status

cba status                  # Show current project status
cba status --list           # List all indexed projects

cba memory

Persistent per-project memory for facts about your codebase.

cba memory list
cba memory search 'database'
cba memory add 'Uses PostgreSQL with Prisma ORM' -c technology
cba memory delete <id>
cba memory clear

cba mcp

Start an MCP server on stdio for AI agent integration.

cba mcp                         # Use current directory
cba mcp --project /path/to/repo # Specify project

cba config

cba config show       # Show current config
cba config set llm.chatModel claude-opus-4-20250514
cba config init       # Initialize ~/.cba directory

Global Options

-p, --project <path>   Project path (default: cwd)
--json                 Machine-readable JSON output
--no-color             Disable colors
--verbose              Verbose logging

MCP Server

Connect cba to Claude Code, Cursor, or any MCP-compatible AI agent:

{
  "mcpServers": {
    "codebase-agent": {
      "command": "node",
      "args": ["/path/to/cba/packages/cli/dist/bin.js", "mcp", "--project", "/path/to/your/project"]
    }
  }
}

Tools

Tool	Description
codebase_search	Semantic search with optional LLM explanations
codebase_explain	Explain a concept or pattern in the codebase
codebase_ask	Answer a question grounded in the code
index_project	Index or re-index a project
memory_search	Search persistent codebase memory
memory_add	Store a fact about the codebase

Resources

• cba://projects — List all indexed projects
• cba://status/{path} — Index status for a project

Prompts

• explain-codebase — Generate a comprehensive explanation of a codebase area
• review-code — Review code for issues, patterns, and improvements

Tech Stack

Component	Technology
Embeddings	all-MiniLM-L6-v2 via @huggingface/transformers (local, no API key)
Vector DB	LanceDB (embedded, no server)
Parsing	tree-sitter (TS, JS, Python, Go, Rust, Java)
LLM	Claude via @anthropic-ai/sdk
CLI	Commander.js, chalk, ora
MCP	@modelcontextprotocol/sdk
Build	pnpm workspaces, turbo, TypeScript

Supported Languages

Full AST-aware chunking: TypeScript, JavaScript, Python, Go, Rust, Java

Sliding-window fallback (still indexed and searchable): all other text file types including YAML, JSON, Markdown, HTML, CSS, SQL, Shell, Ruby, PHP, C/C++, C#, Swift, Kotlin, Scala, and more.

How It Works

1. Scan — Walk directories, respect .gitignore, hash file contents for incremental updates
2. Parse — tree-sitter AST parsing per language, extract semantic nodes (functions, classes, methods, types)
3. Chunk — Split into semantic units (~512 tokens). Large functions/classes are sub-chunked. Unsupported languages use sliding windows.
4. Embed — Generate 384-dim vectors locally with all-MiniLM-L6-v2
5. Store — Upsert into LanceDB at ~/.cba/data/{projectHash}/
6. Search — Embed query, vector similarity search, normalize scores, apply filters
7. Explain — Send top chunks to Claude in a single batch call, get per-result explanations

License

MIT