AgentDev CLI

Distributed agent client for processing GitHub tickets autonomously. Agents poll a central server for work, claim tickets from a GitHub Projects board, execute them using Claude Code, and report results back.

Installation

cd packages/agentdev-client
npm install
npm link   # Makes `agentdev` available globally

Prerequisites: Node.js >= 18, Claude Code CLI (claude) installed and authenticated.

Quick Start

# 1. Register with the AgentDev platform
agentdev register -u https://agentdev.datatamer.ai

# 2. Start processing tickets (cron mode, 1-minute interval)
agentdev cron --interval 1

# 3. Or run as a continuous daemon
agentdev start

Architecture

┌─────────────────────────────────────────────────────────┐
│  AgentDev WebUI (agentdev-webui/)                       │
│  ├── GitHub Projects board integration                  │
│  ├── SSE real-time ticket/log streaming                 │
│  └── REST API for agent communication                   │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP (heartbeat, claim, logs, complete)
┌────────────────────▼────────────────────────────────────┐
│  AgentDev Client (packages/agentdev-client/)            │
│  ├── Polls server for tickets to claim                  │
│  ├── Spawns Claude Code with auto-ticket-workflow skill │
│  ├── Streams logs back to server in real-time           │
│  ├── Polls GitHub comments for live instruction updates │
│  └── Reports completion status                          │
└────────────────────┬────────────────────────────────────┘
                     │ spawns
┌────────────────────▼────────────────────────────────────┐
│  Claude Code CLI                                        │
│  ├── Reads ticket from GitHub                           │
│  ├── Creates OpenSpec, implements, tests, deploys       │
│  └── Moves ticket through board columns                 │
└─────────────────────────────────────────────────────────┘

Commands

agentdev register

Register this machine as an agent with the AgentDev platform.

agentdev register [-u, --url <url>] [-n, --name <name>]

| Option | Default | Description | |--------|---------|-------------| | -u, --url | https://agentdev.datatamer.ai | WebUI server URL | | -n, --name | system hostname | Agent display name |

Performs OAuth device flow authentication, saves agent token and GitHub project board configuration to ~/.config/agentdev/config.json.

agentdev start

Run as a continuous daemon that polls for work every 10 seconds.

agentdev start [-c, --concurrent <number>]

| Option | Default | Description | |--------|---------|-------------| | -c, --concurrent | 1 | Max concurrent tickets (currently sequential) |

On startup, scans the GitHub Projects board for leftover tickets (In Progress, test status) and resumes them before polling the server for new work.

agentdev cron

Run in batch mode — process all available tickets per cycle, then sleep.

agentdev cron [-i, --interval <minutes>] [-m, --max-tickets <number>]

| Option | Default | Description | |--------|---------|-------------| | -i, --interval | 5 | Minutes between polling cycles | | -m, --max-tickets | 10 | Max tickets to process per cycle |

Same leftover-ticket scan as start on startup. Preferred mode for running as a background process:

# Start as background process
nohup agentdev cron --interval 1 > /tmp/agentdev-cron.log 2>&1 &

# Monitor logs
tail -f /tmp/agentdev-cron.log

agentdev status

Show agent registration status and configuration.

agentdev status

agentdev config

Read or write configuration values.

agentdev config get              # Show all config
agentdev config get <key>        # Show specific key
agentdev config set <key> <value>

Config is stored at ~/.config/agentdev/config.json. Keys include:

| Key | Description | |-----|-------------| | api_url | AgentDev server URL | | agent_token | Auth token (set by register) | | agent_id | Agent identifier (set by register) | | agent_name | Display name | | github_org | GitHub organization (data-tamer) | | project_id | GitHub Projects v2 node ID | | project_number | GitHub Projects board number | | status_field_id | Projects status field ID | | status_options | Map of status column option IDs (TODO, IN_PROGRESS, TEST, DONE) |

agentdev ticket create

Create a GitHub issue and add it to the project board as Todo.

agentdev ticket create -R <repo> --title <title> [--body <body>] [--body-file <file>] [--no-claude] [--json]

| Option | Default | Description | |--------|---------|-------------| | -R, --repo | required | Repository name (under the configured org) | | --title | required | Issue title | | --body | "" | Issue body text | | --body-file | — | Read body from file | | --claude | true | Append @claude tag to body | | --no-claude | — | Do not append @claude tag | | --json | — | Output as JSON |

The @claude tag in the issue body is what triggers the agent to pick up the ticket.

agentdev gh

GitHub CLI compatible commands. Drop-in replacement for gh so agent skills can use agentdev gh without requiring a separate gh installation.

# Issues
agentdev gh issue view <number> -R <owner/repo> [--json <fields>]
agentdev gh issue create -R <owner/repo> --title <title> [--body <body>]
agentdev gh issue comment <number> -R <owner/repo> --body <body>
agentdev gh issue reopen <number> -R <owner/repo>

# Pull Requests
agentdev gh pr create -R <owner/repo> --title <title> --head <branch> --base <branch> [--body <body>]
agentdev gh pr view <number> -R <owner/repo> [--json <fields>]
agentdev gh pr merge <number> -R <owner/repo> [--squash | --merge | --rebase]

# Project Board
agentdev gh project item-edit --id <id> --project-id <pid> --field-id <fid> --single-select-option-id <oid>

# Workflow Runs
agentdev gh run view <ref> -R <owner/repo>    # View CI status for a commit/branch
agentdev gh run watch <ref> -R <owner/repo>   # Poll until CI completes

# API (raw)
agentdev gh api graphql -f query='...'
agentdev gh api rest <path> [-X <method>] [--input <file>]

All gh commands require GH_TOKEN environment variable (automatically set from server OAuth tokens when running via start/cron).

agentdev openspec

Wraps the @fission-ai/openspec CLI. Available subcommands:

agentdev openspec init [--tools <tools>] [--force]
agentdev openspec list [--specs] [--sort <order>] [--json]
agentdev openspec show [item] [--type <type>] [--json] [--deltas-only] [--requirements]
agentdev openspec validate [item] [--all] [--changes] [--specs] [--strict] [--json]
agentdev openspec status [--change <name>] [--json]
agentdev openspec instructions <artifact> [--change <name>] [--json]
agentdev openspec archive [change] [-y] [--skip-specs]
agentdev openspec run [args...]   # Catch-all for any openspec subcommand

Resolves the openspec binary from agentdev's own node_modules, falling back to a global install.

agentdev onboard

Interactive repo discovery and environment skill generation. Scans a workspace for git repos, detects languages/frameworks/databases, and generates Claude Code skill files.

agentdev onboard [-w, --workspace <path>] [--no-claude] [--force]

| Option | Default | Description | |--------|---------|-------------| | -w, --workspace | cwd | Workspace root to scan | | --no-claude | — | Use template generation instead of Claude | | --force | — | Overwrite existing skills |

Generates .claude/commands/env-<name>.md skill files and .claude/repo-spec.json per repo.

agentdev render

Render Remotion video compositions. Self-contained — uses Remotion from agentdev's own node_modules, no need for the target project to have Remotion installed.

agentdev render <name> [--output <path>]

| Argument | Composition ID | Output | |----------|---------------|--------| | chat | ChatWithData | public/videos/chat-with-data.mp4 | | topics | OrganizeTopics | public/videos/organize-topics.mp4 | | artifacts | ManageArtifacts | public/videos/manage-artifacts.mp4 | | all | all three above | sequentially |

| Option | Description | |--------|-------------| | --output <path> | Override output path (single composition only, not with all) |

Convention: Run from the project root that contains remotion/index.ts as the entry point and public/ for static assets. Outputs default to public/videos/.

cd /path/to/datatamer.ai/app
agentdev render chat                        # Render single composition
agentdev render all                         # Render all three
agentdev render chat --output /tmp/test.mp4 # Custom output path

Ticket Execution Flow

When a ticket is claimed (via start or cron), the executor:

1. Configures environment — sets GH_TOKEN, TICKET_NUMBER, REPO, AGENT_ID, COMMENT_SIGNAL_FILE
2. Loads the workflow skill — reads skills/auto-ticket-workflow.md and injects it into the Claude prompt
3. Spawns Claude Code — runs claude -p --dangerously-skip-permissions --output-format stream-json --verbose with the full prompt
4. Streams logs — tails the output file, parses stream-json, uploads log batches to the server every 2 seconds
5. Polls for stop signals — checks the server every 5 seconds for user-requested stops
6. Polls GitHub comments — every 10 seconds, writes new comments to a signal file so Claude can read mid-execution instruction updates
7. Reports completion — sends success/failure status to the server

Server API Endpoints

The agent client communicates with the AgentDev WebUI server:

| Method | Endpoint | Purpose | |--------|----------|---------| | POST | /api/agent/heartbeat | Send agent status (idle/busy) every 30s | | GET | /api/agent/oauth | Fetch GitHub OAuth tokens | | GET | /api/agent/work | Claim next available ticket | | POST | /api/agent/logs | Upload log batch | | POST | /api/agent/complete | Mark ticket as done | | POST | /api/agent/ensure-ticket | Upsert ticket in DB (for leftover resumption) | | GET | /api/agent/should-stop | Check if stop was requested |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CLAUDE_BIN | Path to Claude Code CLI binary | claude | | GH_TOKEN | GitHub token (auto-configured from server OAuth) | — |