Documentation
Every page in docs/ of the repository, grouped and rendered here from the public main branch. Each page links to its source on GitHub.
Start here
Three pages explain most of what you see on the first day.
docs/setup.md
Setup and intro
First start detects logins, engines and keys on one screen; choose model, tier, permission, look and what to import.
docs/tiers.md
Tiers and safe mode
Minimalist, balanced and full, the features each one turns on, per-feature overrides and safe mode.
docs/permissions.md
Permissions
read, write and execute on every tool call; rules, modes and what asks by default.
105 pages
Start
Install, the first launch, tiers, upgrades and moving your setup.
- Setup and introFirst start detects logins, engines and keys on one screen; choose model, tier, permission, look and what to import.
docs/setup.md - Connecting providers/connect for API keys and ChatGPT OAuth, /providers to manage them. The terminal never handles OAuth tokens.
docs/connect.md - API-key providersEvery supported API provider, including Google Vertex AI through daemon-owned ADC.
docs/providers.md - Tiers and safe modeMinimalist, balanced and full, the features each one turns on, per-feature overrides and safe mode.
docs/tiers.md - Upgrading MendCodemendcode upgrade: channels, exact targets, signature checks and --rollback to the previous binary.
docs/upgrade.md - UninstallReviews exact paths and byte counts first, moves them to a recoverable trash, can keep config or data.
docs/uninstall.md - Importing legacy historymendcode migrate-v1 copies v1 history into a v2 data directory. Safe to rerun; never writes to v1.
docs/migrate-v1.md - Personal configuration bundlesMove your own setup between data directories, a laptop to a server, as one file you can check.
docs/config-bundle.md - Performance budgetsMemory, startup and size budgets, how they are measured and the dated baseline.
docs/performance.md - Disk usageThousands of sessions and worktrees in well under 1 GB; retention and what is stored where.
docs/storage.md
Engines and models
Which agent runs a turn, which model it uses and what it may spend.
- Claude CodeRun a session on your own Claude Code: pick a Claude model in /model and that session's turns go to claude.
docs/claude-code.md - ACP agentsRun a session on any agent that speaks the Agent Client Protocol, such as Gemini CLI or Zed's adapters.
docs/acp-engine.md - pi engineRun a session on your own pi: it keeps its loop, tools, models and login; MendCode shows the turn.
docs/pi-engine.md - Advanced agent and model configurationAgent and model settings: layers, task models, model denies and provider allowlists.
docs/advanced-config.md - Reasoning controls/model reasoning: the policy and runtime grid for reasoning effort per model.
docs/reasoning.md - Prompt modes and focusInstruction files, @path includes and how much MendCode context each prompt mode adds.
docs/prompt-modes.md - Prompt cache modeslegacy, off or smart: which cache hints the native engine sends with each model call.
docs/prompt-cache.md - Compound orchestration/compound: opt-in single, cascade or critic execution, frozen with its hash and pricing.
docs/compound.md - Code ModeThe model gets one code tool: a confined JavaScript program that calls the permission-filtered catalog.
docs/code-mode.md - AI configuration previewsInspect models and roles, plan a recipe, validate its diff and save it. Never calls a provider.
docs/ai-config.md - Global USD budgetsWarn and stop thresholds in dollars, prices, and confirmation before expensive models.
docs/budgets.md - Usage dashboardTokens, context sections and tool results per session, and how each estimate is computed.
docs/usage.md - Usage-limit pause and resumeA checkpoint before a provider quota runs out, and resuming the session when it resets.
docs/usage-limit.md
Sessions and work
Long work: compaction, goals, loops, workflows, agents and Git.
- Session historyFork at a message, undo and redo, the timeline, titles and export.
docs/sessions.md - Compaction panelSectioned compaction with a request anchor, the live panel and how transcripts are stored.
docs/compaction.md - GoalsA standing objective the agent keeps working on, turn after turn, until done, blocked or over budget.
docs/goals.md - LoopsRecurring or long-running work: an objective, a trigger, a budget and a root session.
docs/loops.md - WorkflowsScript workflows: journaled, resumable, budgeted and sandboxed.
docs/workflows.md - Custom agents and sub-agentsAn agent is a markdown file: frontmatter to configure it, a body added to its system prompt.
docs/agents.md - PeersSessions of the same project talk to each other through two agent tools.
docs/peers.md - One treeSeveral sessions, one checkout: no worktree per agent and no merge for every change.
docs/one-tree.md - Worktree manager/worktrees: linked worktrees, ownership, dirty state and saved plans; merged only after apply.
docs/worktrees.md - Git page/git with Changes, Commit, Worktrees and PR tabs.
docs/git.md - Changes review/changes, plan approvals and pasted-secret markers, shared with the model through the daemon.
docs/changes.md - Plan reviewRead-only plan mode, plan review requests and approving or revising a plan.
docs/plan-review.md - PR reviewerReviews PRs with your own model: one pass finds defects, an independent pass tries to refute them.
docs/pr-review.md - PR reviewer: team setupThe hosted workflow, an always-on server with personal reviewers on laptops, and what happens while a laptop sleeps.
docs/pr-review-setup.md - PR watchLink a pull request; the session wakes only when CI or a review changes, at no model cost.
docs/pr-watch.md - /btwA persistent side chat about the current session. It cannot run tools or read files.
docs/btw.md - MemoryMemory with consent: proposals, retrieval, editing, Codex import and scoped configuration.
docs/memory.md - DreamThe background job that reads recent conversations and proposes memories. It never edits files or runs commands.
docs/dream.md - EvolutionCorrections that recur across sessions become memory proposals or skill suggestions.
docs/evolution.md - ProfilesA profile is a set of folders; a session belongs to the profile that contains its project.
docs/profiles.md
Tools and safety
What the model can call, and the permissions, sandbox and secrets around it.
- Permissionsread, write and execute on every tool call; rules, modes and what asks by default.
docs/permissions.md - OS sandbox for shell commandsAn opt-in OS sandbox under the permission rules for the commands the model runs.
docs/sandbox.md - Pasted secretsPasted keys become markers the model never sees, and the limits of that detection.
docs/secrets.md - Environment credentials and chat encryptionNamed credentials with /env and opt-in chat encryption with /privacy, on every tier.
docs/environment-privacy.md - Shell hooks and project trustRun your own command at points of a session, the way Claude Code and Codex hooks do.
docs/hooks.md - File reads and attachmentsread for text, directories, images and PDFs, with paging and size limits.
docs/attachments.md - Browser toolA Chromium tool with multiple tabs, each action behind its own approval.
docs/browser.md - Web search and image generationwebfetch modes for pages, PDFs and public repositories, web search and image generation.
docs/tools-web.md - Native ComputerOpt-in macOS screen control; disabled means no helper, capture or OS permission request.
docs/computer.md - Code graphA local code graph for orientation, symbol search and callers, behind permissions.
docs/code-graph.md - Language serversDefinitions, references, hover, symbols and call hierarchy from language servers.
docs/lsp.md - FormattersFiles written by the model are formatted before diagnostics and the next model call.
docs/formatters.md - Interactive and model-tool additionsModel-callable tools beside shell, with no startup process or route of their own.
docs/interactive-tools.md - Async tools and questionsOpt-in background jobs whose results reach the session through a persisted mailbox.
docs/async-tools.md - Tool discoveryLoad tools on demand with tool_search instead of sending every schema each call.
docs/tool-discovery.md - PackagesOne package changes how MendCode looks and what it offers; removing it puts everything back.
docs/packages.md - Extensions (daemon half)Trusted TypeScript modules that change how MendCode runs: hooks and tools.
docs/extensions.md - Remote MCP servers and OAuthAdding remote MCP servers, the OAuth flow and pending approval.
docs/mcp-oauth.md - Thread MCP bridgeLets Claude Code, Codex and ACP agents delegate to MendCode threads over MCP. Full tier, off by default.
docs/thread-mcp.md
Terminal
Pages, panels, keys, view slots and everything you see in the TUI.
- Customize, settings, status and extensionsFour in-terminal pages opened with a slash command, with an automation interface behind them.
docs/customize.md - Terminal profile keysEvery /customize row is a terminal profile key you can set from a file or a package.
docs/profile-keys.md - View slotsReplace how any named part of the terminal is drawn; every slot follows one contract.
docs/views.md - Terminal extensions and keybindingsTypeScript modules that draw, add commands and pages, bind keys and reshape tool cards.
docs/extensions-tui.md - Terminal layoutBreakpoints, the sidebar, the dock and long transcripts at every terminal size.
docs/layout.md - Session panel/panel opens cards beside the chat; presets, the narrow sheet and its keys.
docs/sidebar.md - Prompt editorThe prompt box: editing keys, quoting a selection with a comment and drafts.
docs/editor.md - File viewerClick a path in the conversation and the file opens beside it with the cited lines selected.
docs/file-viewer.md - Terminal Mermaid diagramsMermaid fences drawn as Unicode diagrams, and /diagram on a scrollable canvas.
docs/mermaid.md - /fetchA neofetch-style card of the project and MendCode, instant and offline.
docs/fetch.md - Commands/init, /review and the other bundled commands, and how to define your own.
docs/commands.md - Accessibility and screen-reader modeLinear output, nothing that moves, plain text for screen readers and braille displays.
docs/accessibility.md - Voice dictationPush-to-talk dictation into the prompt, off by default.
docs/voice.md - Return, recovery and environmentFocus-aware notifications, a recap when you come back, and recovery.
docs/return.md - herdr and tuiosherdr and tuios sidebars show what a session is doing, with nothing to install.
docs/herdr.md - Terminal-session adapter/tsm: the terminal-session manager and multiplexer activation.
docs/tsm.md - Mflow coordination/mflow: the room manager, relay and private token file.
docs/mflow.md
Integrations and REST
Embedding, automation, GitHub, remote channels and the opt-in HTTP adapter.
- Embedding MendCode in another UIDrive MendCode from another UI over JSON-RPC on stdio, the way codex app-server works.
docs/embedding.md - Automation CLImendcode exposes the daemon to scripts, CI and VPS jobs: one command, one action, then exit.
docs/automation.md - GitHub automationPreview and write a workflow file, run MendCode in CI and check out PRs.
docs/github.md - Remote channels (Telegram)Drive a session from a phone: prompts, answers and approvals. Off by default.
docs/channels.md - Remote attachThe opt-in loopback HTTP adapter, tokens and attaching another client.
docs/remote.md - Console and session sharingOff by default; a loopback origin and a private token file, no public backend.
docs/console.md - Tracing--trace for correlated RPC, turn, model-attempt and frame diagnostics.
docs/tracing.md - Resources and config safetyDaemon settings for proxy, shell environment, web and instruction files, and who may set them.
docs/resources-config.md - PTY APIReal interactive PTYs owned by the daemon, off by default.
docs/pty.md - Catalog RESTv1 catalog and control routes over the opt-in adapter.
docs/catalog-rest.md - File and find RESTSix file and search routes, each requiring a full token.
docs/file-rest.md - Permission, question, plan and memory RESTAnswer pending requests over the opt-in adapter.
docs/interaction-rest.md - Project, worktree and workspace RESTProject and worktree routes; mutations reject browser origins.
docs/project-rest.md - Global and config RESTHealth, config and the global event stream.
docs/server-rest.md - Session RESTSessions through the existing daemon, loopback only.
docs/session-rest.md - TUI control RESTControl a running terminal over the adapter with a full token.
docs/tui-rest.md - Workflow RESTWorkflow snapshots, revisions and ledgers over the adapter.
docs/workflow-rest.md
Records
Release process, audits and measurement procedures, kept as written.
- ReleasesThe release workflow, channels, signatures and the published assets.
docs/release.md - Security pass, October 2026A bounded review of the surfaces added on October 3 and what changed.
docs/security-2026-10-04.md - Unfinished-work auditSource, commands, settings, tests and docs checked for work left half done.
docs/halfdone-audit.md - Optional engines: withdrawnWhy the OpenCode serve and Cursor SDK adapters were removed.
docs/optional-engines.md - Terminal smokeA real-PTY smoke run of the shipped CLI and daemon on macOS or Linux.
docs/pty-smoke.md - Design: one process per terminalWhy one terminal can host the daemon in its own process, and the RAM and first-frame trade-off, measured.
docs/design/memory-single-process.md - Design: the full Markdown rendererThe full message renderer compared feature by feature with a Claude Code mod: what was added, what was left out, every colour slot.
docs/design/markdown-parity.md - Design: tool cardsWhy the balanced and full tool cards look the way they do.
docs/design/tool-cards.md - Design: the rename to MendCodeEvery place the name MendCode v2 appeared, what changed and what was kept on purpose.
docs/design/rename-inventory.md