{"id":48483306,"url":"https://github.com/stainless-code/codemap","last_synced_at":"2026-04-07T09:01:26.445Z","repository":{"id":349605926,"uuid":"1202921401","full_name":"stainless-code/codemap","owner":"stainless-code","description":"Query your codebase — structural SQLite index for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-06T18:37:27.000Z","size":171,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T19:27:28.326Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stainless-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["SutuSebastian"]}},"created_at":"2026-04-06T14:38:36.000Z","updated_at":"2026-04-06T18:37:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stainless-code/codemap","commit_stats":null,"previous_names":["stainless-code/codemap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/stainless-code/codemap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stainless-code%2Fcodemap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stainless-code%2Fcodemap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stainless-code%2Fcodemap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stainless-code%2Fcodemap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stainless-code","download_url":"https://codeload.github.com/stainless-code/codemap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stainless-code%2Fcodemap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31506578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-07T09:01:24.434Z","updated_at":"2026-04-07T09:01:26.440Z","avatar_url":"https://github.com/stainless-code.png","language":"TypeScript","funding_links":["https://github.com/sponsors/SutuSebastian"],"categories":[],"sub_categories":[],"readme":"# Codemap\n\n**Query your codebase.** Codemap builds a **local SQLite index** of structural metadata (symbols, imports, exports, components, dependencies, CSS tokens, markers, and more) so **AI agents and tools** can answer “where / what / who” questions with **SQL** instead of scanning the whole tree.\n\n- **Not** full-text search or grep on arbitrary strings — use those when you need raw file-body search.\n- **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, components, and other extracted facts.\n\n**Documentation:** [docs/README.md](docs/README.md) is the index for technical docs (architecture, packaging, roadmap, benchmarks). **AI / editor agents:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md); Cursor uses `.cursor/` symlinks — [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n---\n\n## Install\n\n```bash\nbun add @stainless-code/codemap\n# or: npm install @stainless-code/codemap\n```\n\n**Engines:** Node **`^20.19.0 || \u003e=22.12.0`** and/or Bun **`\u003e=1.0.0`** — see `package.json` and [docs/packaging.md](docs/packaging.md).\n\n---\n\n## CLI\n\n- **Installed package:** `codemap`, `bunx @stainless-code/codemap`, or `node node_modules/@stainless-code/codemap/dist/index.mjs`\n- **This repo (dev):** `bun src/index.ts` (same flags)\n\n```bash\n# Index project root (optional codemap.config.ts / codemap.config.json)\ncodemap\n\n# Version (also: codemap --version, codemap -V)\ncodemap version\n\n# Full rebuild\ncodemap --full\n\n# SQL against the index (after at least one index run)\ncodemap query \"SELECT name, file_path FROM symbols LIMIT 10\"\n\n# Another project\ncodemap --root /path/to/repo --full\n\n# Explicit config\ncodemap --config /path/to/codemap.config.json --full\n\n# Re-index only given paths (relative to project root)\ncodemap --files src/a.ts src/b.tsx\n\n# Scaffold .agents/ rules and skills from bundled templates (see CONTRIBUTING)\ncodemap agents init\ncodemap agents init --force\n```\n\n**Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).\n\n**Configuration:** optional **`codemap.config.ts`** (default export object or async factory) or **`codemap.config.json`**. Shape: [codemap.config.example.json](codemap.config.example.json). Runtime validation (**Zod**, strict keys) and API surface: [docs/architecture.md § User config](docs/architecture.md#user-config). When developing inside this repo you can use `defineConfig` from `@stainless-code/codemap` or `./src/config`. If you set **`include`**, it **replaces** the default glob list entirely.\n\n---\n\n## Programmatic API (ESM)\n\n```ts\nimport { createCodemap } from \"@stainless-code/codemap\";\n\nconst cm = await createCodemap({ root: \"/path/to/repo\" });\nawait cm.index({ mode: \"incremental\" });\nawait cm.index({ mode: \"full\" });\nawait cm.index({ mode: \"files\", files: [\"src/a.ts\"] });\nawait cm.index({ quiet: true });\n\nconst rows = cm.query(\"SELECT name FROM symbols LIMIT 5\");\n```\n\n`createCodemap` configures a process-global runtime (`initCodemap`); only **one active project per process** is supported. Advanced: `runCodemapIndex` for an open DB handle. **Module layout:** [docs/architecture.md § Layering](docs/architecture.md#layering).\n\n---\n\n## Development\n\nTooling: **Oxfmt**, **Oxlint**, **tsgo** (`@typescript/native-preview`).\n\n| Command                              | Purpose                                                          |\n| ------------------------------------ | ---------------------------------------------------------------- |\n| `bun run dev`                        | Run the CLI from source (same as `bun src/index.ts`)             |\n| `bun run check`                      | Build, format check, lint, tests, typecheck — run before pushing |\n| `bun run fix`                        | Apply lint fixes, then format                                    |\n| `bun run test` / `bun run typecheck` | Focused checks                                                   |\n\n```bash\nbun install\nbun run check    # build + format:check + lint + test + typecheck\nbun run fix      # oxlint --fix, then oxfmt\n```\n\n**Readability \u0026 DX:** Prefer clear names and small functions; keep **JSDoc** on public exports. [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) has contributor workflow and conventions.\n\n---\n\n## Benchmark\n\n```bash\nCODEMAP_ROOT=/path/to/indexed-repo bun src/benchmark.ts\n```\n\nDetails: [docs/benchmark.md](docs/benchmark.md).\n\n---\n\n## Organization\n\nDeveloped under **[stainless-code](https://github.com/stainless-code)** on GitHub.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstainless-code%2Fcodemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstainless-code%2Fcodemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstainless-code%2Fcodemap/lists"}