claude-context-cli (ctx)

Auto-indexing CLI and Claude Code plugin for @zilliz/claude-context-mcp. Keeps your codebase index fresh automatically.

Table of Contents

• Problem
• Features
• Install
• Usage
• Configuration
• Plugin Hooks
• Contributing
• License

Problem

claude-context-mcp provides semantic code search via Milvus, but it only indexes when explicitly told to. After git pulls, code edits, or branch switches, the index goes stale and search results become incomplete.

Features

• Automatic re-indexing on session start, after git operations, and on session end
• Staleness detection via git commit timestamps and dirty file tracking
• Incremental indexing (Merkle tree based, only changed files re-embedded)
• Config resolution matching claude-context-mcp (walks .mcp.json > ~/.claude.json > ~/.context/.env)
• Standalone CLI for manual indexing and search
• Claude Code plugin with async hooks
• Distributed via npm with native module support

Install

npm (recommended)

npm install -g claude-context-cli

This installs both claude-context-cli and the shorter ctx alias.

Claude Code plugin

/plugin marketplace add chrisfentiman/claudesplace
/plugin install claude-context-cli

From source

git clone https://github.com/chrisfentiman/claude-context-cli.git
cd claude-context-cli
npm install
npm run build

Usage

# Index a codebase (incremental)
ctx index [path]

# Index only if stale (new commits or dirty files changed)
ctx index --if-stale [path]

# Force full re-index
ctx index --force [path]

# Check index status
ctx status [path]

# Semantic search
ctx search "authentication middleware" [path]
ctx search "database connection" -n 5 [path]

# Clear index
ctx clear [path]

If running from source, use npx ts-node cli.ts or node dist/cli.js after npm run build.

Configuration

Configuration is resolved by walking the same sources as claude-context-mcp, in priority order:

1. process.env (highest)
2. .mcp.json (project-level, claude-context server env)
3. .claude/.mcp.json
4. ~/.claude.json (user-level MCP config)
5. ~/.context/.env (claude-context global config)
6. Defaults (lowest)

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | EMBEDDING_PROVIDER | Ollama | Ollama, OpenAI, Gemini, VoyageAI | | EMBEDDING_MODEL | Provider-specific | Model name | | OLLAMA_HOST | http://127.0.0.1:11434 | Ollama server URL | | OLLAMA_MODEL | nomic-embed-text | Ollama model (overrides EMBEDDING_MODEL) | | MILVUS_ADDRESS | 127.0.0.1:19530 | Milvus server address | | MILVUS_TOKEN | -- | Milvus/Zilliz Cloud auth token | | OPENAI_API_KEY | -- | Required for OpenAI provider | | OPENAI_BASE_URL | https://api.openai.com/v1 | Custom OpenAI-compatible endpoint | | GEMINI_API_KEY | -- | Required for Gemini provider | | GEMINI_BASE_URL | -- | Custom Gemini endpoint | | VOYAGEAI_API_KEY | -- | Required for VoyageAI provider |

Staleness detection

The CLI tracks index state in .claude/context/last-index.json:

1. Records the latest git commit timestamp and dirty file count after each index
2. On --if-stale, compares current git state against saved state
3. Re-indexes only if new commits exist or dirty file count changed
4. Merkle tree in @zilliz/claude-context-core handles file-level diffing

Plugin Hooks

When installed as a Claude Code plugin, three hooks fire automatically:

| Hook | Event | Behavior | |------|-------|----------| | SessionStart | Session opens | index --if-stale (async) | | PostToolUse | After Bash commands | Re-index after git pull/merge/checkout/rebase (async) | | SessionEnd | Session closes | index --if-stale (async) |

All hooks are async and non-blocking.

Prerequisites

• A running Milvus instance or Zilliz Cloud account
• An embedding provider: Ollama (default), OpenAI, Gemini, or VoyageAI
• claude-context-mcp configured as an MCP server

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feat/something)
3. Commit changes (git commit -m 'feat: add something')
4. Push to branch (git push origin feat/something)
5. Open a PR

License

MIT