Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

7.6 KB
Raw Blame
---
id: sub-agents
title: Sub-Agents (Multi-Agent Mode)
---

Mercury isn't just a chatbot — it's an **orchestrator**. It can spawn parallel AI agents to handle tasks concurrently while continuing the conversation. This is sub-agent mode, and it changes how Mercury works fundamentally.

## Why Sub-Agents Matter

Traditional AI agents are single-threaded: one context window, one task at a time. If you ask Mercury to "research this topic, write the code, and review the result," it does them sequentially — each step blocks the next.

Sub-agents break this bottleneck:

- **Parallel execution** — Multiple tasks run simultaneously across isolated context windows
- **LLM-driven delegation** — Mercury itself decides when to delegate based on task complexity
- **Non-blocking** — You can keep chatting with Mercury while sub-agents work in the background
- **File locks** — Reader-writer locks prevent concurrent write conflicts between agents
- **Resource-aware** — Max concurrent agents is auto-detected from your system's CPU and RAM

## How It Works

```
You: "Build a REST API for users and write integration tests"

Mercury decides to delegate:
  🤖 Multi-agent mode activated.
  **Agent a1** is now working on: "Build REST API endpoints for users"
  **Agent a2** is now working on: "Write integration tests for user endpoints"
  Active agents: 2/4

  You can continue chatting while the agents work.
  Use /agents to check status.

Mercury: I've delegated both tasks to parallel agents. Agent a1 is building the API
  and agent a2 is writing tests. They'll work independently.

  (you continue chatting normally)

  🔄 Agent a1: Using: read_file, create_file
  🔄 Agent a2: Using: list_dir, read_file

  ✅ **Agent a1** completed (12.3s): "REST API built with 5 endpoints"
  ✅ **Agent a2** completed (18.7s): "12 integration tests passing"

  Both agents are done. Want me to review the results together?
```

## Commands

| Command | Description |
|---------|-------------|
| `/agents` | List all sub-agents (running and completed) |
| `/agents stop <id\|all>` | Stop a sub-agent or all sub-agents |
| `/agents pause <id>` | Pause a running sub-agent |
| `/agents resume <id>` | Resume a paused sub-agent |
| `/agents config` | Show sub-agent resource allocation (max concurrent, mode) |
| `/agents set max <n>` | Set max concurrent sub-agents |
| `/code agent <task>` | Delegate a coding task to a sub-agent immediately |
| `/bg: <task>` | Run a natural-language sub-agent task in background |
| `/bg current` | Move current in-flight task to a background sub-agent |
| `/bg list` | List shell + sub-agent background tasks |
| `/halt` | Emergency: stop every chat's task and halt all sub-agents |
| `/stop` | Stop this chat's task and the sub-agents it started. When nothing else is running, also release file locks and clear the task board |
| `/reset` | Full reset: stop all + clear conversation context (requires confirmation) |

:::tip[`/halt` vs `/stop` vs `/reset`]

Chats run at the same time, so **`/stop`** stops only the chat you type it in: its task and the sub-agents it started. When nothing else is running, it also releases file locks and clears the task board. **`/halt`** stops every chat's task and all agents, but keeps file locks. **`/reset`** clears the conversation context as well (requires confirmation).

:::

Slash commands like `/agents`, `/halt`, `/stop`, `/spotify`, and `/code` work **even while the main agent is busy** — they're processed immediately on a fast path.

## Delegation Tools

Mercury uses these tools to manage sub-agents:

| Tool | Description |
|------|-------------|
| `delegate_task` | Spawn a sub-agent with a task description and optional context |
| `list_agents` | Show all running and completed sub-agents |
| `stop_agent` | Halt a specific running sub-agent by ID |

When Mercury decides a task is complex enough to benefit from parallel execution, it calls `delegate_task`. You'll see a response like:

```
🤖 Multi-agent mode activated.

**Agent a1** is now working on: "Analyze the codebase structure for..."
Active agents: 1/4

You can continue chatting while the agent works. I'll notify you when it's done.
Use /agents to check status.
```

## Architecture

```
User message → Main Agent (orchestrator)
                 ├─ delegate_task("research X")  → Sub-Agent a1 (isolated context)
                 ├─ delegate_task("implement Y")  → Sub-Agent a2 (isolated context)
                 └─ continues conversation       → responds to user
                         │
                    a1: "🔄 Using: read_file"
                    a1: "🔄 Using: edit_file"
                    a2: "🔄 Using: list_dir"
                    a1: "✅ completed (8.2s)"
                    a2: "🔄 Using: create_file"
                    a2: "✅ completed (15.1s)"
```

Each sub-agent:

- Has its **own context window** — the main agent's conversation doesn't pollute it
- Runs an independent **10-step agentic loop** with the same tool access
- Uses the **same permission system** — but with auto-approve for the task's scope
- Reports progress via the **notification channel** (CLI or Telegram)
- Respects **file locks** — if a1 is writing a file, a2 waits for the lock

## When Mercury Uses Sub-Agents

Mercury decides to delegate when:

- A task is **naturally parallelizable** (e.g., "research X while I code Y")
- The task benefits from an **isolated context window** (no pollution from the main conversation)
- A task is **complex enough** to warrant dedicated focus
- Multiple **independent investigations** would save time

You can also ask Mercury explicitly: "Use two agents for this" or "Delegate this task."

## What Happens While Agents Work

You can keep chatting normally. Mercury processes your messages as they come in. Sub-agent progress and completion appear as notification messages in your channel:

```
🔄 Agent a1: Starting task...
🔄 Agent a1: Using: read_file, edit_file
🔄 Agent a2: Using: fetch_url, create_file
✅ Agent a1 completed (8.2s): "Analyzed the codebase..."
🔄 Agent a2: Using: run_command
✅ Agent a2 completed (14.5s): "Tests passing..."
```

If you send `/agents`, you'll see the full status:

```
**Sub-Agents:**

🔄 a1: Build REST API endpoints — running (Using: read_file)
⏳ a2: Write integration tests — pending
```

Background-tracked agent tasks also appear in `/bg list` so shell jobs and delegated coding work share one progress surface.

## Configuration

Sub-agents are configured in `~/.mercury/mercury.yaml`:

```yaml
subagents:
  enabled: true
  maxConcurrent: auto    # auto-detected from CPU/RAM, or set manually (e.g., 4)
  mode: auto             # "auto" (LLM decides) or "manual" (user controls)
```

Environment variable overrides:

| Variable | Description |
|----------|------------|
| `SUBAGENTS_ENABLED` | Enable/disable sub-agents |
| `SUBAGENTS_MAX_CONCURRENT` | Max number of concurrent agents |
| `SUBAGENTS_MODE` | `auto` or `manual` |

## Programming Mode

Sub-agents pair well with Mercury's programming mode for code tasks:

| Command | Mode | Behavior |
|---------|------|----------|
| `/code plan` | Plan | Analyze without writing code |
| `/code execute` | Execute | Implement step by step |
| `/code off` | Off | Normal conversation |
| `/code toggle` | — | Cycle through modes |
| `/code status` | — | Show current mode |

## Programming Mode + Sub-Agents

When `/code plan` is active, Mercury will analyze a task and present a plan. If the plan involves parallel work, Mercury can delegate parts to sub-agents during `/code execute`. The `ask_user` tool lets Mercury present choices at decision points — on CLI this is an arrow-key menu, on Telegram it's inline buttons.