Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/helweg/open-codebase-index/agents-mdgit clone --depth 1 https://github.com/Helweg/open-codebase-indexWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.04107 | $0.04107 |
| Opus 5 | $0.02054 | $0.02054 |
| Sonnet 5 | $0.00821 | $0.00821 |
| Haiku 4.5 | $0.00411 | $0.00411 |
Grade A, and why
open-codebase-index AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 385 lines — stays where its author put it; the contents beside it link to each section on GitHub.
AGENTS.md - AI Agent Guidelines for open-codebase-index
Updated: 2026-08-02 | Commit: 32160f8 | Branch: main | Version: 0.22.3
Semantic codebase indexing for OpenCode, MCP hosts, Pi, Claude, Codex, and Jcode. repo uses hybrid TypeScript/Rust architecture:
- TypeScript (
src/): host adapters, tool orchestration, indexing, retrieval, embedding providers, config, evaluation, and watchers - Rust (
native/): tree-sitter parsing, semantic chunking, usearch vectors, SQLite persistence, BM25, call graphs, and graph analytics
Build, Test, and Lint
npm run build # Build TypeScript and the Rust native module
npm run build:ts # TypeScript bundle plus built-CLI smoke test
npm run build:native # Rust/NAPI module for the current platform
npm run test:run # Full Vitest suite once; pretest rebuilds native code
npm test # Vitest watch mode
npm run test:coverage # Coverage run; pretest rebuilds native code
npm run lint # ESLint over src/
npm run typecheck # tsc --noEmit
Run a Single Test
npx vitest run tests/files.test.ts
npx vitest run -t "parseFile"
When Rust code changes, rebuild native module before running targeted tests that bypass npm run test:run
npm run build:native
# Equivalent low-level command:
cd native && cargo build --release && napi build --release --platform
full PR validation gate is:
npm run build && npm run typecheck && npm run lint && npm run test:run
Architecture and File Structure
src/
├── index.ts # Thin OpenCode facade; re-exports adapters/opencode
├── mcp-server.ts # Thin MCP facade; re-exports createMcpServer
├── cli.ts # CLI facade for MCP, eval, and visualization commands
├── adapters/
│ ├── opencode.ts # OpenCode plugin composition and hooks
│ ├── opencode/ # OpenCode tool and PR-impact adapters
│ ├── mcp/ # MCP CLI, server, tools, prompts, and shared schemas
│ └── pi/ # Pi extension and call-graph adapters
├── tools/
│ ├── operations.ts # Shared host-neutral tool operations
│ ├── operation-runtime.ts # Shared operation runtime/context
│ ├── contracts.ts # Shared request/result contracts
│ ├── execute-common.ts # Common execution helpers
│ ├── context*.ts # Context routing, retrieval, and evidence packing
│ └── tool-names.ts # Canonical and host-specific public tool names
├── indexer/
│ ├── index.ts # Indexer orchestration
│ ├── search-ranking.ts # Hybrid fusion, filtering, diversity, assembly
│ ├── definition-ranking.ts # Definition-oriented evidence ranking
│ ├── embedding-batches.ts # Embedding batching, retry state, vector pooling
│ └── call-graph-constants.ts # Shared declaration chunk-type rules
├── native/ # Focused TypeScript wrappers over the NAPI binding
├── config/ # Host-aware config schema, merging, paths, and validation
├── embeddings/ # Provider detection and implementations
├── git/ # Branch resolution and branch-index materialization
├── watcher/ # File and Git branch watchers
├── eval/ # Retrieval evaluation CLI, datasets, metrics, and reports
├── rerank/ # Optional external reranking
├── utils/ # Files, paths, logging, metrics, power state, and helpers
├── identity-catalog.json # Current/future product and package identities
└── package-metadata.ts # Runtime package metadata helpers
native/src/
├── lib.rs # NAPI facade and exports
├── bindings/
│ └── database.rs # NAPI Database wrapper methods
├── db.rs # Core SQLite database implementation
├── db/call_graph.rs # Call-graph persistence and query operations
├── parser.rs # Tree-sitter parsing
├── chunker.rs # Semantic chunking with overlap
├── call_extractor.rs # Query-based call extraction
├── community.rs # Community detection and centrality algorithms
├── store.rs # usearch vector storage
├── inverted_index.rs # BM25 keyword index
├── hasher.rs # xxhash content hashing
└── types.rs # Shared native types and language mapping
native/queries/ # Tree-sitter call queries by language
tests/ # Vitest integration and unit tests
benchmarks/ # Native and retrieval benchmarks/evaluation fixtures
commands/ # OpenCode slash command definitions
skill/ # OpenCode skill guidance
docs/ # Installation, configuration, tools, migration docs
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 385 lines · 4,107 tokens per session scan A aa6a2565d495
open-codebase-index AGENTS.md is an instructions file published in the GitHub repository Helweg/open-codebase-index (185 stars, last pushed 3d ago), licensed MIT. It adds 4,107 tokens to every session, about $0.0205 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
gno AGENTS.md
Instructions for gmickel/gno, covering knowledge cutoff warning, apis - bun first!, must use bun, acceptable node:\ (no bun equivalent) and testing.
coco-search CLAUDE.md
Instructions for VioletCranberry/coco-search, covering project instructions, project overview, tool routing (mandatory), development setup and prerequisites: docker, uv (python package manager).
codesearch AGENTS.md
Instructions for flupkede/codesearch, covering agents.md — codesearch, current state, implemented features, open todos and ⚠️ branching & pr workflow (read first).
codesage AGENTS.md
Instructions for iliaal/codesage, covering codesage, build, sanity check before pushing, crate map and search pipeline.
leantoken AGENTS.md
Instructions for morluto/leantoken, covering repository guidance, architecture, development, change-specific validation and contributions.
ken CLAUDE.md
Instructions for townsendmerino/ken, covering claude.md, what this is, repository ownership (read this first), commands and embedding parity & golden fixtures (now in aikit).