/agent-brain-list

List Agent Brain Instances

Purpose

Displays all running Agent Brain server instances across all projects. Shows each instance's project name, URL, process ID, mode, and health status by scanning the global registry.

Usage

/agent-brain:agent-brain-list [--all] [--json]

Execution

Run the following command to list all instances:

agent-brain list

Options

agent-brain list              # List running instances only
agent-brain list --all        # Include stale/unhealthy instances
agent-brain list -a           # Short form of --all
agent-brain list --json       # Output as JSON for scripting

Expected Output

         Agent Brain Instances
Project         URL                      PID   Mode     Status
my-project      http://127.0.0.1:8000    12345 project  running
api-docs        http://127.0.0.1:8001    12678 project  running

2 running, 0 stale/unhealthy

JSON Output

agent-brain list --json

{
  "instances": [
    {
      "project_root": "/home/user/my-project",
      "project_name": "my-project",
      "base_url": "http://127.0.0.1:8000",
      "pid": 12345,
      "mode": "project",
      "status": "running",
      "started_at": "2026-01-31T10:30:00Z"
    }
  ],
  "total": 1
}

Output

Format the result as a table with the following columns:

Column	Description
Project	Project directory name
URL	Server base URL (e.g., http://127.0.0.1:8000)
PID	Process ID of the server
Mode	Instance mode: project or shared
Status	Health status: running, unhealthy, stale

Status Indicators

• running: Server process is alive and health endpoint responds
• unhealthy: Server process is alive but health endpoint fails
• stale: Process is no longer alive (auto-cleaned from registry)

Registry Cleanup

Stale entries are automatically removed from the global registry when agent-brain list runs. By default, only running instances are shown. Use --all to include stale and unhealthy instances.

Error Handling

Error	Cause	Resolution
No running instances found	No servers have been started	Run agent-brain init and agent-brain start
Permission Error	Cannot read registry or signal processes	Check file permissions
Connection refused	Server crashed or was killed externally	Clean up with agent-brain stop

Cleanup Stale Instances

# For each stopped instance, clean up its state
cd /path/to/project
agent-brain stop

# Or check system processes directly
ps aux | grep agent-brain

Notes

• Instances are discovered from the global registry at ~/.local/state/agent-brain/registry.json
• Each instance is validated by checking process liveness and the /health/ endpoint
• Each project has its own isolated instance
• Ports are automatically assigned from the 8000-8100 range (configurable)
• Stale registry entries are automatically cleaned up during listing