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 attach 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)
`heartbeat`	—	Periodic execution config (interval + prompt)

System prompts

Each agent loads its system prompt from ~/.crabtalk/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/agents/researcher.md

The default agent uses Crab.md from the memory directory as its identity.

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.

Auto-compaction

When a conversation exceeds the model's token threshold (default ~100k), the agent automatically compacts the history — summarizing earlier messages to stay within the context window. Summaries are saved to ~/.crabtalk/memory/sessions/.

What's next

Multi-Agent Setup — step-by-step delegation guide
Skills — how skills extend agent behavior
Memory — how agents remember across sessions