CIRCUIT
Autonomous WorkersSpawn autonomous agents that work through issue queues without human intervention
Best Way to Use CIRCUIT
The easiest way to use CIRCUIT is by asking Claude Code or another AI coding agent to run the TRIBE CLI commands for you. Simply describe your issues and let the agent manage the queue.
Example Prompt
"Use the tribe CLI to create issues for these bugs: [list bugs]. Then start CIRCUIT in auto mode to have agents work through them autonomously."Claude will run tribe circuit add, tribe circuit auto, and monitor progress automatically.
What is CIRCUIT?
CIRCUIT (Continuous Issue Resolution Circuit for Unified Intelligent Tasks) spawns autonomous agents that work through an issue queue. Agents pull issues by priority, work independently in isolated git worktrees, and complete without human intervention.
Core Commands
Agent Management
tribe circuit list # Show all agents
tribe circuit spawn <issue> # Spawn for specific issue
tribe circuit next [--force] # Spawn for next priority issue
tribe circuit <number> # Attach by index (shortcut)
tribe circuit status # Quick status summaryAutomation
tribe circuit auto [--interval N] # Auto-spawn until queue empty
tribe circuit watchdog [--once] # Stuck agent recoveryMonitoring
tribe circuit monitor # Enhanced monitoring
tribe circuit dashboard [interval] # Real-time dashboard
tribe circuit metrics # Performance metricsSession & Issue Operations
tribe circuit kill <agent> # Kill specific agent
tribe circuit attach <agent> # Attach to agent session
tribe circuit restart <agent> # Restart stuck agent
tribe circuit heartbeat # Emit heartbeat
tribe circuit issue <id> # View issue details
tribe circuit logs <agent> # View agent logs
tribe circuit sync # Sync issue state
tribe circuit clean --all # Clean everythingIssue Store Structure
CIRCUIT uses a file-based issue store for tracking work:
.issues/
├── issues/
│ ├── open/ # Pending issues
│ │ ├── 001-fix-login.md
│ │ └── 002-add-tests.md
│ ├── in-progress/ # Being worked
│ └── closed/ # Completed
├── agents/
│ ├── heartbeats/ # Health check files
│ │ ├── circuit-agent-001.json
│ │ └── circuit-agent-002.json
│ └── registry.json # Agent registry
└── metrics.json # Aggregated statsIssue Format
<!-- .issues/issues/open/001-fix-login.md -->
---
priority: 1 # 1=HIGH, 2=MEDIUM, 3=LOW
status: open
created: 2024-01-15
---
# Fix Login Authentication Bug
## Description
Users are getting logged out unexpectedly...
## Acceptance Criteria
- [ ] Session persists for 24 hours
- [ ] Token refresh works correctlyAgent Lifecycle
Issue Selection
Agent picks highest priority issue from .issues/issues/open/
Session & Worktree Creation
Creates tmux session circuit-agent-001-fix-login and worktree at .circuit-worktrees/001-fix-login/
Working with Heartbeat
Agent works autonomously, emitting heartbeats every 10 seconds for health monitoring
Completion
Upon CHANGES_COMPLETE, issue moves to closed/ and metrics update
Heartbeat System
Agents emit heartbeats to prove they're alive and making progress:
Heartbeat Format
// .issues/agents/heartbeats/circuit-agent-001.json
{
"timestamp": "2024-01-15T10:30:00Z",
"status": "working",
"issue": "001-fix-login",
"progress_lines": 142
}Health States
healthy
Heartbeat < 120 seconds ago
stale
Heartbeat 120-300 seconds ago
no_heartbeat
No heartbeat file found
dead
tmux session doesn't exist
Auto-Recovery
CIRCUIT automatically recovers stuck agents:
Configuration
# In circuit.yaml
circuit:
stale_threshold: 120 # Seconds without heartbeat
max_restarts: 3 # Auto-restart attempts
auto_restart: true # Enable auto-recoveryRecovery Flow
Real-Time Dashboard
Monitor all agents with the live dashboard:
$ tribe circuit dashboard 5
╔══════════════════════════════════════════════════════════════╗
║ CIRCUIT AGENT DASHBOARD ║
╚══════════════════════════════════════════════════════════════╝
Active Agents: 3/5
Queue Depth: 7 issues
┌─────────────────┬────────────┬───────────┬──────────┐
│ Agent │ Issue │ Status │ Runtime │
├─────────────────┼────────────┼───────────┼──────────┤
│ circuit-001 │ fix-login │ healthy │ 12m 34s │
│ circuit-002 │ add-tests │ healthy │ 8m 12s │
│ circuit-003 │ refactor │ stale │ 45m 22s │
└─────────────────┴────────────┴───────────┴──────────┘
Last check: 2024-01-15 10:30:00
Press Ctrl+C to exitConfiguration
Full Configuration Reference
# ~/.tribe/circuit.yaml or .tribe/circuit.yaml
circuit:
max_agents: 5
issue_store: ".issues"
log_dir: "logs"
stale_threshold: 120 # Seconds
check_interval: 10 # Seconds
session_prefix: "circuit-agent"
auto_restart: true
max_restarts: 3
heartbeat_dir: ".issues/agents/heartbeats"Quick Reference
Starting Work
tribe circuit next # Next issue
tribe circuit auto --interval 10 # Auto-spawnMonitoring
tribe circuit list
tribe circuit dashboard 5Recovery
tribe circuit watchdog --once
tribe circuit restart <agent>Cleanup
tribe circuit clean --all
tribe circuit clean --dry-runWorktree Isolation
Each CIRCUIT agent works in an isolated git worktree:
Repository Root/
├── .circuit-worktrees/
│ ├── 001-fix-login/ # circuit-agent-001
│ │ ├── .git -> ...
│ │ ├── CLAUDE.md
│ │ └── (full codebase)
│ └── 002-add-tests/ # circuit-agent-002
└── (main codebase)Orchestrator Integrations
CIRCUIT agents can be integrated with other orchestration systems for automated issue processing.
Issue Sync Patterns
Sync issues from external sources (GitHub, Jira, Linear) into the CIRCUIT issue store:
# Sync from GitHub Issues
gh issue list --json number,title,body,labels | \
jq -r '.[] | "---\npriority: \(if .labels | any(.name=="high-priority") then 1 else 2 end)\nstatus: open\n---\n# \(.title)\n\n\(.body)"' > .issues/issues/open/gh-\$number.md
# Run CIRCUIT auto mode
tribe circuit auto --interval 30Retrieving Results
Query completed CIRCUIT sessions for reporting and analysis:
# List CIRCUIT sessions via API
GET /api/tribes/sessions?subagent_type=circuit
# CLI query for recent completions
tribe sessions search --subagent-type circuit --since 24h
# Get specific session summary
tribe recall <session-id>Stop Hook Integration
Use stop hooks to trigger CIRCUIT spawning when issues are detected:
{
"hooks": {
"stop": [
{
"name": "circuit-on-error",
"trigger": "on_error",
"command": "tribe circuit spawn \"$ERROR_CONTEXT\""
},
{
"name": "circuit-queue-check",
"trigger": "on_idle",
"command": "tribe circuit next --force"
}
]
}
}