Skip to main content

​
Agents

An agent in Genie is a Claude Code (or Codex) instance running in a tmux pane with a defined identity and role. Agents are spawned, managed, and coordinated through the CLI.

​
Agent Identity

Every agent has three identity files that shape its behavior:

​
SOUL.md

The agent’s core identity — purpose, temperament, and principles. This is injected into the agent’s system prompt at startup. 
# Engineer Soul

You are an execution-focused engineer. You implement features
and fixes per the execution group assigned to you.

## Principles
- Read before writing — understand existing code first
- Ship the minimum — don't over-engineer
- Test what you build — if it's not tested, it's not done

​
HEARTBEAT.md

The checklist an agent runs on each /loop iteration. Defines what to check, what to do, and when to exit. 
# Engineer Heartbeat

1. Check task assignments
2. Read wish execution group
3. Implement deliverables
4. Run validation commands
5. Report completion to team-lead
6. If no assignments, exit

​
AGENTS.md

Agent configuration — spawn profiles, default models, and team assignments. Placed in the project root to configure project-specific agent behavior.

​
Built-in Roles

Genie ships with specialized agent roles:
RoleTypePurpose
team-leadLeaderOrchestrates wish execution, dispatches workers, manages PRs
pmLeaderProject management — backlog coordination, team oversight
engineerExecutorImplements features and fixes per execution group
fixExecutorRepairs FIX-FIRST gaps from review
refactorExecutorStructural code improvements
docsExecutorDocumentation generation and validation
reviewerValidatorQuality gates — returns SHIP or FIX-FIRST
qaValidatorAcceptance criteria verification on dev branch
traceInvestigatorRoot cause analysis for unknown failures
learnLearnerBehavioral correction from user feedback
councilDeliberatorMulti-perspective architectural review

​
Spawning Agents

genie spawn engineer                    # Basic spawn
genie spawn engineer --team my-team     # Spawn into a team
genie spawn reviewer --model opus       # Specify model
genie spawn engineer --skill work       # Pre-load a skill
Each spawn creates a tmux pane and registers the agent in the PostgreSQL agents table. See the Spawn & Lifecycle CLI reference for all spawn options and the agent management commands for listing and inspecting agents.

​
Agent Lifecycle

spawn → active → [suspended] → stopped/killed
                    ↑    ↓
                  resume  stop
StateMeaning
activeRunning in a tmux pane, processing tasks
suspendedPaused (idle timeout or manual stop), session preserved
stoppedGracefully stopped, session saved for resume
killedForce-terminated, session lost

​
Managing Agents

genie ls                    # List all agents with status
genie read engineer         # Read agent's terminal output
genie stop engineer         # Graceful stop (preserves session)
genie resume engineer       # Resume a stopped agent
genie kill engineer         # Force kill (no session save)
genie answer engineer yes   # Answer a pending question

​
Agent Communication

Agents communicate through two channels:

​
Direct Messages (Mailbox)

Point-to-point messages stored in .genie/mailbox/<worker>.json: 
genie send 'implement the auth module' --to engineer
genie inbox                 # Check your messages

​
Team Chat

Broadcast messages visible to all team members, stored in .genie/chat/<team>.jsonl: 
genie send 'group 1 is complete' --to team
genie chat                  # Read team chat history

​
Worker Registry

All spawned agents are tracked globally in the PostgreSQL agents table. This registry maps agent names to their tmux sessions, PIDs, teams, and status. The genie ls command reads from this table.

​
Council: Multi-Agent Deliberation

The council is a special agent mode that spawns 10 specialist perspectives for architectural review:
SpecialistFocus
QuestionerChallenge assumptions — “Why? Is there a simpler way?”
BenchmarkerPerformance evidence — “Show me the benchmarks.”
SimplifierComplexity reduction — “Delete code. Ship features.”
SentinelSecurity oversight — “Where are the secrets?”
ErgonomistDeveloper experience — “If you need docs, the API failed.”
ArchitectSystems thinking — “Talk is cheap. Show me the code.”
OperatorOperations reality — “No one wants to run your code.”
DeployerZero-config deployment — “Zero-config with infinite scale.”
MeasurerObservability — “Measure, don’t guess.”
TracerProduction debugging — “You will debug this in production.”
Use /council to invoke a multi-perspective review of any architectural decision.