Code maps

A code map is the bird's-eye view of how your product is wired, derived from the source itself: every screen is a node, navigation between screens are edges, and the API/data calls a screen makes are attached to it.

Scan

alkahest scan

Runs at the project root, parses the source statically (nothing executes), and writes .alkahest/map.json. Preview locally with alkahest view — no account needed.

Because the map is derived, it can't go stale the way hand-drawn diagrams do: re-scan and it reflects reality.

Publish

alkahest publish

Uploads the map to the hosted viewer and returns the link. The first publish creates the project; later publishes update the same link. The checkout remembers its project, so a bare publish from the same directory always lands in the right place (or pass --slug).

Each publish records a version with a node-level diff — the account's Maps page shows a "Publish history…" timeline, and the activity journal shows exactly which screens and resources were added or removed.

Several code maps per project

A project holds as many maps as you like — say web and api code maps in a monorepo:

alkahest publish --map web    # publish to (or create) the 'web' code map
alkahest publish --map api

Each map lives at its own link (alkahest.app/p/:project/:map). With a single code map you never need --map; with several, the CLI tells you which ones exist if you omit it.

Reading the map

The hosted viewer is an interactive graph — pan, zoom, click a screen for its detail (summary, PRD, calls). Agents read the same map over MCP (overview, get_screen, who_calls) and can attach a one-line summary or a short prd to any screen, which the viewer renders.

Comments can be pinned to any node — see Sharing & permissions for who can read and write.