{"id":51321032,"url":"https://github.com/orafaelfragoso/columbus","last_synced_at":"2026-07-01T13:32:17.732Z","repository":{"id":363105597,"uuid":"1261493377","full_name":"orafaelfragoso/columbus","owner":"orafaelfragoso","description":"The navigator your coding agent has been missing — a local-only, deterministic code-context server.","archived":false,"fork":false,"pushed_at":"2026-06-15T09:30:18.000Z","size":1738,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T12:37:46.914Z","etag":null,"topics":["ai-agents","cli","code-context","code-search","developer-tools","golang","llm","local-first","tree-sitter"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/orafaelfragoso/columbus","language":"Go","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/orafaelfragoso.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-06T19:03:26.000Z","updated_at":"2026-06-10T20:27:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/orafaelfragoso/columbus","commit_stats":null,"previous_names":["orafaelfragoso/columbus"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/orafaelfragoso/columbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orafaelfragoso%2Fcolumbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orafaelfragoso%2Fcolumbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orafaelfragoso%2Fcolumbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orafaelfragoso%2Fcolumbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orafaelfragoso","download_url":"https://codeload.github.com/orafaelfragoso/columbus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orafaelfragoso%2Fcolumbus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35009270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","cli","code-context","code-search","developer-tools","golang","llm","local-first","tree-sitter"],"created_at":"2026-07-01T13:32:17.642Z","updated_at":"2026-07-01T13:32:17.723Z","avatar_url":"https://github.com/orafaelfragoso.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\".github/columbus.jpg\" alt=\"Columbus — local-only context server for LLM agents\" width=\"100%\" /\u003e\n\n\u003cbr /\u003e\n\n**The navigator your coding agent has been missing.**\n\n[![CI](https://github.com/orafaelfragoso/columbus/actions/workflows/ci.yml/badge.svg)](https://github.com/orafaelfragoso/columbus/actions/workflows/ci.yml)\n[![Release](https://github.com/orafaelfragoso/columbus/actions/workflows/release.yml/badge.svg)](https://github.com/orafaelfragoso/columbus/actions/workflows/release.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/orafaelfragoso/columbus.svg)](https://pkg.go.dev/github.com/orafaelfragoso/columbus)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n📖 **[Documentation \u0026 Guides](https://github.com/orafaelfragoso/columbus/wiki)** · [Quick Start](https://github.com/orafaelfragoso/columbus/wiki/Quick-Start) · [Using with your agent](https://github.com/orafaelfragoso/columbus/wiki/Using-Columbus-with-Your-Agent)\n\n\u003c/div\u003e\n\nYour coding agent is brilliant at reasoning and bad at locating and remembering.\nSo it greps in the dark, reads whole files to use ten lines, and leans on stale\n`.md` context that quietly lies.\n\n**Columbus** is a **local-only, semantic code-context server** your agent calls\nas a tool. Ask it — in plain language — where something is and get ranked,\nLLM-ready context with **exact line ranges**, reconstructed live from your\nworking tree so it's **never stale**. It also owns your project's durable\nmemory, so the agent stops re-discovering the codebase every session.\n\n_Local embeddings, no cloud, no LLM calls — natural-language search that stays on\nyour machine._\n\n\u003e [!IMPORTANT]\n\u003e **It cannot go stale, because it never stores your code.** The database holds\n\u003e **metadata, git anchors and embedding vectors only** — every snippet and exact\n\u003e line range is rebuilt live at query time by re-parsing the working tree. The\n\u003e vectors are a derived index, not your source; the answer always matches the\n\u003e code as it is *right now*.\n\nColumbus does exactly three things:\n\n1. **Index** — chart the codebase with embedded tree-sitter and embed each\n   symbol/file on-device (metadata + git anchors + vectors, never your code).\n2. **Search** — natural-language semantic search: vector retrieval re-ranked by\n   deterministic heuristics, returning ranked context with exact line ranges.\n3. **Memory** — own the project's durable record: ADRs, plans and\n   documentation with tags, links, evidence anchors, and drift checks.\n\nEmbeddings run **on-device** with bundled Model2Vec assets\n(`minishlab/potion-code-16M`); there are no LLM calls and nothing leaves your\nmachine. Ranking, \"why relevant\" text, and risk hints are deterministic.\n\n## Why Columbus\n\nThe agent is great at the thinking. It's the *finding* and *remembering* that\nbleed tokens and go wrong. Columbus takes that off its plate.\n\n| Without Columbus | With Columbus |\n|---|---|\n| Greps for the exact word and misses the concept | **Natural-language** semantic search finds it by meaning |\n| Reads whole files to find ten relevant lines | One call returns ranked context with **exact line ranges** |\n| Context drifts; stale `.md` files confidently lie | Snippets rebuilt **live** from the working tree — never stale |\n| Re-discovers the codebase every session | **Durable memory** — ADRs, plans \u0026 documentation persist |\n| Repo cluttered with `.cursorrules` / scattered context files | Memory is queryable and **git-excluded**, not committed noise |\n| Embeddings shipped to a cloud, per-query cost | **On-device** embeddings, zero LLM calls, nothing leaves your machine |\n\n\u003e [!NOTE]\n\u003e **Proof, measured.** A with/without study (tokens to first correct location,\n\u003e total session tokens, tool calls, run-to-run variance) is in progress — real\n\u003e numbers will land here. _Placeholder; not yet published._\n\n## Install\n\nRequires Go 1.26+ and a C compiler for the embedded tree-sitter grammars.\nColumbus is built with `-tags fts5`. The SQLite, vector, and embedding stack is\npure Go, so no ONNX, tokenizer, or SQLite native libraries are required.\n\n### Release archives\n\nDownload the archive for your platform from\n[Releases](https://github.com/orafaelfragoso/columbus/releases). Each archive\nships a single `columbus` binary with the model assets embedded, so local\nnatural-language (vector) search works out of the box with no network at\nruntime.\n\n### Build from source\n\n```sh\nbrew install ripgrep ast-grep\nmake setup        # fetch Model2Vec assets into internal/embed/assets\nmake install      # built with -tags fts5 and CGO_ENABLED=1 by default\n```\n\n`git` is the only hard runtime dependency. `ripgrep` is the recommended search\nfast-path (a pure-Go fallback covers the rest); `ast-grep` is optional. The\nSQLite metadata store and `vec0` vector search use the pure-Go modernc driver;\nthe embedding engine uses a pure-Go Model2Vec runtime and embedded safetensors\nweights.\n\n## Quick start\n\n```sh\ncolumbus install                 # onboard: write .columbus.json, create db, first index + embed\ncolumbus search \"parse config\"   # ranked, LLM-ready context with exact line ranges\ncolumbus reindex                 # re-chunk + re-embed only what changed\ncolumbus view                    # full-screen dashboard (index stats + memory table)\ncolumbus doctor                  # verify git, vec0, model runtime + index health\n```\n\nThen point your agent at Columbus as a tool (see\n[Use it with your agent](#use-it-with-your-agent)). The agent stops grepping and\nstarts asking; `columbus view` gives *you* the live view of what it's doing.\n\n## Documentation\n\nFull guides and reference live in the **[Columbus Wiki](https://github.com/orafaelfragoso/columbus/wiki)**:\n\n- [Your First Index \u0026 Search](https://github.com/orafaelfragoso/columbus/wiki/Your-First-Index-and-Search) — guided tour with real output\n- [Using Columbus with Your Agent](https://github.com/orafaelfragoso/columbus/wiki/Using-Columbus-with-Your-Agent) — the skills model and `--json`/`--llm` contract\n- [Never Stale: Live Reconstruction](https://github.com/orafaelfragoso/columbus/wiki/Never-Stale-Live-Reconstruction) — why answers always match current code\n- [Command Reference](https://github.com/orafaelfragoso/columbus/wiki/Command-search) · [Configuration](https://github.com/orafaelfragoso/columbus/wiki/Configuration) · [FAQ](https://github.com/orafaelfragoso/columbus/wiki/FAQ)\n\n## How it works\n\nThe **chart** (the index) tells Columbus *where* things are. The **working\ntree** tells it *what they currently say*. Because Columbus never caches the\n\"what,\" it can never lie about it.\n\n```\nyour working tree ──(tree-sitter)──▶ index: metadata + git anchors   (the chart)\n        │                                          │\n        │   agent: columbus search \"parse config\"  │\n        ▼                                          ▼\n   re-parse live ◀───────────────────────  rank deterministically\n        │\n        ▼\n   ranked results + EXACT line ranges + \"why relevant\"  ──▶  LLM-ready\n```\n\nIndexing is incremental and cheap, but even a stale index can't produce a stale\n*answer*: the snippet and line range you get back are reconstructed from the\nfile as it exists at query time.\n\n## Use it with your agent\n\nColumbus is a tool, not an autopilot. Your agent learns *when* and *how* to call\nit through **skills** — small instruction files that teach the agent the CLI\n(when to `search` before editing, how to record a decision, how to read the\ngraph). The skills live in the **agent/plugin layer**, never in this binary,\nwhich keeps Columbus a small, deterministic context server with no opinion on\nyour workflow.\n\nThe contract the agent consumes:\n\n- **`--json`** — a versioned, machine-readable contract with a canonical error\n  envelope. Stable to parse, safe to depend on.\n- **`--llm`** — markdown shaped for a context window: ranked results, exact line\n  ranges, and a short \"why relevant\" per hit.\n\nBoth are pure projections of the same typed result as the human `text` output —\nthey can never silently diverge.\n\nSearch is **locate-first**: by default it returns ranked locations, signatures,\nscores and graph edges — the cheap \"where to look\" map — and omits code bodies.\nAdd `--snippets` to attach bodies inline (capped with `--snippet-lines N`), or\npull a specific body on demand with `columbus show symbol`. Exact line ranges are\nalways present, so an agent can read first and drill down only where it matters.\n\n```sh\ncolumbus search \"where do we parse config\" --llm             # ranked locations, no bodies (cheap)\ncolumbus search \"where do we parse config\" --llm --snippets  # same, with code bodies inline\ncolumbus graphs --in internal/server --json                  # dependency graph as {nodes, edges}, machine-readable\n```\n\n\u003e [!NOTE]\n\u003e **Columbus skills** (for Claude Code and other agents) are published separately\n\u003e as plugin assets. _Link coming soon._\n\n## Commands\n\n### Lifecycle\n\n```sh\ncolumbus install                    # onboard: write config, create db, first index + embed\ncolumbus reindex                    # re-chunk + re-embed changes (also --full/--changed/--clean/--status)\ncolumbus doctor                     # environment + project health (git, vec0, runtime, model, index)\ncolumbus uninstall                  # remove config + delete the db (confirm; --yes when non-TTY)\ncolumbus purge                      # clear all records + reset config to defaults (confirm; --yes)\n```\n\n### Search \u0026 navigate\n\n```sh\ncolumbus search \"where do we parse config\"    # natural-language, ranked, LLM-ready results\ncolumbus search \"auth token check\" --kind all # code hits + full-body memory section in one call\ncolumbus show symbol Engine --in internal/search\ncolumbus show file internal/store/store.go\ncolumbus graphs --json                        # whole dependency graph as {nodes, edges}\ncolumbus graphs --role impl --in internal/store   # narrow + induce subgraph\n```\n\nSearch is semantic: the query is embedded on-device and matched by vector\nsimilarity, then re-ranked by deterministic heuristics. With no runtime library\npresent it degrades to keyword (FTS) ranking — `columbus doctor` shows which.\n\nOne search is the **master query**: alongside the ranked code hits it returns a\nMEMORIES section with the **full bodies** (plus tags, links, and evidence) of\nthe most relevant memories, and 1-hop graph edges (imports / imported-by /\ntests) per code hit — so an agent gets complete context in a single call, no\nfollow-up `show memory` needed.\n\n### Memory (durable knowledge)\n\nThree kinds — `adr` (architecture decision), `plan` (durable implementation\nplan), and `documentation` (everything else worth remembering). All of it is\nembedded and surfaces in semantic `search` with full bodies.\n\n```sh\ncolumbus memory add adr --title \"Use WAL\" --body \"readers never block writers\" \\\n  --evidence internal/store/store.go:30-40 --link symbol:Open --tag db\ncolumbus memory add plan --title \"Ship master search\" --body \"one query = full context\"\ncolumbus memory add documentation --title \"Release process\" --body \"goreleaser + zig\"\ncolumbus memory update mem_001 --title \"Use WAL mode\" --add-tag sqlite\ncolumbus memory list --kind adr --tag db\ncolumbus memory remove mem_001                  # destructive; id retired\n```\n\nMemories are a passive, durable record. Links and evidence anchors are\ndrift-checked against the indexed `file`/`symbol` targets; `show\nfile|symbol` lists in reverse the memories that reference that entity.\n\n```sh\ncolumbus show memory mem_001          # full body, tags, links, evidence\ncolumbus search \"WAL\" --kind memory   # memory-only search (full bodies)\ncolumbus memory validate              # evidence drift + link resolution report\n```\n\n### Import / export\n\n```sh\ncolumbus export --out memories.json    # portable memory doc (schema v4)\ncolumbus import memories.json          # vectors are not exported — reindex rebuilds them\n```\n\n### Dashboard\n\n`columbus view` opens a full-screen, read-mostly terminal dashboard over the\nindexed project: index freshness, file/symbol/embedding counts, memory counts,\nand a full-width memory table. It auto-refreshes, so external `columbus\nreindex`/agent edits appear on their own.\n\nKeys: `↑/↓` (or `j/k`) navigate · `enter` detail (full body, tags, links) ·\n`/` semantic search across code and memory (ranked results, snippets in\ndetail) · `esc` back · `r` refresh · `R` reindex (in-process) · `?` help ·\n`q` quit confirmation. It is a projection of the same data the JSON/LLM\ncommands expose; only `R` writes (it runs the indexer) — memory is read-only.\n\n## Output modes\n\n`text` (default, human; color only on a TTY), `--json` (machine contract), and\n`--llm` (markdown) are pure projections of the same typed result — they can\nnever silently diverge. Color follows `--no-color`, then `NO_COLOR`,\n`FORCE_COLOR`, `TERM=dumb`, and `CI`, in that order, before falling back to TTY\ndetection.\n\n### Exit codes\n\n| code | meaning |\n|---|---|\n| 0 | success (incl. \"usable with warnings\") |\n| 1 | runtime error |\n| 2 | usage error |\n| 3 | not initialized / index missing |\n| 4 | transient / retryable (e.g. index writer locked) |\n\n## Design invariants\n\n- **Data always reflects current project state.** The database stores\n  **metadata + git anchors only** — never code lines or file bodies. Snippets\n  and exact line ranges are reconstructed **live** at query time by re-parsing\n  the working tree with tree-sitter.\n- **The DB is a metadata + graph cache**, not a content store.\n- **`git` is the only hard runtime dependency.** `ripgrep` is the recommended\n  search fast-path; a pure-Go fallback covers the rest. `ast-grep` is optional.\n- **`--json` is a versioned API contract** with a canonical error envelope.\n\n## Languages (V1)\n\nTypeScript + TSX, JavaScript + JSX, Python, Go, Markdown. Adding a language is\na grammar + `.scm` queries + an extension mapping — no core changes.\n\n## Development\n\n```sh\nmake test       # go test -tags fts5 ./...\nmake vet\ngolangci-lint run ./...\nmake cover\n```\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the\n[Code of Conduct](CODE_OF_CONDUCT.md). For security reports, see\n[SECURITY.md](SECURITY.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forafaelfragoso%2Fcolumbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forafaelfragoso%2Fcolumbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forafaelfragoso%2Fcolumbus/lists"}