Fontaine documentation
Fontaine is a terminal AI coding agent that works with any model you configure. These pages describe what the current build does; each page covers one topic.
Start here
- Installing Fontaine: the one-line installer for Linux and macOS, what it writes,
its prerequisites and caveats, the manual archive and source installs, updating with
fontaine update, and uninstalling. - Architecture: the workspace layout, what each crate is responsible for, and how the pieces depend on each other.
- Configuration: every settings key, the settings scope stack and its merge rules, workspace trust, model accounts, where files live, and the command-line flags that affect configuration.
- Providers: every account kind side by side, how to choose between them, the easily confused pairs, and a minimal example for each.
- Tools: the built-in tools, their risk classes, workspace roots and what earns the read-only fast path, the shell and web fetch settings.
- Permissions: the modes, the deterministic floor, the
Tool(specifier)rules and allow rules, and the shell pre-classifier. - AFK mode: the permission mode after
autofor working while you are away: every would-prompt outcome becomes a denial with recovery guidance, the report of everything the agents tried, the session temperature and the stop that follows it, and--afkfor headless runs. - The guardian: what
automode asks a separate model, what it sees, how every failure becomes a denial, how to choose the guardian model, and the container-mode profile. - Subagents: the
agentandsend_messagetools, asynchronous subagents, agent types and agent files, the agent lifecycle (idle, wake, retire, resume), task boards (any agent can own one, withboard_showandboard_update), the permission-mode rules, budgets, and the agents panel. - Remote control:
fontaine --remote,/remoteandfontaine attach, a full terminal UI on another machine that drives a live session over iroh, device pairing and revoking, what a device can and cannot do, reconnecting,attach --message, relay privacy and the exit codes. - Android app: the sideloaded phone app that scans the host’s QR code, pairs through the host confirmation, and drives the session; install, pairing, reattaching and limits.
- User hooks: the tool, prompt, turn, subagent, compaction, session and notification
events, the
command,httpandprompthandlers, their JSON input and output, and what a hook can and cannot decide. - MCP servers: declaring stdio and streamable-HTTP servers in local, project
(
.mcp.json) and user scope, thefontaine mcpcommand, workspace trust and per-server approval, and how MCP tools are gated. - Instruction files:
FONTAINE.md,CLAUDE.mdandAGENTS.mdfrom your config, every parent directory and nested directories,@pathimports, rules scoped by path, what the guardian reads,/memoryand/init. fontaine doctor: the read-only check of the settings layers (including project keys the scope policy refused), effective values and their source, workspace trust, guardian and model availability, MCP servers, instruction files, hooks and skills, and auto-memory integrity.- Auto memory: the per-project notes store, how its writes are gated, what the guardian does with them, and how to audit and clear it.
- Skills, agent files and output styles: the extension files, their
frontmatter, slash commands and porting from
.claude/. - Plugins and marketplaces: Claude Code’s plugin bundles installed from
git-hosted catalogs, the tighten-only rules they load under, the
fontaine pluginCLI and/pluginand/reload-pluginsfor managing them from a running session. - The terminal UI: keys, the status bar, approval prompts, the guardian’s denials,
/denied,/login,/model,/effort,/guardian-model,/guardian-disable,/guardian-enable,/auto-mode-setup,/add-dir,/output-style,/help,/status,/permissions,/mcp,/hooks,/skills,/plugins,/plugin,/reload-plugins,/copy,/expand,/memory,/init,/clear,/compact,/btw(side questions),/recap(session report),/costand/usage(token usage and spend by source and by model),/context,/config,/theme,/loopand scheduled prompts,/goal,/resume,/branch,/rename,/exportand/rewind,/afk report, the agents panel and the workspace trust prompt. - Verifying releases: what is signed on the
releaseanddevchannels, the public keys, and how to verify an archive withminisignandsha256sum. - Checkpoints and /rewind: what
writeandeditsave before they change a file,/rewindand Esc Esc, restoring code, the conversation or both, and what is not tracked. - Terminal setup: newline keys for each terminal, tmux, Option as Meta on macOS,
colour themes and
NO_COLOR, notifications for pending prompts, and screen-reader mode. - Claude Agent SDK compatibility: using
fontaineas the executable of an unmodified TypeScript or Python Agent SDK application, what is supported, howcanUseToolstays below the permission rules, and the differences from Claude Code. - Headless runs:
fontaine -p, its flags, exit codes, and the versioned JSON output that CI and the eval runner consume. - Embedding in a Rust program: the
fontaine-sdkcrate: a session builder, host tools and hooks, an approval callback and a typed event stream that isheadless-v1, and how the Rust, stdio and Claude Agent SDK routes relate. - Claude subscription: the account kind that runs your installed Claude Code CLI as the model transport on a Max or Ultra plan, its checks, limits and billing caveats.
- Telemetry: enabling export, the micromegas and OTLP backends, what is exported, and the privacy defaults.
Evaluating the guardian
- Guardian scorecard: catch rate, false-deny rate and latency per guardian model, and the inclusion bar for the default-guardian list.
- Golden dataset and eval runner: the case format, the categories, and how to run the offline scoring and the live guardian mode.
Project
- Contributing: build and test commands, branch and commit rules, and how to submit golden-dataset cases.
- Security policy: how to report a vulnerability.
- Changelog: what changed in each release.