@pantheon.ai/agents CLI

pantheon-agents helps you:

• configure an agent for a Pantheon project
• queue tasks for that agent
• run the agent worker loop
• check task/config status

Required Configuration (Users and Developers)

.env is required for both users and developers.

Create/update .env:

# Use mysql://... for TiDB, or postgresql://... for db9.
DATABASE_URL=mysql://[email protected]:4000/pantheon_agents
PANTHEON_API_KEY=<your_pantheon_api_key>
DEFAULT_PANTHEON_PROJECT_ID=<optional_default_project_id>
DEFAULT_PANTHEON_ROOT_BRANCH_ID=<optional_default_root_branch_id>

Database Setup (One-Time)

If you already have a TiDB/MySQL database with the required tables, skip this section.

1) Start local TiDB (with tiup)

npm run dev:db:start
# same as: tiup playground --without-monitor --tag pantheon-agents

Keep this terminal running. Open another terminal for the next steps.

2) Execute the first SQL DDL

mysql --host 127.0.0.1 --port 4000 -u root -e "CREATE DATABASE IF NOT EXISTS pantheon_agents;"

3) Initialize tables

src/db/schema/tidb.sql already includes the DB creation statement as the first line.
To avoid running it twice, apply the rest of the file to pantheon_agents:

sed '1d' src/db/schema/tidb.sql | mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents

Versioned Migrations

When schema changes across versions, add versioned migration SQL files under:

• src/db/migrations/tidb
• src/db/migrations/db9

Example migration added in this version:

• src/db/migrations/tidb/20260304_0001_add_task_retry_columns.sql
• src/db/migrations/db9/20260304_0001_add_task_retry_columns.sql
• src/db/migrations/tidb/20260305_0002_add_agent_config_envs.sql
• src/db/migrations/db9/20260305_0002_add_agent_config_envs.sql

Apply manually:

# TiDB/MySQL
mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents < src/db/migrations/tidb/20260304_0001_add_task_retry_columns.sql
mysql --host 127.0.0.1 --port 4000 -u root pantheon_agents < src/db/migrations/tidb/20260305_0002_add_agent_config_envs.sql

# db9/PostgreSQL
psql "$DATABASE_URL" -f src/db/migrations/db9/20260304_0001_add_task_retry_columns.sql
psql "$DATABASE_URL" -f src/db/migrations/db9/20260305_0002_add_agent_config_envs.sql

Developer Local Setup

This section is only for developing this package locally. Run these steps inside packages/agents.

1) Install and build

npm install
npm run build

Quick Start

Use pantheon-agents .... If you omit --project-id, set DEFAULT_PANTHEON_PROJECT_ID in .env first.

npm install -g @pantheon.ai/agents@latest

pantheon-agents --help

1) Queue a config task

# first-time config for an agent/project requires --role
pantheon-agents config <agent-name> "<config prompt>" --project-id <project-id> --role <role>

# further config requests can omit --role, or pass --role to update it
pantheon-agents config <agent-name> "<config prompt>" --project-id <project-id>

Example:

# explicit project id
pantheon-agents config reviewer "Download some files" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617 --role developer

# update role on later config request
pantheon-agents config reviewer "Switch to review workflow" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617 --role reviewer

# set per-project branch envs (passed on every task start)
pantheon-agents config reviewer "Use Anthropic model" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617 --envs '{"ANTHROPIC_MODEL":"claude-opus-4-5"}'

2) Add a task

# explicit project id
pantheon-agents add-task <agent-name> "<task prompt>" --project-id <project-id>

# or use DEFAULT_PANTHEON_PROJECT_ID from .env
pantheon-agents add-task <agent-name> "<task prompt>"

Example:

# explicit project id
pantheon-agents add-task reviewer "Review the latest backend changes" --project-id 019c0495-f77a-7b6c-ade0-6b59c6654617

# or use DEFAULT_PANTHEON_PROJECT_ID from .env
pantheon-agents add-task reviewer "Review the latest backend changes"

3) Run the worker

pantheon-agents run <agent-name>

4) Check status

pantheon-agents show-tasks <agent-name>

# explicit project id
pantheon-agents show-config <agent-name> --project-id <project-id>

# or use DEFAULT_PANTHEON_PROJECT_ID from .env
pantheon-agents show-config <agent-name>

Common Commands

pantheon-agents show-tasks --all
pantheon-agents get-task <agent-name> <task-id>
pantheon-agents cancel-task <agent-name> <task-id> [reason] --yes
pantheon-agents retry-task <agent-name> <task-id> [reason] --yes
pantheon-agents kill <agent-name> <task-id> [reason] --yes
pantheon-agents skill.sh
pantheon-agents gen-migration-sql --provider tidb --from 0.3.0
pantheon-agents delete-task <agent-name> <task-id>

Task Dependencies & Retries

• A dependent task (with parent_task_id) only starts after its parent reaches completed.
• If the parent is failed/canceled, the child stays pending (so the parent can be retried).
• If the parent is permanently failing, manually retry-task / cancel-task the child / kill the subtree.

For full options of any command:

pantheon-agents <command> --help