agent-core-cli

Headless CLI and HTTP server wrapping @accomplish_ai/agent-core. A drop-in replacement for the sandbox mock agent that runs AI tasks autonomously — no Electron, no GUI.

Architecture

Client  ──POST /jobs──>  Hono HTTP Server
                              |
                         JobRunner
                              |
                    TaskManager (agent-core)
                              |
                         OpenCode CLI
                              |
                    ┌─────────┴─────────┐
                    v                   v
              EventBus              StorageAPI
                |                       |
        ┌───────┼───────┐          SQLite DB
        v       v       v
       SSE     WS    stdout

Prerequisites

• Node.js >= 20
• ANTHROPIC_API_KEY environment variable

Installation

npm install -g @accomplish_ai/agent-core-cli

@accomplish_ai/agent-core is a peer dependency — npm 7+ installs it automatically. To pin a specific agent-core version (e.g. in a Dockerfile), install both:

npm install -g @accomplish_ai/agent-core-cli @accomplish_ai/[email protected]

From source

npm install
npm run build

Commands

run — One-shot execution

Run a single prompt and stream output to stdout, then exit.

agent-core-cli run --prompt "Write a hello world in Python" \
  --model anthropic/claude-sonnet-4-5 \
  --workdir ./my-project \
  --data-dir /app/data

| Option | Default | Description | |--------|---------|-------------| | --prompt (required) | — | Task prompt | | --model | anthropic/claude-sonnet-4-5 | Model ID | | --workdir | Current directory | Working directory for the agent | | --data-dir | /app/data | SQLite database directory |

serve — HTTP server

Start the HTTP API server with SSE and WebSocket support.

agent-core-cli serve --port 8080 \
  --model anthropic/claude-sonnet-4-5 \
  --workdir /workspace \
  --data-dir /app/data

| Option | Default | Description | |--------|---------|-------------| | --port | 8080 | HTTP port (1-65535) | | --model | anthropic/claude-sonnet-4-5 | Model ID | | --workdir | /workspace | Working directory for the agent | | --data-dir | /app/data | SQLite database directory |

interactive — REPL mode

Start a multi-turn conversation with session continuity.

agent-core-cli interactive \
  --model anthropic/claude-sonnet-4-5 \
  --workdir ./my-project

| Option | Default | Description | |--------|---------|-------------| | --model | anthropic/claude-sonnet-4-5 | Model ID | | --workdir | Current directory | Working directory for the agent | | --data-dir | /app/data | SQLite database directory |

HTTP API

GET /health

{ "status": "ok" }

POST /jobs

Create and start a new agent job. Returns immediately; the job runs in the background.

Request:

{ "id": "optional-custom-id", "prompt": "Build a REST API" }

Response (201):

{ "id": "job_1707400000_abc1234", "status": "pending" }

GET /jobs/:id

Poll job status.

{
  "id": "job_123",
  "prompt": "Build a REST API",
  "status": "running",
  "result": null,
  "created_at": "2026-02-08T12:00:00.000Z",
  "started_at": "2026-02-08T12:00:01.000Z",
  "completed_at": null
}

Status values: pending, running, completed, failed.

GET /jobs/:id/stream

Server-Sent Events stream. Sends an initial heartbeat, replays historical messages on connect, then streams live updates.

data: {"type":"connected","jobId":"job_123"}
data: {"type":"assistant","content":"I'll create the API..."}
data: {"type":"tool_use","content":"{\"tool\":\"bash\",\"input\":{...}}"}
data: {"type":"tool_result","content":"server.py created"}
data: {"type":"done","content":"Task completed"}

WS /jobs/:id/ws

WebSocket endpoint. Same message format as SSE. Replays history on connect, streams live updates, closes automatically when the job completes.

TaskManagerAPI Surface

The CLI wraps @accomplish_ai/agent-core's TaskManagerAPI. Currently only startTask and dispose are used by the HTTP server. The full API surface is documented below for consumers and contributors.

Task Lifecycle

| Method | Description | Used by CLI | |--------|-------------|:-----------:| | startTask(taskId, config, callbacks) | Start a task with prompt, config, and event callbacks | Yes | | interruptTask(taskId) | Soft stop — sends Ctrl+C to the agent process for graceful shutdown | No | | cancelTask(taskId) | Hard stop — kills the agent process immediately | No | | cancelQueuedTask(taskId) | Cancel a task waiting in the queue (before it starts running) | No | | cancelAllTasks() | Cancel all running and queued tasks | No | | sendResponse(taskId, response) | Send a response to a task waiting for input (e.g. permission prompt) | No | | dispose() | Dispose resources and clean up all processes | Yes |

Task State Queries

| Method | Description | Used by CLI | |--------|-------------|:-----------:| | isTaskRunning(taskId) | Check if a specific task is currently running | No | | hasActiveTask(taskId) | Check if a task is active (running or queued) | No | | hasRunningTask() | Check if any task is currently running | No | | isTaskQueued(taskId) | Check if a task is waiting in the queue | No | | getQueueLength() | Get number of queued tasks | No | | getActiveTaskIds() | Get IDs of all active tasks | No | | getActiveTaskId() | Get ID of the currently running task | No | | getActiveTaskCount() | Get count of active tasks (running + queued) | No | | getIsFirstTask() | Check if this is the first task in the session | No | | getSessionId(taskId) | Get the session ID for a task | No |

Task Callbacks

Callbacks passed to startTask() for receiving lifecycle events.

| Callback | Required | Description | Used by CLI | |----------|:--------:|-------------|:-----------:| | onMessage(message) | No | Raw message from the agent (streamed as-is) | Yes | | onBatchedMessages(messages) | No | Batched/processed messages (50ms batches) | No | | onProgress(progress) | Yes | Task progress updates | Yes | | onPermissionRequest(request) | Yes | Agent needs permission to proceed | Yes | | onComplete(result) | Yes | Task finished (success or failure) | Yes | | onError(error) | Yes | Unrecoverable error during execution | Yes | | onStatusChange(status) | No | Task status transitions | No | | onDebug(info) | No | Debug/diagnostic information | No | | onTodoUpdate(todos) | No | Agent's internal todo list changes | No | | onAuthError(error) | No | Authentication/API key errors | No |

Configuration

Factory options passed to createTaskManager().

| Option | Required | Description | |--------|:--------:|-------------| | adapterOptions | Yes | Platform, CLI command, environment builder, CLI args builder | | defaultWorkingDirectory | Yes | Default working directory for tasks | | maxConcurrentTasks | No | Max parallel tasks (CLI sets 1) | | isCliAvailable | Yes | Async check that the OpenCode CLI is installed | | onBeforeTaskStart | No | Hook called before each task starts |

Development

npm run dev      # Watch mode
npm run build    # Compile TypeScript
npm test         # Run tests

License

MIT