Astrolabe Overview

• cmd/astrolabe/main.go
• internal/agent.Agent
• internal/graph.Provider
• internal/wiki.Site
• internal/verify.Checker

Astrolabe turns a codebase into a static, verified wiki. It indexes a repository with a code graph, asks an LLM to plan and draft wiki pages with citations into real source files, machine-checks every citation and mermaid diagram against the actual checkout, optionally asks the model to fact-check itself, and emits a self-contained static bundle (Markdown, HTML, search index, symbol graph). The result is documentation that a senior engineer wrote and then audited: every behavioral claim links to the line range that supports it.

This page tells the story of one end-to-end run and points at the pages that deep-dive each subsystem.

How it works

The entry point is the CLI in cmd/astrolabe. The run dispatcher routes to three subcommands — generate (the full pipeline), check (verify an existing bundle against the repo), and version — with configuration coming from flags or environment (ASTROLABE_BASE_URL, ASTROLABE_API_KEY, ASTROLABE_MODEL, and friends) run. Generate accepts a rich set of flags: page caps, retry counts, source-URL templates that rewrite citations into forge links, incremental-build controls, and search indexing options, documented in the usage text usage. Provider precedence is explicit: --dry-run (built-in mock model) beats an ACP agent configured via astrolabe.yaml, which beats a plain OpenAI-compatible endpoint usage. The details of flag parsing, CI integration, and the check command (which re-parses a bundle's published pages and maps forge citation links back to src/ citations for re-verification loadBundlePages) are covered in CLI & Pipeline Orchestration.

The heart of a run is Agent.Run in internal/agent. It works through a fixed sequence:

1. Graph loading. The agent opens a graph.Provider — the abstraction that reads a codegraph index rooted at the repository, offering Files, Nodes, Edges, and Stats Provider. The default implementation, SQLiteProvider, reads <repo>/.codegraph/codegraph.db and shells out to the codegraph CLI to build or sync the index on Open when it is missing SQLiteProvider. See Graph Model & Providers.
2. Build mode. If a previous state.json exists with a known commit, the agent diffs the two commits and, when successful, runs incrementally — redrafting only pages affected by changed files — and falls back to a full build with a warning on any obstacle mode.
3. Planning. The agent asks the LLM to propose a page plan (which pages to write, what symbols each covers), truncating it to the --max-pages cap plan.
4. Drafting. In full mode every planned page is drafted; in incremental mode only stale pages are re-drafted draft. Drafting is an agentic tool-use loop: the model calls tools (read source, query the graph, list pages) to ground its claims, within per-phase token budgets. See Agent Core and Agent Tools & Budget.
5. Verification with retries. Drafted pages go through the harness and failing pages are re-drafted up to --retries times verifyWithRetries.
6. Emission. The agent assembles a wiki.Site — pages, per-page verification summaries, the full report as JSON, and a machine-readable symbol graph — and hands it to wiki.Writer.Write, which writes pages, HTML, the source snapshot or forge-linked citations, graph.json, and index.json emit. Finally it indexes the bundle for full-text search and writes state.json so the next run can go incremental search+state.

The LLM itself is reached through a provider-agnostic client layer (llm.Client, OpenAIClient, plus a mock for dry runs) described in LLM Client Layer; the alternative ACP agent transport is described in ACP Agent Transport. Instrumentation — GenAI-convention traces, metrics and logs — is wired throughout via Telemetry.

Verification is what distinguishes Astrolabe from a plain documentation generator. The verify.Checker statically validates every page against the repository checkout: it resolves src/<path>#L<start>-L<end> citations against real files, validates inter-page links against the site's slugs, and checks that mermaid diagram symbols exist in the codegraph universe Checker. On top of that, an optional LLM Reviewer acts as a second opinion: it presents the page together with the exact source excerpts it cites and asks the model to flag any claim the excerpts do not support, replying with a JSON verdict Reviewer. Issues surface as per-page statuses in the report and, ultimately, as pass/fail badges on the published site — see Verification (Checker & Review).

The bundle itself is defined by wiki.Site: normalized, sorted pages, an optional VersionInfo stamping the commit/tag/branch the bundle was generated from, per-page VerificationSummary entries, and a Graph payload powering the interactive graph viewer Site. The wiki.Writer renders each page both as canonical Markdown and as HTML, rewrites citations to forge URLs when a source-URL template is given (pinning them with {commit} so links cannot drift), and copies the source snapshot otherwise Writer.Write. Publishing, search, and the browser-side experience are covered by Wiki Bundle & Pages, Wiki Search, Wiki Design System (JS Bundle), WebMCP Integration, and Astro Theme & Site Rendering.

End-to-end flow

flowchart TD
    A["cmd/astrolabe generate"] --> B["internal/agent.Agent.Run"]
    B --> C["internal/graph.SQLiteProvider"]
    C --> D["plan (LLM page plan)"]
    D --> E["draft pages (tool loop)"]
    E --> F["verify.Checker"]
    F --> G["verify.Reviewer"]
    G -->|issues| E
    F -->|pass / retries exhausted| H["wiki.Writer.Write"]
    B --> I["internal/llm.OpenAIClient"]
    E --> I
    G --> I
    H --> J["static bundle: pages, graph.json, search index, state.json"]

Repository map

Reference

Generated by astrolabe from commit ecc180b3 (tag 0.4.0).