# Agents

How CrabTalk agents work — configuration, system prompts, delegation, and scoping.

An agent is a named configuration that binds a model to a system prompt, tools, and behavior settings. The daemon can run many agents simultaneously — each with its own model, personality, and capabilities.

## Default agent

The `[system.crab]` section configures the daemon's built-in agent:

```
[system.crab]
model = "deepseek-chat"
thinking = false
```

This is the agent you get when you run `crabtalk` without arguments.

## Custom agents

Define additional agents in `[agents.<name>]` sections:

```
[agents.researcher]
description = "Deep research specialist"
model = "claude-sonnet-4-20250514"
max_iterations = 32
thinking = true
members = ["writer"]
skills = ["web-research"]
mcps = ["search"]
```

| Field             | Default                 | Description                                           |
| ------------------| ----------------------- | ----------------------------------------------------- |
| `model`          | Active model            | Model name from a configured provider                  |
| `max_iterations` | 16                      | Maximum tool-use loop iterations                       |
| `thinking`       | false                   | Enable reasoning/thinking mode                        |
| `members`        | []                      | Agents this agent can delegate tasks to                |
| `skills`         | []                      | Allowed skills (empty = all)                          |
| `mcps`           | []                      | Allowed MCP servers (empty = all)                      |

## System prompts

Each agent loads its system prompt from `~/.crabtalk/local/agents/<name>.md`. Create the file to give an agent its personality and instructions:

```
echo "You are a research specialist. Be thorough and cite sources." 
  > ~/.crabtalk/local/agents/researcher.md
```

The default agent's identity is embedded in the binary. You can override it globally by creating `~/.crabtalk/Crab.md`, or per-project with a `Crab.md` in the project root.

## Delegation

When an agent has `members`, it can spawn tasks for those agents. The researcher above can delegate writing tasks to the writer agent. Tasks track state (queued, in progress, blocked, finished, failed) and respect concurrency limits.

## Scoping

Control what each agent can access:

- **`skills = ["name1", "name2"]`** — only these skills are available. Empty list means all skills.
- **`mcps = ["name1", "name2"]`** — only these MCP servers' tools are available. Empty list means all.

Scoping keeps agents focused and prevents them from using tools outside their responsibility.

## Session titles

After the first exchange in a conversation, the daemon auto-generates a short title (3-6 words) using the active model. Titles appear in the session browser (`/resume` in the REPL) and are included in the session filename.

## Auto-compaction

When a conversation exceeds the token threshold set by `compact_threshold`, the agent automatically compacts the history — summarizing earlier messages to stay within the context window. Configure it in `[system.crab]`:

```
[system.crab]
compact_threshold = 100000
```

On compaction, earlier messages are condensed into a dense prose summary. The summary preserves agent identity, user profile, key decisions, and active tasks. Session files on disk retain full history — compaction only affects the context window.

## What's next

- [Multi-Agent Setup](/content/blog/multi-agent-setup/index.html) — step-by-step delegation guide
- [Skills](/content/docs/crabtalk/skills/index.html) — how skills extend agent behavior
- [Memory](/content/docs/crabtalk/memory/index.html) — how agents remember across sessions

### Commands

CrabTalk commands — cargo-style subcommand dispatch for telegram, search, and custom tooling.

### Sessions

Persistent conversations — append-only JSONL, auto-compaction, crash-safe.