Core concepts
The nouns you need. Everything else on this site assumes these.
The relationships
Section titled “The relationships”Session
Section titled “Session”One task, one agent process, one git clone. The central row in the database and the thing the
whole UI is organized around. A session has a status (waiting, running, needs_input,
failed, archived), a prompt, a repo, a branch, a runtime, a goal, and lists of selected
skills / MCP servers / hooks / plugins.
Sessions are addressable by a numeric id or a slug, on every surface — the web UI, the REST API and the MCP tools. An all-digit identifier is an id; anything else is a slug.
Agent root
Section titled “Agent root”A named bundle of domain context: which repo, which branch, which subdirectory, which runtime, which model, which goal, and which artifacts are on by default. You pick a root when creating a session and it seeds everything else.
Zimmer’s own catalog ships ten roots. general-agent is the catch-all default
(AgentRootsConfig::DEFAULT_ROOT); zimmer is the root for working on Zimmer itself;
zimmer-orchestrator is the not-user-invocable baseline that every quick-router / chat-bubble
submission is dispatched against, and zimmer-router is its deprecated pre-rename alias, kept
so sessions created under the old name still resolve. Four catalog-mgmt-* roots are subagent roots — not
user-invocable, spawned as phases by the catalog-management lead root.
Runtime (agent harness)
Section titled “Runtime (agent harness)”Which CLI actually runs: claude_code, codex or pi. Selected per session, defaulting from
the agent root, then the global setting, then claude_code.
The three behave differently in ways that leak. Claude and Pi accept a --session-id you
generate; Codex mints its own. Claude reads --mcp-config and Pi reads a .mcp.json in the
clone; Codex reads ~/.codex/config.toml. Claude and Pi take --append-system-prompt; Codex
requires you to write into AGENTS.md. And Pi arrives with no MCP, hooks or plugins of its own
— all three are supplied by pinned Pi extensions.
→ Runtimes · Adding an agent harness
A stop condition attached to the session, chosen from config/goals.json. Four ship:
codebase-question, open-reviewed-green-pr (the default for most roots),
open-reviewed-green-pr-with-version-bump, and e2e-verified-green-pr.
A goal is appended to the prompt as text. It has no runtime enforcement.
A markdown procedure (SKILL.md) that the agent can invoke — “how to run the tests here,”
“how to deploy staging.” Resolved from the catalog and copied into .claude/skills/<id>/ in
the clone before the agent starts.
Zimmer’s catalog ships ten: seven Zimmer-specific ones plus three vendored generic workflow
skills (open-pr, wait-for-ci, recover-from-compaction-thrashing). Nine are default-on for
the zimmer root; awaken-waiting-sessions defaults on fleet-maintenance instead.
→ Skills, plugins, hooks, references
MCP server
Section titled “MCP server”A tool provider the agent can call, over stdio or HTTP. This is the session’s blast radius: the set of things the agent can do outside its own clone. Selected per session.
Eighteen ship in Zimmer’s catalog; only playwright-custom is default-on for the zimmer
root.
Plugin
Section titled “Plugin”A bundle that composes existing skills, MCP servers, and hooks under one name. It is a macro: at prepare time AIR expands it into its constituent skills, MCP servers, and hooks, which then materialize through exactly the same code path as if you’d selected them directly.
A lifecycle script registered into the agent’s own settings (.claude/settings.json), fired
on agent events. Not to be confused with transcript hooks, which are a Ruby-side plugin
system that runs inside Zimmer when new transcript messages arrive.
Catalog
Section titled “Catalog”The versioned source of all of the above. Zimmer’s catalog is the set of JSON indexes at the
repo root (skills/skills.json, mcp.json, roots.json, plugins/plugins.json,
hooks/hooks.json, references/references.json), wired together by air.json and resolved
by the AIR CLI.
Trigger
Section titled “Trigger”A rule that creates or resumes a session when something happens. Three condition types:
slack (a message in a channel), schedule (cron or one-time), and ao_event (a session
transitioned to needs_input / failed / archived). Conditions on one trigger are ORed.
Triggers are also the backing store for an agent’s own “wake me up later” and “wake me when that other session finishes” tools.
Elicitation
Section titled “Elicitation”An MCP server asking the human a question mid-session — “which environment should I deploy
to?” The agent process stays alive and blocked; the session flips to needs_input; a banner
appears in the UI; your answer is polled back by the MCP server.
Elicitations expire after an hour by default (ELICITATION_EXPIRATION_MINUTES moves it; an MCP
server can name its own deadline per request). One that ends without an answer — expired, or a
round-trip that never completed — says so on the session page instead of leaving the session
looking idle.
Transcript
Section titled “Transcript”The agent’s JSONL output file, polled off disk by the worker, normalized into the vendor-neutral
OpenTranscripts v0.1 schema, and streamed to the UI over Turbo Streams. The whole raw file is
also persisted, as append-only slices in session_transcript_chunks.