Agents (Subagents)

CrabCode automatically spawns subagents to parallelize complex tasks. /agents manages configs, /tasks shows background tasks, and CRABCODE_MAX_CONCURRENT_AGENTS caps concurrency.

What it is

When CrabCode's main loop hits a task that needs a wide investigation before any edits—"survey the codebase first"—it spawns a subagent: an isolated agent with its own context and tool set that runs in parallel, then reports a brief back. Big tasks may fan out several subagents at once (search code, run tests, check docs).

Subagents are core to how CrabCode handles large work. You don't dispatch them by hand—the main model decides. But you do control: which subagent type to use (specialty), how to author your own (project / user), and the concurrency cap.

When you'll see them

• Main loop prints "Spawning subagent: …" or similar
• Multiple Agent tool blocks appear concurrently
• /agents lists available types
• /tasks lists running background tasks

Built-in subagent types

CrabCode ships 6 built-in types (src/tools/AgentTool/built-in/):

The main model picks based on each type's whenToUse description; omitting subagent_type defaults to general-purpose.

Custom subagents

You can author your own subagent types. Files live in two places:

Format (markdown with frontmatter):

---
name: db-migration-reviewer
description: Reviews DB migration scripts for safety issues
tools: [Read, Grep, Bash]
model: deepseek-v4-flash
---

You are a database migration safety reviewer.

When invoked, read the migration files passed in, check for:
- Missing rollback statements
- Locking risks on large tables
- Foreign-key constraint violations

Report findings concisely.

---
name: db-migration-reviewer
description: Reviews DB migration scripts for safety issues
tools: [Read, Grep, Bash]
model: deepseek-v4-flash
---

You are a database migration safety reviewer.

When invoked, read the migration files passed in, check for:
- Missing rollback statements
- Locking risks on large tables
- Foreign-key constraint violations

Report findings concisely.

Fields:

• name — subagent type identifier (required)
• description — when this subagent should be chosen (required, used by the main model to pick)
• tools — allowed tool list; omit or use ["*"] for full access
• model — pin a specific model; omit to inherit the default subagent model
• color — color tag in the TUI
• The body is the subagent's system prompt

Save the file and it's picked up on next CrabCode start. /agents will list it.

/agents command

/agents opens the subagent management menu:

• View all available subagents (built-in + user + project)
• See each subagent's description, tools, and source file
• Jump to edit

It does not dispatch a subagent — dispatch is the main model's job. The command is a config panel.

/tasks command

/tasks (alias /bashes) opens the background tasks dialog. "Background tasks" here means processes you started with the Bash tool in background mode (run_in_background: true) — local dev servers, tail -f, etc. They keep running and their output is buffered.

From the dialog you can:

• View the latest output of each background task
• Kill ones you no longer need
• Pipe a task's output back into the conversation

Note /tasks shows Bash background tasks, not subagents. Subagents have no separate list UI — their state appears as tool-call blocks in the message stream.

Concurrency cap

To prevent the main model from dispatching dozens of subagents at once and saturating the gateway, CrabCode applies a client-side concurrency budget to subagent dispatch (src/services/tools/StreamingToolExecutor.ts:24-34):

• Default cap: 3 in-flight at a time
• Over-budget dispatches queue, they don't fail
• Override via env: CRABCODE_MAX_CONCURRENT_AGENTS=5 raises the cap to 5

The cap only affects the Agent tool — other tools (Read / Bash / Grep) are not throttled. Raising it can speed up large tasks but risks hitting gateway rate limits; lowering it serializes work and produces cleaner error traces.

Hooks

Subagent lifecycle exposes 4 hook events (see hooks):

Use these for logging, audit, or injecting extra context before a subagent starts.

Troubleshooting

Related

• hooks
• memory
• thinking-mode