Glossary

Quick reference for the terms that appear across Chord’s docs.

MainAgent

The single main agent for a session. It owns the user-facing conversation and is the only agent that can spawn SubAgents. The active main mode (role) is shown in the TUI status bar and can be cycled with Tab (main view only).

SubAgent

A delegated agent spawned by the MainAgent (or another SubAgent, when delegation depth allows) to work on a focused task. SubAgents have their own conversation budget (context window), system prompt, and permissions, and report back via an agent_done event with a summary. Cycle the focused agent view across the main agent and SubAgents with Shift+Tab.

Pool (model pool)

A named, ordered list of provider/model (and model@variant) refs. Each agent references one or more pools. At runtime, Chord uses the first pool’s first ref by default and falls back through the rest when a request fails. Switch the active pool with /models, Ctrl+P, or chord headless models command.

Variant

A named parameter preset for a single model — for example claude-opus-4.7@high selects a higher reasoning effort. Variants are defined under models.<name>.variants in config.yaml and referenced as provider/model@variant inside model pools.

Compaction

The runtime process of summarizing earlier conversation into a compact context summary so a long session can keep going without exceeding the model’s context window. Auto-compaction means Chord triggers this process before the request gets too large; you can also trigger it manually with /compact. See Configuration — Context compaction.

Context window

The maximum number of tokens a model can handle in one request. For most models, the practical rule is: prompt input + requested output must fit inside this window. In config this is limit.context.

Model limits (`limit.*`)

Per-model numbers that tell Chord how much room the provider allows:

limit.context: the total request window.
limit.input: a separate input cap, only needed when the provider publishes one.
limit.output: the model’s maximum output capacity.

Split limits

A provider term for models that publish more than one limit, usually a total context window plus a separate input cap. Some GPT models work this way. If provider docs list both numbers, configure both limit.context and limit.input so Chord can compact before the input is too large.

Requested output cap (`max_output_tokens`)

The maximum output Chord asks for in a request. It is separate from the model’s own limit.output. At runtime, Chord uses the smallest applicable value: max_output_tokens, the model’s limit.output, and any remaining room in limit.context.

Oversize recovery

The retry path Chord uses after a provider rejects a request as too large. Chord compacts or trims the conversation according to the configured input budget, then retries when it can do so safely.

Worktree

A chord-managed git worktree (under <state-dir>/worktrees/<repo-id>/<slug>) with its own project key, sessions, cache, and exports. Create or enter one via chord --worktree <name> or chord worktree <name>; manage existing ones via chord worktree list / remove / finish. Useful for running multiple parallel chord tasks on the same repo without crosstalk. See Paths — Worktrees.

Skill

A reusable, on-demand piece of expertise expressed as a markdown body plus YAML frontmatter (SKILL.md). The model loads matching skills via the Skill tool when relevant — Chord does not preload them into every prompt. Discovered from .chord/skills/, .agents/skills/, ~/.config/chord/skills/, and any extra paths configured via skills.paths. See Customization — Skills.

Hook

An external command that runs at a well-defined point in Chord’s lifecycle (before a tool call, after an LLM call, on idle, etc.). Hooks receive a JSON envelope on stdin, set CHORD_HOOK_* environment variables, and may block / modify / observe depending on the trigger point’s category. See Hooks.

MCP (Model Context Protocol)

A protocol for exposing external tools or data sources to an AI agent. In Chord, MCP servers are configured under mcp: in config.yaml; each server appears as a set of tools with the prefix mcp_<server>_<tool>. Use allowed_tools to register only a curated subset and avoid sending unused tool schemas to the model.

Headless

Chord without the TUI. chord headless exposes a stdio JSONL control plane suitable for bot / gateway / automation integration. The companion project chord-gateway wraps it for chat platforms. See Headless.

Speculative execution (early tool execution)

Chord may execute a small safe subset of tool calls while the model response is still streaming (as soon as tool arguments are complete) to reduce the “finalize gap”. Speculative file mutations are real on-disk writes that get rolled back if the finalize discards the call. Always enabled; not user-configurable.

Project key

A stable, sanitized identifier Chord computes from a project’s canonical filesystem root (e.g. HOME-projects-chord for ~/projects/chord). Used as the namespace for sessions, runtime cache, exports, and worktree identity. If two distinct paths sanitize to the same key, Chord appends an 8-character fingerprint. See Paths — <project-key>.

Permission action

The result of evaluating a permission rule against a tool call. The three outcomes are:

allow — auto-execute
ask — pause and require user confirmation
deny — refuse outright

Permissions are agent-level and combine with project / global configuration. They are product-level risk control, not an OS-level sandbox. See Permissions & Safety.

Local TUI vs Local mode

“Local TUI” and “local mode” both refer to the default chord invocation: an in-process MainAgent driving a terminal UI. There is no IPC, no socket, no separate server. Contrast with chord headless, which runs the runtime without a TUI for external control planes.

Diagnostics bundle

A snapshot exported by Ctrl+G: includes recent log lines, runtime state, TUI-specific debug info, and a recent lightweight LLM request trace from the current session. Full raw request / SSE dumps still require log_level: debug. Use it when reporting bugs. See Troubleshooting — When to check logs.

Insert / Normal mode

The two TUI modes inspired by Vim. Insert is the input-focused mode where you type messages; Normal is for navigation, search, fold, scroll, and meta operations. Esc leaves Insert; i (or any unbound printable key) returns to Insert. See Keybindings.

Custom slash command

A user-defined command of the form /name [args] that, when entered in the input box, expands into a fixed (or $ARGUMENTS-templated) text and is sent to the model as a user message. Defined under commands: in config.yaml or as files under commands/. See Customization — Custom slash commands.