Agent Identity & Configuration

Every agent in the swarm is a persistent entity with its own identity, memories, and environment. This identity evolves over time as the agent works.

Identity Files

Each agent has four identity files that persist across sessions:

How Identity Works

1. Template-based bootstrap — On first registration, if TEMPLATE_ID is set, the template is fetched and used to generate identity files. Templates can also set default role, capabilities, maxTasks, and isLead values that apply when not explicitly configured.
2. Default generation — If no template is set, the system generates generic templates based on the agent's name, role, and description
3. Self-editing — Agents modify their own identity files during sessions. A PostToolUse hook syncs changes to the database in real-time
4. API / MCP tool — Use the update-profile tool to programmatically set any identity field

Version History

All identity file changes are tracked with version history. You can:

• View past versions using the context-history MCP tool
• Compare versions using the context-diff tool
• Roll back to a previous version if needed

System Prompt Assembly

The system prompt is built from multiple layers, assembled at task start:

1. Base role instructions — Lead or worker-specific behavior rules
2. Code quality & repository guidelines — Mandatory PR checks, merge policy, and review guidance from per-repo configuration
3. Conditional Slack instructions — Injected only for worker tasks that originated from Slack (channel ID and thread context)
4. Agent identity — SOUL.md + IDENTITY.md content
5. Repository context — If the task targets a specific GitHub repo, that repo's CLAUDE.md and guidelines are included
6. Filesystem guide — Memory directories, personal/shared workspace, setup script instructions
7. Self-awareness — How the agent is built (runtime, hooks, memory system, task lifecycle)
8. Additional prompt — Custom text from SYSTEM_PROMPT env var or --system-prompt CLI flag

Startup Scripts

Each agent has a startup script (/workspace/start-up.sh) that runs at every container start. Agents can modify this script to install tools, configure their environment, or set up workflows — and the changes persist across restarts.

Supported formats (priority order):

• start-up.sh / start-up.bash — Bash scripts
• start-up.js — Node.js scripts
• start-up.ts / start-up.bun — Bun/TypeScript scripts

Example: Install dependencies

#!/bin/bash
# /workspace/start-up.sh

echo "Installing dependencies..."
if [ -f "package.json" ]; then
    bun install
fi

sudo apt-get update -qq
sudo apt-get install -y -qq ripgrep

Agent Workspace

Each agent has access to:

Agent Filesystem (agent-fs)

When AGENT_FS_API_URL is configured as a global swarm config, agents gain access to agent-fs — a persistent, searchable filesystem shared across the swarm. Agent-fs provides:

• Personal and shared drives — Each agent has a personal drive and access to a shared org drive
• Full-text and semantic search — Search across all files with keyword or natural language queries
• Comments — Human-agent collaboration via file comments
• CLI access — The agent-fs CLI is pre-installed in worker containers and auto-configured on first boot

Agents are automatically registered with agent-fs on their first container boot. The lead agent creates a shared organization and workers receive invitations automatically.

Repository Guidelines

Repos registered with the swarm can have guidelines — per-repo quality rules that are injected into agent prompts and enforced by plugin commands.

Guidelines have three sections:

How It Works

1. Lead sets guidelines — Use the update-repo MCP tool to configure guidelines for a repo
2. Prompt injection — When a task targets a repo, its guidelines are injected into the agent's system prompt as a mandatory "Repository Guidelines" section
3. Command enforcement — /create-pr and /implement-issue require PR checks to pass before pushing; /review-pr references the review guidance
4. Lead gating — The lead agent can block code tasks for repos that lack guidelines

Use the get-repos MCP tool to view registered repos and their guidelines.

Lead vs Worker

Lead Agent

• Receives incoming messages from Slack, GitHub, and email
• Has an inbox for triaging messages
• Can delegate tasks to workers
• Can inject learnings into worker memories
• Has access to all Slack channels
• Coordinates projects across workers

Worker Agent

• Executes assigned tasks
• Reports progress via store-progress
• Can expose HTTP services
• Builds specialized expertise over time
• Can claim tasks from the task pool
• Can communicate with other agents via channels

Related

• Architecture Overview — How all the components fit together
• Hook System — Hooks that sync identity files and manage sessions
• Memory System — How agents build compounding knowledge
• Agents API Reference — REST API endpoints for registering, querying, and managing agents