Agents

An agent profile defines how Geoff Code behaves: its system prompt and the set of tools it can use. The main agent you talk to runs the default profile. For substantial sub-tasks, it can delegate to a subagent — a fresh agent instance with its own context window and its own tool restrictions — and use the result without polluting the main conversation.

Why subagents

Delegation buys two things: an isolated context (the subagent starts clean and the main thread stays uncluttered) and scoped permissions (a read-only explorer can’t accidentally edit files). The trade-off is a handoff cost, so it pays off for substantial work, not for a one-line file read.

Built-in subagents

Geoff Code ships three built-in subagent profiles, each launched through the Agent tool with a subagent_type:

Profile	Role	Tools
`coder`	Non-trivial engineering: read, edit, run, and report back.	Full read/write/execute, web, and MCP tools.
`explore`	Read-only codebase investigation — fast file and code search.	Read-only `Bash`, search, and read tools. No edits.
`plan`	Architecture and step-by-step implementation planning.	Read and search tools only — no shell, no writes.

The main agent picks the profile that fits the task. A subagent’s output is returned only to its caller (the main agent), which summarizes anything you need to see.

Behavior

Each subagent keeps an independent context history under its own agent ID.
Multiple subagents can run in parallel for independent questions.
Subagents use a fixed timeout; if one times out, the parent resumes it rather than starting over.
A subagent cannot spawn its own subagents.

You can launch a swarm of agents on a coordinated task with the /swarm command in the TUI.

Custom agent profiles

Profiles are defined in YAML. The most common pattern is to extends a built-in profile and override only what you need:

name: reviewer
extends: agent
whenToUse: |
  Use for code review: read the diff, flag correctness and style issues,
  and report a structured summary. Does not modify files.
systemPromptPath: ./reviewer-system.md
tools:
  - Read
  - Grep
  - Glob
  - Bash

Field	Description
`name`	The profile’s identifier.
`extends`	Inherit from a built-in profile (for example `agent`) and override fields.
`whenToUse`	Guidance the parent agent uses to decide when to delegate to this profile.
`systemPromptPath`	Path to a Markdown system prompt for the profile.
`tools`	The tool allowlist. Use `mcp__*` to include all MCP tools.
`promptVars`	Variables injected into the system prompt (for example `roleAdditional`).

The system prompt is a Markdown template, so you can tailor tone, constraints, and output format per profile.

Skills

Give agents reusable knowledge and workflows.

Sessions

Subagent context is preserved across session resume.

Getting Started

Extending

Reference

Why subagents

Built-in subagents

Behavior

Custom agent profiles

Skills

Sessions

​Why subagents

​Built-in subagents

​Behavior

​Custom agent profiles

​Related

Skills

Sessions

Why subagents

Built-in subagents

Behavior

Custom agent profiles

Related