AgentMux docs

The documentation site for AgentMux — a desktop terminal multiplexer for AI coding agents.

Live: https://docs.agentmux.ai

Stack

• Astro + Starlight — static MPA, no client-side router.
• Content lives in src/content/docs/*.md (Markdown with frontmatter).
• Sidebar / nav is configured in astro.config.mjs.
• TypeScript API reference is generated by TypeDoc from the AgentMux source via the src/agentmux submodule.
• Rust crate reference is generated by cargo doc.

Run locally

git clone --recurse-submodules https://github.com/agentmuxai/agentmux-docs
cd agentmux-docs
npm install
npm run dev          # → http://localhost:4321

If you didn't clone with --recurse-submodules:

git submodule update --init --recursive

Build

npm run build        # Fast iterative build. Skips TypeDoc + rustdoc.
npm run build:full   # Production build. Generates TypeScript + Rust references.

Use build:full before any production deploy — build is fine for iterating on docs styling and content.

Diagrams

Architecture and internals diagrams are hand-authored SVGs in public/diagrams/, matching the design tokens in DESIGN.md (color palette, font stack, dark-mode @media query). Reference public/architecture.svg as the canonical style example.

When adding or updating a diagram:

1. Copy the structure from an existing SVG in public/diagrams/.
2. Use explicit x/y coordinates — no layout engine. This is intentional: auto-layout tools (Graphviz, D2) use abstract font metrics that don't match browser rendering, causing text to overflow boxes.
3. See DIAGRAMS.md for the full design token reference and a catalogue of all diagrams.

Source reference links

File paths and line numbers written as inline code in docs prose automatically become GitHub hyperlinks at build time via two Astro plugins in plugins/:

Plugin	What it converts
remark-github-source-links.mjs	`path/file.rs`, `file.rs:42`, `file.rs:42-78` → GitHub blob links
rehype-github-source-table.mjs	Bare line numbers in table cells (e.g. 506–611) when a sibling cell already has a file link

Rules for writing source references:

• Always use backtick inline code for file paths: `agentmux-srv/src/reducer.rs`
• Line numbers go after a colon: `reducer.rs:42` or `reducer.rs:42-78`
• The path must contain a / or be a registered alias (see aliases in astro.config.mjs) for the link to fire — bare single-word filenames not in the alias list are skipped (too many false positives with symbol names)
• Spec/design docs under specs/ in the repo are reachable as `specs/SPEC_NAME.md` (remapped to docs/specs/ automatically)
• Existing [text](url) markdown links are left untouched

Adding an alias (for short filenames used across multiple pages):

// astro.config.mjs → remarkGithubSourceLinks options → aliases
'short.rs': 'full/path/to/short.rs',

See SOURCE_LINKS.md for the full spec including the table-linking algorithm and all edge cases.

Contributing

Pull requests welcome. Page-level tips:

• New page: drop a .md / .mdx file under src/content/docs/, then wire it into the sidebar in astro.config.mjs.
• Theme changes: edit src/styles/custom.css. Test both dark AND light mode — Starlight's gray scale inverts between them. See CLAUDE.md for details.
• Assets: site logos / illustrations go in src/assets/ (Astro optimizes them). Favicons go in public/ (served as-is).
• Reference content: the TypeScript and Rust API docs are regenerated from source. Don't hand-edit anything under src/content/docs/api/typescript/ or public/api/rust/ — those directories are rewritten on each build:full.

Content accuracy is sourced from the AgentMux app code. Cross-check the running source in src/agentmux/ (the submodule) before describing behavior.

For internal deployment info (S3 / CloudFront / invalidation steps), see CLAUDE.md.

License

Documentation content is published under the same license as AgentMux itself.