magellan - Render structured technical walkthroughs into terminal, markdown, or HTML output.
MANDATORY: Your job is to produce rendered artifacts, not prose explanations.
After writing JSON, you MUST run:
magellan go --input /tmp/magellan.json
This single command validates, renders HTML (opens it in the browser), and
writes a markdown file. Do not skip it. Do not summarize in chat instead.
The rendered HTML and markdown files ARE the deliverable.
Magellan is a deterministic presentation engine for AI-generated walkthroughs.
It does not inspect a repository by itself and it does not call an LLM.
An agent or engineer gathers evidence, writes a structured JSON payload, and
then uses Magellan to validate and render that payload.
Usage:
magellan go --input <payload.json|-> [--out <path>] [--markdown-out <path>]
magellan schema
magellan prompt --agent-type <codex|claude> [--source <session|diff|branch|pr>] [--goal <walkthrough|followup|handoff>] [options]
magellan example --preset <walkthrough|timeline|before-after|followup>
magellan validate --input <payload.json|->
magellan render --input <payload.json|-> --format <terminal|markdown|html> [--out <path>] [--open]
magellan guide
Commands:
go Validate, render HTML, open it, and write markdown — all in one step.
schema Print the JSON Schema for Magellan's input payload.
prompt Print an agent-oriented prompt template for producing a Magellan walkthrough.
example Print a starter payload that agents can edit before rendering.
validate Validate a JSON payload without rendering it.
render Render a JSON payload into terminal, markdown, or HTML output.
guide Print this help text.
Global options:
-h, --help Print this help text.
-V, --version Print version.
Core rule:
Explain behavior, flow, architecture, timeline, or verification.
Do not narrate file churn.
Normal workflow:
1. Decide what evidence you are using.
- persisted session transcripts, tool actions, and timestamps
- current diff or commit range
- branch compared to trunk
- pull request description, comments, and diff
2. Learn the payload contract.
- run: `magellan schema`
- optional starter payload: `magellan example --preset walkthrough`
3. Write a JSON payload with:
- `title`
- `summary`
- `sections`
- optional `verification`
4. Validate and render. This step is mandatory, do not skip it.
- run: `magellan go --input /tmp/magellan.json`
Common requests:
Explain the last commit:
- use the current diff or `git show HEAD` as the main evidence
- `magellan prompt --agent-type codex --source diff --goal followup --question "what did the last commit implement?"`
Explain what we did yesterday or on a specific day:
- inspect persisted session transcripts for that day first; if they are unavailable, say that and label any diff or commit reconstruction as fallback evidence
- `magellan prompt --agent-type codex --source session --goal walkthrough --topic "what we built yesterday"`
- `magellan prompt --agent-type claude --source session --goal followup --question "what did we do on March 15, 2026?"`
Explain what we did in the last session or a named session:
- inspect persisted Codex or Claude session transcripts first and stay scoped to the relevant session
- `magellan prompt --agent-type codex --source session --goal walkthrough --topic "what we built in the last session"`
- `magellan prompt --agent-type claude --source session --goal followup --question "what did we implement in session X?"`
Explain what changed in commit X or on branch Y:
- use that commit diff or branch comparison as the main evidence
- `magellan prompt --agent-type codex --source diff --goal followup --question "what changed in commit <sha>?"`
- `magellan prompt --agent-type claude --source branch --goal walkthrough --topic "what changed on branch <name>"`
Session evidence:
When the evidence source is a prior coding session:
- inspect persisted session transcripts before using git history as a proxy
- Codex usually stores them under `$CODEX_HOME/sessions/YYYY/MM/DD/*.jsonl` and commonly `~/.codex/sessions/...`
- Claude Code usually stores per-project transcripts under `~/.claude/projects/<workspace-slug>/<session-id>.jsonl` and uses `sessions-index.json` to help locate them
- stay scoped to the current workspace or clearly relevant session
- if transcript persistence is unavailable, say that explicitly and label any diff or commit reconstruction as fallback evidence, not the session itself
Content rules:
- Keep the summary to 1-2 short paragraphs.
- Keep sections to 3-6 focused chunks.
- Keep section text short.
- In HTML, each section becomes a page in book view.
- In book view, diagrams can be clicked to enlarge.
- Use diagrams only when they make the technical explanation easier to follow.
- Ground the content in real evidence from code, diffs, tests, and persisted session history.
Diagram picking:
sequence Request or actor-by-actor interaction flow
flow Branching logic or state movement
component_graph Steady-state relationships between modules or layers
timeline Ordered work, debugging steps, or event progression
before_after User-visible behavior change
Prompt workflow:
Use `magellan prompt` when you want Magellan to teach the agent how to build
the payload.
Useful prompt knobs:
- `--source`: where the evidence comes from
- `--goal`: broad walkthrough, follow-up answer, or engineer handoff
- `--question`: a narrow question to answer directly
- `--scope`: keep the artifact inside a subsystem, route, or flow
- `--focus`: emphasize behavior, architecture, timeline, verification, or decisions
Examples:
- `magellan prompt --agent-type codex`
- `magellan prompt --agent-type codex --source session --goal walkthrough`
- `magellan prompt --agent-type codex --source diff --goal followup --question "why did this flow change?"`
- `magellan prompt --agent-type claude --source branch --goal handoff --scope backend --scope tests --focus verification --focus decisions`
Render targets:
Use `magellan go` to validate and produce both HTML and markdown in one step:
magellan go --input /tmp/magellan.json
html Opened in the browser for a paced visual walkthrough
markdown Also saved to disk for sharing, docs, or PR comments with Mermaid blocks
terminal Only use when explicitly requested via `magellan render --format terminal`
HTML behavior:
HTML reports are self-contained and open in book view by default.
Book view:
- starts with the summary
- shows one technical slice per page
- supports page navigation
- lets the user click diagrams to enlarge them
Overview view:
- shows the full walkthrough as one stacked report
Reference files:
Use these checked-in payloads when you want realistic examples:
- `examples/session-walkthrough.json`
- `examples/branch-handoff-timeline.json`
- `examples/followup-validation-question.json`
Fast paths:
Learn the contract:
- `magellan schema`
Start from a built-in preset:
- `magellan example --preset timeline`
- `magellan example --preset followup`
Study a realistic HTML report:
- `magellan render --input examples/session-walkthrough.json --format html --open`
Answer a focused follow-up:
- `magellan prompt --agent-type codex --source diff --goal followup --question "why did this API flow change?"`
Prepare a handoff:
- `magellan prompt --agent-type claude --source branch --goal handoff --scope backend --scope tests`
Validate and render (the mandatory final step):
- `magellan go --input /tmp/magellan.json`
REMINDER: You MUST run `magellan go` after creating the JSON.
The task is not complete until the HTML report is open in the browser and the
markdown file exists on disk. A prose summary in chat is not a substitute.