Sub-agents

A sub-agent is a child agent loop with its own scratchpad, its own per-session FileStateCache scoping, and its own conversation. The parent agent drives it via the agent tool and receives only the final answer (plus optional partial updates), keeping the parent’s context lean.

When to use a sub-agent

• Wide reads. “Walk these 40 files and summarize what you find” — do it in a child so the parent’s context window survives.
• Fan-out. Spawn N children in parallel for research, triage, or per-file review, then merge results.
• Specialized prompts. A child can run with a different system prompt, model, or permission mode tailored to its task.

Built-in agents

Agent type	Description
explore	Read-only research. Bounded read-window, no shell, no edits.
general-purpose	General worker that inherits the parent’s permission policy.
code-review	Reviews recent changes on a branch / diff for correctness and style.
task	Runs a focused task with a tight scope and bounded turns.
plan	Pure-thinking planner used by plan mode.

All are invoked via the agent tool:

{
  "tool": "agent",
  "input": {
    "type": "explore",
    "prompt": "Find every place we serialize a User and report the JSON shape."
  }
}

Custom agents

Custom agent definitions are Markdown files with YAML frontmatter. The body of the file is the system prompt — the runtime always prepends its universal worker preamble, so this prompt holds only the agent-specific portion.

Scope	Path
Project	.lime/agents/<name>.md
User	~/.lime/agents/<name>.md (or $LIME_HOME/agents/<name>.md)

Built-in agents take precedence; project agents override user agents with the same type.

Example

---
name: refactor-rust
description: Specialised Rust refactor worker — runs cargo clippy and proposes minimal-diff fixes.
type: refactor-rust
model: inherit
max_turns: 30
color: cyan
tools:
  - read_file
  - grep_search
  - edit_file
  - "Bash(cargo:*)"
disallowed_tools:
  - delete_file
permission_mode: accept-edits
---

You are a focused Rust refactoring assistant. Run clippy first, propose
the minimum diff that resolves each warning, and never reformat code
that's outside the scope of the requested change.

Frontmatter fields

Field	Type	Notes
name	string	Display name. Defaults to the file stem.
description	string	Surfaced in the agent tool schema so the routing model can decide when to spawn it.
type	string	The agent_type / subagent_type value used to invoke it. Defaults to the slugified name.
tools	string[] or comma-string	Allow-list of tools (and tool patterns).
disallowed_tools	string[] or comma-string	Deny-list, evaluated after the allow-list.
model	string	Override the model for this agent. inherit (or omitted) means use the coordinator’s model.
max_turns	integer	Cap on agent loop iterations before forced stop.
color	string	Display color for TUI badges (green, cyan, purple, orange, red, gray, …).
background	bool	Always run in the background (async) instead of inline.
permission_mode	string	Permission-mode override (default, read-only, accept-edits, bypass-permissions, plan).
memory_scope	object	Persistent memory scope for this agent (advanced).
skills	string[] or comma-string	Names of skills bound to this agent — they appear in the agent’s tool surface automatically.

Manage agents

Snapshot from the CLI:

lime agents              # list configured agents

Inside the REPL:

/agents               # list, show, create, edit, delete

/agents create <name> writes a starter .lime/agents/<name>.md with the frontmatter scaffolded.

Lifecycle tools

Once a sub-agent is running, the agent_* family controls it:

Tool	Purpose
agent	Spawn a sub-agent.
agent_continue	Send a follow-up message to an existing sub-agent.
agent_status	Query a sub-agent’s execution status.
agent_stop	Cancel a running sub-agent.
send_message	Send a message to a specific sub-agent or broadcast to all.

CSV fan-out

spawn_agents_on_csv spawns one sub-agent per CSV row with per-row template substitution:

{
  "tool": "spawn_agents_on_csv",
  "input": {
    "csv_path": "./bugs.csv",
    "prompt_template": "Triage bug #{id} ({title}). Look for similar issues and propose a fix."
  }
}

Live view in the REPL

/tasks      Show live sub-agents spawned in this session.

The /tasks panel shows each sub-agent’s status, the latest streamed chunk, and whether it’s blocked on a permission prompt.