🗺️ A Map for Your Codebase, Not Another Agent

✨ What is Astrograph?

Astrograph gives AI coding agents a local, structured map of your codebase. Instead of reading whole repositories into context, they can ask for outlines, symbols, source, and targeted task context.

🚫 What it is not

Astrograph is not another coding agent, a hosted code service, or a replacement for your editor, Git, or tests. Your code stays local. It is also not a generic vector database or RAG service: it builds a structured code index for precise retrieval. Read the concepts guide when you want the deeper model.

🚀 Start Here

In the repository you want to explore:

npx --yes astrograph

Choose your AI client and setup scope, then restart the client.

• This device connects your client once and keeps a private index for each repository. It does not change repositories unless you opt into indexing one.
• This repository creates project-owned configuration that collaborators can review.

The installer explains every write before it makes it. For automation and recovery commands, use the CLI reference.

New to Astrograph? Follow the five-minute setup.

✨ What You Get

• 🧠 Persistent local context — an index per repository, stored on your machine
• 🔍 Progressive retrieval — outlines, symbols, source, then bounded context when needed
• 🛠️ MCP + CLI surfaces — the same engine for Codex, Copilot, and the shell
• 🧹 Health and refresh tools — inspect stale indexes instead of guessing
• 🧪 Measured output efficiency — source-grounded results with explicit evidence

🧪 Evidence, Not Promises

Astrograph ships reproducible benchmarks. The current compact-response baseline uses 55.6%–66.7% fewer cl100k_base tokens on its fixture; it is a response-size measurement, not a productivity claim. See benchmark evidence for the method and limits.

📚 Documentation

Start with the five-minute setup, then choose the document that matches your task:

• Docs compendium
• Concepts
• First steps
• Retrieval workflows
• Troubleshooting
• Performance and benchmark evidence
• CLI reference and config reference
• Language support
• Release reference

Requirements

Astrograph supports Node 20.19+, 22, and 24. Git is optional: without it, Astrograph uses a safe filesystem fallback. Its parser uses packaged WebAssembly grammars, so installing Astrograph does not compile Tree-sitter or require a C++ toolchain for parsing.

⚖️ License

MIT. See LICENSE.

🙏 Acknowledgements

• pnpm, Turborepo, Vite, React, and Vitest for the core workspace foundation
• Tree-sitter and its grammar maintainers for local, structured parsing
• the Model Context Protocol ecosystem for a common agent integration surface
• the open-source maintainers whose work makes local-first developer tooling possible

👤 Author

Morten Broesby-Olsen (mortenbroesby)

• GitHub: @mortenbroesby
• LinkedIn: mortenbroesby