{"owner":"zilliztech","repo":"claude-context","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Overview\n\nClaude Context is an MCP plugin that adds semantic code search to AI coding agents. A codebase is split into chunks, embedded, and stored in a Milvus/Zilliz vector database; queries are answered by semantic (hybrid dense + sparse) search instead of loading whole directories into the model's context.\n\n## Monorepo Layout\n\npnpm workspace (`packages/*`, `examples/*`). Requires Node >=20 <24 and pnpm >=10.\n\n- `packages/core` (`@zilliz/claude-context-core`) — the indexing engine. All real logic lives here; the other packages are thin frontends over it.\n- `packages/mcp` (`@zilliz/claude-context-mcp`) — stdio MCP server, the primary product. ESM (`\"type\": \"module\"`).\n- `packages/vscode-extension` (`semanticcodesearch`) — VSCode extension. Bundled with webpack; stubs out Node-only deps (Milvus gRPC, native AST) in `src/stubs/`.\n- `packages/chrome-extension` — browser build; overrides `@zilliz/milvus2-sdk-node` to `false` (no gRPC in browser).\n- `examples/basic-usage` — runnable library example.\n\n## Commands\n\n```bash\npnpm install\npnpm build                 # build all packages (examples built last)\npnpm build:core            # build a single package: also build:mcp, build:vscode\npnpm dev                   # watch all; or dev:core / dev:mcp / dev:vscode\npnpm lint                  # eslint across packages; lint:fix to autofix\npnpm typecheck             # tsc --noEmit across packages\npnpm clean                 # rimraf dist in every package\n```\n\nPackages depend on `core` via `workspace:*`, so **rebuild core (`pnpm build:core`) before testing mcp/vscode against core changes** — they consume `core/dist`, not its source.\n\n### Tests\n\n- **core** uses Jest + ts-jest. Test files are colocated as `*.test.ts` in `src/`.\n  ```bash\n  pnpm --filter @zilliz/claude-context-core test                     # all (runs in band)\n  pnpm --filter @zilliz/claude-context-core test -- context.abort    # by filename\n  pnpm --filter @zilliz/claude-context-core test -- -t \"pattern\"     # by test name\n  ```\n- **mcp** uses the Node built-in test runner via tsx (no Jest):\n  ```bash\n  pnpm --filter @zilliz/claude-context-mcp test                      # runs src/**/*.test.ts\n  ```\n\n### Running the MCP server locally\n\n```bash\npnpm --filter @zilliz/claude-context-mcp start        # tsx src/index.ts\n```\nConfiguration is entirely via environment variables (see `.env.example` and `packages/mcp/src/config.ts`). Key vars: `EMBEDDING_PROVIDER` (OpenAI | VoyageAI | Gemini | Ollama | OpenRouter), provider API key, `EMBEDDING_MODEL`, `MILVUS_ADDRESS` and/or `MILVUS_TOKEN` (address can be auto-resolved from a Zilliz token), `CODE_CHUNKS_COLLECTION_NAME_OVERRIDE`.\n\n## Architecture\n\n### Core: the `Context` orchestrator (`packages/core/src/context.ts`)\n\n`Context` ties together three pluggable interfaces injected through its constructor config:\n\n- **Embedding** (`src/embedding/`) — `base-embedding.ts` interface with `OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, `OllamaEmbedding` implementations.\n- **VectorDatabase** (`src/vectordb/`) — `MilvusVectorDatabase` (gRPC, Node-only) and `MilvusRestfulVectorDatabase` (HTTP, browser-safe). `zilliz-utils.ts` (`ClusterManager`) can provision a free Zilliz cluster and resolve an address from a token.\n- **Splitter** (`src/splitter/`) — `AstCodeSplitter` (tree-sitter, the default at 2500/300 chunk/overlap) which falls back to `LangChainCodeSplitter` for unsupported languages or parse failures.\n\nThe public surface (`indexCodebase`, `reindexByChange`, `semanticSearch`, `clearIndex`, `hasIndex`) is re-exported from `src/index.ts`. Indexing reads files honoring ignore rules, splits them, embeds in batches, and upserts vectors. Collection name is derived from a hash of the absolute codebase path (overridable).\n\nTwo error types carry control-flow meaning and should be preserved when touching the pipeline:\n- `IndexAbortError` — cooperative cancellation via `AbortSignal`.\n- `EmbeddingError` — always re-thrown to halt the whole pipeline, unlike per-file read/parse errors which are logged and skipped. This prevents silent partial indexing (Milvus getting zero vectors while the snapshot marks files done).\n\n### Incremental sync (`packages/core/src/sync/`)\n\n`FileSynchronizer` builds a Merkle DAG (`merkle.ts`) of file hashes to compute `{added, removed, modified}` between runs. Snapshots persist to `~/.context/merkle/<md5-of-path>.json`. `reindexByChange` uses this so re-indexing only touches changed files. The MCP server can also run a background sync loop (`CLAUDE_CONTEXT_BACKGROUND_SYNC`, `CLAUDE_CONTEXT_SYNC_INTERVAL_MS`).\n\n### Ignore patterns\n\nLayered: built-in `DEFAULT_IGNORE_PATTERNS` + config + env (`CUSTOM_IGNORE_PATTERNS`) + on-disk ignore files (`.gitignore`, `.contextignore`, `.xxxignore`, and a global `~/.context/.gitignore`). `utils/ignore-matcher.ts` implements matching including gitignore negation (`!`) semantics — covered by `context.ignore-patterns.test.ts`.\n\n### Env resolution (`packages/core/src/utils/env-manager.ts`)\n\n`envManager.get(name)` resolves with priority `process.env` > `~/.context/.env` file. Use it instead of reading `process.env` directly so the `.env` file fallback keeps working.\n\n### MCP server (`packages/mcp/src/`)\n\n- `index.ts` — entry point. **Critically, it redirects `console.log`/`console.warn` to stderr at the very top**, because stdout is reserved for the MCP JSON protocol. Never write non-protocol output to stdout in this package.\n- `handlers.ts` (`ToolHandlers`) — implements the tools: `index_codebase`, `search_code`, `clear_index`, `get_indexing_status`.\n- `snapshot.ts` (`SnapshotManager`) — tracks per-codebase indexing state across server restarts.\n- `sync.ts` (`SyncManager`) — drives incremental re-indexing.\n- `config.ts`, `embedding.ts` — build `Context` (embedding provider + Milvus) from environment variables.\n\n## Conventions\n\nCommits follow Conventional Commits with these scopes: `core`, `vscode`, `mcp`, `examples`, `docs` (e.g. `fix(core): support gitignore negation patterns`). All code and comments are written in English.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Overview\n\nClaude Context is an MCP plugin that adds semantic code search to AI coding agents. A codebase is split into chunks, embedded, and stored in a Milvus/Zilliz vector database; queries are answered by semantic (hybrid dense + sparse) search instead of loading whole directories into the model's context.\n\n## Monorepo Layout\n\npnpm workspace (`packages/*`, `examples/*`). Requires Node >=20 <24 and pnpm >=10.\n\n- `packages/core` (`@zilliz/claude-context-core`) — the indexing engine. All real logic lives here; the other packages are thin frontends over it.\n- `packages/mcp` (`@zilliz/claude-context-mcp`) — stdio MCP server, the primary product. ESM (`\"type\": \"module\"`).\n- `packages/vscode-extension` (`semanticcodesearch`) — VSCode extension. Bundled with webpack; stubs out Node-only deps (Milvus gRPC, native AST) in `src/stubs/`.\n- `packages/chrome-extension` — browser build; overrides `@zilliz/milvus2-sdk-node` to `false` (no gRPC in browser).\n- `examples/basic-usage` — runnable library example.\n\n## Commands\n\n```bash\npnpm install\npnpm build                 # build all packages (examples built last)\npnpm build:core            # build a single package: also build:mcp, build:vscode\npnpm dev                   # watch all; or dev:core / dev:mcp / dev:vscode\npnpm lint                  # eslint across packages; lint:fix to autofix\npnpm typecheck             # tsc --noEmit across packages\npnpm clean                 # rimraf dist in every package\n```\n\nPackages depend on `core` via `workspace:*`, so **rebuild core (`pnpm build:core`) before testing mcp/vscode against core changes** — they consume `core/dist`, not its source.\n\n### Tests\n\n- **core** uses Jest + ts-jest. Test files are colocated as `*.test.ts` in `src/`.\n  ```bash\n  pnpm --filter @zilliz/claude-context-core test                     # all (runs in band)\n  pnpm --filter @zilliz/claude-context-core test -- context.abort    # by filename\n  pnpm --filter @zilliz/claude-context-core test -- -t \"pattern\"     # by test name\n  ```\n- **mcp** uses the Node built-in test runner via tsx (no Jest):\n  ```bash\n  pnpm --filter @zilliz/claude-context-mcp test                      # runs src/**/*.test.ts\n  ```\n\n### Running the MCP server locally\n\n```bash\npnpm --filter @zilliz/claude-context-mcp start        # tsx src/index.ts\n```\nConfiguration is entirely via environment variables (see `.env.example` and `packages/mcp/src/config.ts`). Key vars: `EMBEDDING_PROVIDER` (OpenAI | VoyageAI | Gemini | Ollama | OpenRouter), provider API key, `EMBEDDING_MODEL`, `MILVUS_ADDRESS` and/or `MILVUS_TOKEN` (address can be auto-resolved from a Zilliz token), `CODE_CHUNKS_COLLECTION_NAME_OVERRIDE`.\n\n## Architecture\n\n### Core: the `Context` orchestrator (`packages/core/src/context.ts`)\n\n`Context` ties together three pluggable interfaces injected through its constructor config:\n\n- **Embedding** (`src/embedding/`) — `base-embedding.ts` interface with `OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, `OllamaEmbedding` implementations.\n- **VectorDatabase** (`src/vectordb/`) — `MilvusVectorDatabase` (gRPC, Node-only) and `MilvusRestfulVectorDatabase` (HTTP, browser-safe). `zilliz-utils.ts` (`ClusterManager`) can provision a free Zilliz cluster and resolve an address from a token.\n- **Splitter** (`src/splitter/`) — `AstCodeSplitter` (tree-sitter, the default at 2500/300 chunk/overlap) which falls back to `LangChainCodeSplitter` for unsupported languages or parse failures.\n\nThe public surface (`indexCodebase`, `reindexByChange`, `semanticSearch`, `clearIndex`, `hasIndex`) is re-exported from `src/index.ts`. Indexing reads files honoring ignore rules, splits them, embeds in batches, and upserts vectors. Collection name is derived from a hash of the absolute codebase path (overridable).\n\nTwo error types carry control-flow meaning and should be preserved when touching the pipeline:\n- `IndexAbortError` — cooperative cancellation via `AbortSignal`.\n- `EmbeddingError` — always re-thrown to halt the whole pipeline, unlike per-file read/parse errors which are logged and skipped. This prevents silent partial indexing (Milvus getting zero vectors while the snapshot marks files done).\n\n### Incremental sync (`packages/core/src/sync/`)\n\n`FileSynchronizer` builds a Merkle DAG (`merkle.ts`) of file hashes to compute `{added, removed, modified}` between runs. Snapshots persist to `~/.context/merkle/<md5-of-path>.json`. `reindexByChange` uses this so re-indexing only touches changed files. The MCP server can also run a background sync loop (`CLAUDE_CONTEXT_BACKGROUND_SYNC`, `CLAUDE_CONTEXT_SYNC_INTERVAL_MS`).\n\n### Ignore patterns\n\nLayered: built-in `DEFAULT_IGNORE_PATTERNS` + config + env (`CUSTOM_IGNORE_PATTERNS`) + on-disk ignore files (`.gitignore`, `.contextignore`, `.xxxignore`, and a global `~/.context/.gitignore`). `utils/ignore-matcher.ts` implements matching including gitignore negation (`!`) semantics — covered by `context.ignore-patterns.test.ts`.\n\n### Env resolution (`packages/core/src/utils/env-manager.ts`)\n\n`envManager.get(name)` resolves with priority `process.env` > `~/.context/.env` file. Use it instead of reading `process.env` directly so the `.env` file fallback keeps working.\n\n### MCP server (`packages/mcp/src/`)\n\n- `index.ts` — entry point. **Critically, it redirects `console.log`/`console.warn` to stderr at the very top**, because stdout is reserved for the MCP JSON protocol. Never write non-protocol output to stdout in this package.\n- `handlers.ts` (`ToolHandlers`) — implements the tools: `index_codebase`, `search_code`, `clear_index`, `get_indexing_status`.\n- `snapshot.ts` (`SnapshotManager`) — tracks per-codebase indexing state across server restarts.\n- `sync.ts` (`SyncManager`) — drives incremental re-indexing.\n- `config.ts`, `embedding.ts` — build `Context` (embedding provider + Milvus) from environment variables.\n\n## Conventions\n\nCommits follow Conventional Commits with these scopes: `core`, `vscode`, `mcp`, `examples`, `docs` (e.g. `fix(core): support gitignore negation patterns`). All code and comments are written in English.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Overview\n\nClaude Context is an MCP plugin that adds semantic code search to AI coding agents. A codebase is split into chunks, embedded, and stored in a Milvus/Zilliz vector database; queries are answered by semantic (hybrid dense + sparse) search instead of loading whole directories into the model's context.\n\n## Monorepo Layout\n\npnpm workspace (`packages/*`, `examples/*`). Requires Node >=20 <24 and pnpm >=10.\n\n- `packages/core` (`@zilliz/claude-context-core`) — the indexing engine. All real logic lives here; the other packages are thin frontends over it.\n- `packages/mcp` (`@zilliz/claude-context-mcp`) — stdio MCP server, the primary product. ESM (`\"type\": \"module\"`).\n- `packages/vscode-extension` (`semanticcodesearch`) — VSCode extension. Bundled with webpack; stubs out Node-only deps (Milvus gRPC, native AST) in `src/stubs/`.\n- `packages/chrome-extension` — browser build; overrides `@zilliz/milvus2-sdk-node` to `false` (no gRPC in browser).\n- `examples/basic-usage` — runnable library example.\n\n## Commands\n\n```bash\npnpm install\npnpm build                 # build all packages (examples built last)\npnpm build:core            # build a single package: also build:mcp, build:vscode\npnpm dev                   # watch all; or dev:core / dev:mcp / dev:vscode\npnpm lint                  # eslint across packages; lint:fix to autofix\npnpm typecheck             # tsc --noEmit across packages\npnpm clean                 # rimraf dist in every package\n```\n\nPackages depend on `core` via `workspace:*`, so **rebuild core (`pnpm build:core`) before testing mcp/vscode against core changes** — they consume `core/dist`, not its source.\n\n### Tests\n\n- **core** uses Jest + ts-jest. Test files are colocated as `*.test.ts` in `src/`.\n  ```bash\n  pnpm --filter @zilliz/claude-context-core test                     # all (runs in band)\n  pnpm --filter @zilliz/claude-context-core test -- context.abort    # by filename\n  pnpm --filter @zilliz/claude-context-core test -- -t \"pattern\"     # by test name\n  ```\n- **mcp** uses the Node built-in test runner via tsx (no Jest):\n  ```bash\n  pnpm --filter @zilliz/claude-context-mcp test                      # runs src/**/*.test.ts\n  ```\n\n### Running the MCP server locally\n\n```bash\npnpm --filter @zilliz/claude-context-mcp start        # tsx src/index.ts\n```\nConfiguration is entirely via environment variables (see `.env.example` and `packages/mcp/src/config.ts`). Key vars: `EMBEDDING_PROVIDER` (OpenAI | VoyageAI | Gemini | Ollama | OpenRouter), provider API key, `EMBEDDING_MODEL`, `MILVUS_ADDRESS` and/or `MILVUS_TOKEN` (address can be auto-resolved from a Zilliz token), `CODE_CHUNKS_COLLECTION_NAME_OVERRIDE`.\n\n## Architecture\n\n### Core: the `Context` orchestrator (`packages/core/src/context.ts`)\n\n`Context` ties together three pluggable interfaces injected through its constructor config:\n\n- **Embedding** (`src/embedding/`) — `base-embedding.ts` interface with `OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, `OllamaEmbedding` implementations.\n- **VectorDatabase** (`src/vectordb/`) — `MilvusVectorDatabase` (gRPC, Node-only) and `MilvusRestfulVectorDatabase` (HTTP, browser-safe). `zilliz-utils.ts` (`ClusterManager`) can provision a free Zilliz cluster and resolve an address from a token.\n- **Splitter** (`src/splitter/`) — `AstCodeSplitter` (tree-sitter, the default at 2500/300 chunk/overlap) which falls back to `LangChainCodeSplitter` for unsupported languages or parse failures.\n\nThe public surface (`indexCodebase`, `reindexByChange`, `semanticSearch`, `clearIndex`, `hasIndex`) is re-exported from `src/index.ts`. Indexing reads files honoring ignore rules, splits them, embeds in batches, and upserts vectors. Collection name is derived from a hash of the absolute codebase path (overridable).\n\nTwo error types carry control-flow meaning and should be preserved when touching the pipeline:\n- `IndexAbortError` — cooperative cancellation via `AbortSignal`.\n- `EmbeddingError` — always re-thrown to halt the whole pipeline, unlike per-file read/parse errors which are logged and skipped. This prevents silent partial indexing (Milvus getting zero vectors while the snapshot marks files done).\n\n### Incremental sync (`packages/core/src/sync/`)\n\n`FileSynchronizer` builds a Merkle DAG (`merkle.ts`) of file hashes to compute `{added, removed, modified}` between runs. Snapshots persist to `~/.context/merkle/<md5-of-path>.json`. `reindexByChange` uses this so re-indexing only touches changed files. The MCP server can also run a background sync loop (`CLAUDE_CONTEXT_BACKGROUND_SYNC`, `CLAUDE_CONTEXT_SYNC_INTERVAL_MS`).\n\n### Ignore patterns\n\nLayered: built-in `DEFAULT_IGNORE_PATTERNS` + config + env (`CUSTOM_IGNORE_PATTERNS`) + on-disk ignore files (`.gitignore`, `.contextignore`, `.xxxignore`, and a global `~/.context/.gitignore`). `utils/ignore-matcher.ts` implements matching including gitignore negation (`!`) semantics — covered by `context.ignore-patterns.test.ts`.\n\n### Env resolution (`packages/core/src/utils/env-manager.ts`)\n\n`envManager.get(name)` resolves with priority `process.env` > `~/.context/.env` file. Use it instead of reading `process.env` directly so the `.env` file fallback keeps working.\n\n### MCP server (`packages/mcp/src/`)\n\n- `index.ts` — entry point. **Critically, it redirects `console.log`/`console.warn` to stderr at the very top**, because stdout is reserved for the MCP JSON protocol. Never write non-protocol output to stdout in this package.\n- `handlers.ts` (`ToolHandlers`) — implements the tools: `index_codebase`, `search_code`, `clear_index`, `get_indexing_status`.\n- `snapshot.ts` (`SnapshotManager`) — tracks per-codebase indexing state across server restarts.\n- `sync.ts` (`SyncManager`) — drives incremental re-indexing.\n- `config.ts`, `embedding.ts` — build `Context` (embedding provider + Milvus) from environment variables.\n\n## Conventions\n\nCommits follow Conventional Commits with these scopes: `core`, `vscode`, `mcp`, `examples`, `docs` (e.g. `fix(core): support gitignore negation patterns`). All code and comments are written in English.\n","category":"root","tokens":1548}]}