npm package: @pantheon.ai/agents
Description: `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
Latest version: 0.3.5

# `@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`:

```bash
# Use mysql://... for TiDB, or postgresql://... for db9.
DATABASE_URL=mysql://root@127.0.0.1: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`)

```bash
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

```bash
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`:

```bash
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:

```bash
# 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

```bash
npm install
npm run build
```

## Quick Start

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

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

pantheon-agents --help
```

### 1) Queue a config task

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
pantheon-agents run <agent-name>
```

### 4) Check status

```bash
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

```bash
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:

```bash
pantheon-agents <command> --help
```