Codamigo - Code Amigo

Semantic code search for your local machine. codamigo walks a source tree, chunks files into semantically coherent pieces using tree-sitter ASTs, embeds the chunks with a configurable embedding provider, stores them in a local SQLite + sqlite-vec database, and exposes hybrid search (KNN + BM25) via a CLI and an MCP stdio server.

How it works

codamigo runs a four-stage pipeline:

Walk — recursive filesystem walk with .gitignore / .caignore and include/exclude glob filtering
Chunk — tree-sitter AST-based splitting into semantically coherent units (functions, classes, declarations)
Embed — each chunk is converted to a float32 vector via any OpenAI-compatible embedding API
Search — queries are embedded and matched against the store using hybrid KNN + BM25 (Reciprocal Rank Fusion), backed by sqlite-vec and FTS5

The index lives in a single .codamigo/store.db file in your project. No external services are required — any local embedding server (Ollama, LM Studio) works.

Installation

Prerequisites: Go 1.26+ and a C compiler (CGo is required for tree-sitter grammars).

go install github.com/ieshan/codamigo/cmd/codamigo@latest

If cc is not on your PATH, set the CC environment variable to point to your compiler before building.

Quick start

codamigo init            # guided setup — writes ~/.codamigo/global_settings.yml
codamigo index           # walk + chunk + embed + store
codamigo search "query"  # semantic search, prints top 10 results
codamigo map             # structural map of packages, files, and symbols
codamigo serve           # start MCP stdio server for AI assistant integration

Usage modes

Choose the mode that fits your workflow.

Mode A — CLI only

Run index whenever you want to refresh the store, then search interactively. No AI assistant required. Useful for one-off exploration or scripting.

codamigo index
codamigo search "authentication middleware" 5

Mode B — MCP with pre-indexed store

Pre-run index before starting serve (e.g. in CI, as a cron job, or on a git hook). When serve starts it also runs an initial index pass, but if the store is already fresh all files are hash-matched and skipped quickly. Use this when you want indexing managed outside the MCP server lifecycle.

# scheduled or on commit:
codamigo index

# AI assistant launches this (serve re-checks hashes on startup, then watches):
codamigo serve

Mode C — MCP with auto-indexing (recommended)

Run serve once. It performs an initial full index on startup, then watches the filesystem for changes and re-indexes modified files continuously. The MCP refresh_index=true parameter triggers a manual re-index on demand.

# configure your AI assistant to run:
codamigo serve

Decision guide:

Simplest local setup → Mode C
Indexing managed separately (CI/CD, cron, git hooks) → Mode B
No AI assistant, just want semantic grep → Mode A

Commands

`codamigo init`

Guided first-time setup. Prompts for embedding base URL, model, and API key. Writes ~/.codamigo/global_settings.yml and .codamigo/settings.yml (if absent). Appends .codamigo/ to .gitignore. Runs a smoke-test against the embedding model.

No flags. Reads from stdin interactively.

`codamigo index`

Walks the project root, chunks every matched file, embeds each chunk, and upserts records into the store. Skips files whose content hash is unchanged since the last run. Removes records for files that no longer exist on disk.

When stderr is a TTY, a live 2-line progress display shows running processed/skipped counts and the file currently being indexed. The display is suppressed automatically in CI and piped environments.

Common flags (shared by all commands):

Flag	Env var	Default	Purpose
`--api-key`	`CODAMIGO_API_KEY`	—	Embedding API key
`--model`	`CODAMIGO_MODEL`	`text-embedding-3-small`	Embedding model name
`--base-url`	`CODAMIGO_BASE_URL`	`https://api.openai.com/v1`	Embedding API base URL
`--store-path`	`CODAMIGO_STORE_PATH`	`.codamigo/store.db`	SQLite store file path
`--project-root`	`CODAMIGO_PROJECT_ROOT`	current directory	Root directory to index
`--dimensions`	`CODAMIGO_DIMENSIONS`	`1536`	Embedding vector dimensions
`--global-config`	`CODAMIGO_GLOBAL_CONFIG`	`~/.codamigo/global_settings.yml`	Path to global config
`--project-config`	`CODAMIGO_PROJECT_CONFIG`	`.codamigo/settings.yml`	Path to project config

`codamigo search <query> [limit]`

Embeds the query and runs hybrid KNN + BM25 search. Prints results as score filepath:startLine-endLine [language] followed by the chunk content.

Additional flags:

Flag	Default	Purpose
`--limit`	`10`	Maximum results to return
`--offset`	`0`	Results to skip (pagination)
`--lang`	—	Filter by language, repeatable: `--lang go --lang python`
`--path`	—	Filter by file path glob, repeatable: `--path 'cmd/**'`
`--max-tokens`	`0`	Token budget for results (0 = no limit)
`--package`	—	Filter results to a package (e.g. `--package store`)
`--name`	—	Filter by symbol name
`--node-kind`	—	Filter by AST node kind, repeatable
`--metadata-only`	`false`	Return only file paths, line numbers, and symbol names

limit can also be passed as a second positional argument: codamigo search "auth" 5.

`codamigo map`

Prints a structural map of the indexed codebase showing packages, files, and symbol names. Useful for orientation before searching. Built entirely from stored data — no embedding API calls.

By default, the map excludes configured non-code files (default: markdown, yaml, json), shows line ranges on symbols, includes per-file type summaries, and marks exported/internal symbols.

Flag	Default	Purpose
`--max-tokens`	`2000`	Token budget for the map output
`--no-code-only`	`false`	Include configured non-code language files in the map
`--no-summary`	`false`	Hide per-file type summary from file headers
`--no-visibility`	`false`	Hide export/visibility markers from symbols

`codamigo serve`

Starts the MCP stdio server. On startup it runs a full index pass, then launches a background filesystem watcher that re-indexes changed files. Accepts MCP tool calls from an AI assistant over stdin/stdout.

MCP tool: search

query (string) — the search text
limit (int, default 10) — how many results to return
languages (array, optional) — filter by programming language
paths (array, optional) — glob patterns to restrict search scope
max_tokens (int, default 0) — token budget for results (0 = no limit)
package (string, optional) — filter to a package name
refresh_index (bool, default false) — trigger a full re-index before searching
name (string, optional) — filter results to chunks matching this symbol name
node_kinds (array, optional) — filter by AST node kind (e.g. ["function_declaration"])
metadata_only (bool, default false) — return only file paths, line numbers, and symbol names (no source content)
offset (int, default 0) — number of results to skip for pagination

MCP tool: get_map

max_tokens (int, default 2000) — token budget for the map output
code_only (bool, default true) — exclude configured non-code languages from the map
show_summary (bool, default true) — show per-file type summary in file headers
show_visibility (bool, default true) — show export markers (+ public, - internal)

Uses the same common flags as index.

`codamigo reset`

Deletes the vector store database file. Prompts for confirmation unless --force is passed.

Flag	Purpose
`--force`	Skip the confirmation prompt

`codamigo doctor`

Diagnoses configuration, store health, and embedding model reachability. Reports: global config, project config, store file existence, index stats (chunks, files, per-language counts), walker file count, embedding smoke-test.

Flag	Purpose
`--quick`	Skip the live embedding smoke-test

Configuration

Configuration is loaded in four layers — later layers win:

built-in defaults
  → ~/.codamigo/global_settings.yml   (shared across all projects)
    → .codamigo/settings.yml          (per-project; safe to commit)
      → environment variables
        → CLI flags

codamigo init writes the global file. The project file holds project-specific patterns. Both are YAML.

Full config reference:

# Embedding provider
embedding_provider: openai            # informational label only
embedding_model: text-embedding-3-small
embedding_api_key: sk-...             # use CODAMIGO_API_KEY env var instead
embedding_base_url: https://api.openai.com/v1
embedding_dimensions: 1536
embedding_index_input_type: ""        # e.g. "document" for Voyage AI
embedding_query_input_type: ""        # e.g. "query" for Voyage AI

# Rate limiting and retries
embedding_max_batch_size: 256
embedding_rate_limit: 500.0           # sustained requests/second
embedding_rate_burst: 100             # max burst above sustained rate
embedding_max_retries: 3
embedding_retry_base_delay: "500ms"   # e.g. "500ms", "1s"

# File filtering
include_patterns: []                  # empty = include all matched extensions
exclude_patterns: []                  # gitignore rules are also applied

# Map display
non_code_languages:           # languages excluded by code_only filter
  - markdown                  # default: ["markdown", "yaml", "json"]
  - yaml
  - json

# Storage
store_path: .codamigo/store.db

# Project
project_root: ""                      # defaults to current working directory

# Indexing
index_concurrency: 20                 # files processed concurrently during indexing
max_file_size: 1048576                # skip files larger than this (bytes); 0 = no limit
write_batch_size: 50                  # files per DB write transaction during batch indexing; 0 = use default (50)

# File watching (serve only)
watch_mode: auto                      # "auto" | "fsnotify" | "poll"
poll_interval: "5s"
debounce_window: "500ms"

Keep embedding_api_key in the global config (written with mode 0600 by init) or in CODAMIGO_API_KEY. Do not put API keys in the project config.

Embedding providers

OpenAI

# ~/.codamigo/global_settings.yml
embedding_base_url: https://api.openai.com/v1
embedding_model: text-embedding-3-small
embedding_dimensions: 1536

export CODAMIGO_API_KEY=sk-...

Models: text-embedding-3-small (fast, 1536 dims), text-embedding-3-large (higher quality, 3072 dims).

Voyage AI

Voyage uses input_type to distinguish document vs. query vectors, which improves retrieval quality.

# ~/.codamigo/global_settings.yml
embedding_base_url: https://api.voyageai.com/v1
embedding_model: voyage-code-3
embedding_dimensions: 1024
embedding_index_input_type: document
embedding_query_input_type: query

export CODAMIGO_API_KEY=pa-...

Ollama (local)

No API key required. Pull a model first:

ollama pull nomic-embed-text

# ~/.codamigo/global_settings.yml
embedding_base_url: http://localhost:11434/v1
embedding_model: nomic-embed-text
embedding_dimensions: 768
embedding_rate_limit: 50
embedding_rate_burst: 10

Ollama requires a non-empty Authorization header; set any placeholder value:

export CODAMIGO_API_KEY=ollama

Good models: nomic-embed-text (768 dims), mxbai-embed-large (1024 dims).

LM Studio (local)

Enable Local Server in LM Studio and load an embedding model, then:

# ~/.codamigo/global_settings.yml
embedding_base_url: http://localhost:1234/v1
embedding_model: <model-id-shown-in-lm-studio>
embedding_dimensions: <see model card>
embedding_rate_limit: 20
embedding_rate_burst: 5

export CODAMIGO_API_KEY=lm-studio

Check the model card for embedding_dimensions. A mismatch between the stored value and the configured value causes an error on the second index run — the store enforces model consistency.

MCP integration

codamigo speaks the MCP stdio protocol. Configure your AI assistant to launch codamigo serve as a stdio MCP server. The server indexes on startup and keeps the index fresh via filesystem watching.

Claude Code

Add to ~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "codamigo": {
      "command": "codamigo",
      "args": ["serve"],
      "env": {
        "CODAMIGO_API_KEY": "<your-api-key>"
      }
    }
  }
}

If your API key is already in ~/.codamigo/global_settings.yml, the env block can be omitted.

The tools are available in Claude as mcp__codamigo__search and mcp__codamigo__get_map.

OpenAI Codex

Add to ~/.codex/config.toml (global) or codex.toml (project):

[[mcp_servers]]
name = "codamigo"
command = "codamigo"
args = ["serve"]

[mcp_servers.env]
CODAMIGO_API_KEY = "<your-api-key>"

Tip: For large repos, run codamigo index once before starting your AI session. When serve starts it re-checks all files, but if the store is already fresh the pass completes in seconds.

Using with AI coding agents

codamigo is designed to be used as an MCP server by AI coding agents such as Claude Code, OpenAI Codex, Cursor, Windsurf, and others. Once codamigo serve is running, the agent has access to two tools:

Tool	Purpose
`search`	Semantic search — embed a query and return matching code chunks
`get_map`	Structural overview — packages, files, and symbol names from the index

Recommended workflow

1. Orient with get_map first. Before searching, call get_map (with a reasonable max_tokens budget, e.g. 2000) to get a structural overview of the codebase. This shows which packages exist, how many symbols each contains, and what the key files are. Use this to decide which package or file to scope your search to.

2. Search semantically. Use natural-language queries rather than exact symbol names. The hybrid KNN + BM25 index understands intent, not just keywords. "parse config file" will find the config loading logic even if the function is called Load.

3. Scope searches to reduce noise. Narrow results with the available filters:

package — restrict to one package, e.g. "store" or "embedder/openaicompat"
languages — e.g. ["go"] to skip test fixtures in other languages
node_kinds — e.g. ["function_declaration", "method_declaration"] to see only functions
name — exact symbol lookup, e.g. "NewChunker"

4. Use metadata_only for exploratory queries. When you want to find which files or functions are relevant without reading their full source, set metadata_only=true. Results include file path, line numbers, and symbol name but omit the source text — typically 10–20× fewer tokens. Follow up with a targeted search (or a direct file read) once you've identified the right symbols.

5. Control context budget with max_tokens. For agents with limited context windows, set max_tokens to cap the total tokens returned. Results are ranked by relevance and truncated at the budget; a truncated: true flag signals that more results exist.

6. Refresh the index when needed. Set refresh_index=true on a search call to trigger a full re-index before querying. A 30-second cooldown prevents hammering the embedder on rapid back-to-back calls. Alternatively, run codamigo index from the shell.

Example agent queries (Claude Code)

# Overview first — all features enabled by default
mcp__codamigo__get_map(max_tokens=3000)

# Overview without visibility markers
mcp__codamigo__get_map(max_tokens=3000, show_visibility=false)

# Include non-code files (markdown, yaml, etc.)
mcp__codamigo__get_map(max_tokens=3000, code_only=false)

# Find all functions related to embedding
mcp__codamigo__search(query="embedding API request", package="embedder/openaicompat", node_kinds=["function_declaration"])

# Look up a specific symbol
mcp__codamigo__search(query="walk directory tree", name="Walk", metadata_only=true)

# Scan store package cheaply
mcp__codamigo__search(query="upsert chunk records", package="store", metadata_only=true, limit=20)

Node kind reference

Common values for the node_kinds filter:

Value	Matches
`function_declaration`	Go `func` at package level
`method_declaration`	Go `func` on a receiver
`type_declaration`	Go `type` block
`function_definition`	Python / C / C++ functions
`class_definition`	Python classes
`class_declaration`	TypeScript / Java classes
`method_definition`	JS / TS / Ruby methods

Run codamigo map to see which node kinds appear in your indexed codebase.

Supported languages

Language	Extensions
Go	`.go`
Python	`.py`, `.pyw`
JavaScript	`.js`, `.mjs`, `.cjs`, `.jsx`
TypeScript	`.ts`, `.mts`
TSX	`.tsx`
Ruby	`.rb`
C	`.c`, `.h`
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`
Bash	`.sh`, `.bash`
HTML	`.html`, `.htm`
CSS	`.css`
Markdown	`.md`, `.markdown`
JSON	`.json`
YAML	`.yaml`, `.yml`
Vue	`.vue`

Use include_patterns and exclude_patterns in your project config to control which files are indexed.

`.caignore`

codamigo supports a .caignore file that works exactly like .gitignore but is specific to codamigo. Files matched by either .gitignore or .caignore are excluded from indexing and file watching.

Why use `.caignore`?

Your .gitignore controls what Git tracks. Sometimes you want codamigo to skip files that Git still tracks — large generated files, vendored dependencies, test fixtures, or data files that add noise to search results. .caignore lets you tune codamigo's scope without touching .gitignore.

Syntax

.caignore uses identical syntax to .gitignore:

# Ignore all CSV data files
*.csv

# Ignore the testdata directory
testdata/

# But keep the golden files
!testdata/golden/

Behavior

Same directory scoping as .gitignore. A .caignore in src/ applies only to paths under src/, just like a nested .gitignore.
.caignore rules win on conflict. Both files are loaded per directory (.gitignore first, then .caignore). The "last matching rule wins" semantics mean .caignore takes precedence.
Negation works across files. A !pattern in .caignore can re-include a path that .gitignore excludes.
Either file is optional. A directory with only .caignore (no .gitignore) works. A directory with only .gitignore works as before.

Examples

Exclude large generated files from the index while keeping them in Git:

# .caignore
generated/
*.pb.go
*.min.js

Re-include a directory that .gitignore excludes (useful for vendored code you want searchable):

# .gitignore
vendor/

# .caignore — override .gitignore for codamigo
!vendor/

Scope exclusions to a subdirectory by placing .caignore there:

# frontend/.caignore — only affects frontend/
node_modules/
dist/
*.bundle.js

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
chunker		chunker
cmd/codamigo		cmd/codamigo
config		config
embedder		embedder
indexer		indexer
langs		langs
mcp		mcp
query		query
skills/codamigo		skills/codamigo
store		store
walker		walker
watcher		watcher
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Codamigo - Code Amigo

How it works

Installation

Quick start

Usage modes

Mode A — CLI only

Mode B — MCP with pre-indexed store

Mode C — MCP with auto-indexing (recommended)

Commands

codamigo init

codamigo index

codamigo search <query> [limit]

codamigo map

codamigo serve

codamigo reset

codamigo doctor

Configuration

Embedding providers

OpenAI

Voyage AI

Ollama (local)

LM Studio (local)

MCP integration

Claude Code

OpenAI Codex

Using with AI coding agents

Recommended workflow

Example agent queries (Claude Code)

Node kind reference

Supported languages

.caignore

Why use .caignore?

Syntax

Behavior

Examples

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`codamigo init`

`codamigo index`

`codamigo search <query> [limit]`

`codamigo map`

`codamigo serve`

`codamigo reset`

`codamigo doctor`

`.caignore`

Why use `.caignore`?

Packages