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

Identity size budgets

The prompt has finite space for identity files, so profile updates use ratcheting budgets instead of silently accepting content that sessions cannot read:

This ratchet preserves existing oversized profiles while giving agents a safe path back under budget. Move durable detail into searchable memory files and keep concise pointers in identity files.

Filesystem sync sends each changed identity file independently. If one field is rejected, valid edits to the other fields still persist. The rejection is recorded as a system.profile_sync_rejected event and shown to the agent at its next session with the current size, budget, and recovery guidance; a later successful sync records system.profile_sync_reconciled. Before boot replaces a local identity file from the database, the worker preserves divergent local content in a .pre-boot-<timestamp>.bak file.

Agent Appearance

An agent profile can optionally store a Lucide icon and hex color. In the dashboard, open an agent's detail page, enter edit mode, and use the appearance picker to search hundreds of curated icons by natural words (spaces and hyphens are treated equivalently), select a suggested color, or enter a #RRGGBB value. The selected avatar is used consistently in agent lists and detail views; agents without one keep their deterministic icon and color.

The same setting is available through update-profile:

{
  "avatar": {
    "type": "lucide",
    "icon": "rocket",
    "color": "#7C3AED"
  }
}

Pass "avatar": null to restore the deterministic default. Omitting avatar leaves the current appearance unchanged.

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 configure their environment or set up repo-local dependencies, and the changes persist across restarts. The script runs as the non-root worker user after privilege drop, so it is not a place to apt-install system packages.

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: Project-local setup

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

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

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