Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 auto for 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 --afk for headless runs.
  • The guardian: what auto mode 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 agent and send_message tools, asynchronous subagents, agent types and agent files, the agent lifecycle (idle, wake, retire, resume), task boards (any agent can own one, with board_show and board_update), the permission-mode rules, budgets, and the agents panel.
  • Remote control: fontaine --remote, /remote and fontaine 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, http and prompt handlers, 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, the fontaine mcp command, workspace trust and per-server approval, and how MCP tools are gated.
  • Instruction files: FONTAINE.md, CLAUDE.md and AGENTS.md from your config, every parent directory and nested directories, @path imports, rules scoped by path, what the guardian reads, /memory and /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 plugin CLI and /plugin and /reload-plugins for 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), /cost and /usage (token usage and spend by source and by model), /context, /config, /theme, /loop and scheduled prompts, /goal, /resume, /branch, /rename, /export and /rewind, /afk report, the agents panel and the workspace trust prompt.
  • Verifying releases: what is signed on the release and dev channels, the public keys, and how to verify an archive with minisign and sha256sum.
  • Checkpoints and /rewind: what write and edit save before they change a file, /rewind and 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 fontaine as the executable of an unmodified TypeScript or Python Agent SDK application, what is supported, how canUseTool stays 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-sdk crate: a session builder, host tools and hooks, an approval callback and a typed event stream that is headless-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.