Skip to main content
Glama
opencode-cc-tool

opencode-cc-tool

by jeremysball

CI License: MIT

taskferry

Background agent work with a changeset at the door.

Quick links: Quickstart · Why · Commands · CLI reference · Config · Troubleshooting

Quickstart

git clone https://github.com/jeremysball/taskferry.git
cd taskferry
node src/cli.js setup
export PATH="$HOME/.local/bin:$PATH"
taskferry --version

Re-run taskferry setup after updating the checkout (git pull && taskferry setup); it is idempotent and refuses to replace unmanaged paths.

taskferry dispatch \
  --prompt "Fix the failing tests" \
  --directory /workspace/my-repo \
  --model opencode-go/minimax-m3
taskferry wait <id>
taskferry result <id> --diff
taskferry accept <id>

The loop is dispatch, wait, result --diff, inspect, then accept or reject. Use taskferry output <id> for files the worker wrote to its durable per-task scratch directory rather than to the changeset.

On Linux the worker runs sandboxed in a copy-on-write overlay by default; macOS runs without the bubblewrap layer. The daemon owns task state and child processes after the calling terminal is gone, so no MCP server, tmux wrapper, or log-grepped marker is needed.

Worker CLIs ship no credentials: for pi run pi once and type /login (or set the provider API key), for --executor opencode run opencode auth login, for --executor kilo log in with the kilo CLI itself. The daemon accepts a task without usable credentials, then the worker fails at its provider; see why with taskferry status <id> --full.

Related MCP server: claude-code

Why taskferry

  • Dispatch is separate from acceptance. Worker writes land in an overlay; result --diff inspects, accept applies, reject discards.

  • The daemon owns the work. State and child handles outlive the client terminal.

  • Completion is a process event. Status follows the child's exit event, not a parsed log string.

  • Failure is queryable. Watchdogs, provider buckets, cancellation, output, and check-gate state surface via status and result fields.

  • The interface is a normal CLI. Scripts, CI, and any agent that can shell out use the same lifecycle.

Rationale, guarantees, and limits in full: docs/overview.md.

Commands

Command

Purpose

taskferry

Show live workspace tasks and next actions

taskferry dispatch

Queue a background model run

taskferry list

List workspace tasks with counts

taskferry status <id>

Task status and activity

taskferry wait <id>

Wait for settlement or a timeout

taskferry result <id>

Read the final model result

taskferry accept <id>

Apply a pending changeset

taskferry reject <id>

Discard a pending changeset

taskferry output <id>

Read durable per-task scratch output

taskferry tail <id>

Read recent model text

taskferry cancel <id>

Cancel queued or running work

taskferry watch

Stream workspace task events

taskferry context

Compact context for a session-start hook

taskferry doctor

Installation and daemon health

taskferry setup

Install CLI and native integration symlinks

taskferry init

Scaffold a project verification config

Full flags, defaults, and TOON examples for every command: docs/cli-reference.md.

How it works

A private daemon owns task processes and exposes versioned JSON-RPC over a user-scoped Unix-domain socket; the CLI validates input, auto-starts the daemon when needed, and prints TOON. For a git target, worker changes are held as a pending changeset against the pre-dispatch HEAD, with an optional .taskferry.toml check gate before accept. Native integrations exist for Claude Code, OpenCode, Kilo Code, and Codex; the CLI remains the dispatch surface. Full process model: docs/daemon.md.

Further reading

Available Tools

6 tools
opencode_cancelCancel a running opencode taskA

Stop a running task: sends SIGTERM to the task's whole process group (opencode and any subprocess it spawned), escalating to SIGKILL after a grace period if it hasn't exited. A finished task's status is unaffected and returns a note instead of an error. Poll opencode_status afterward; the task moves to status 'cancelled' once its exit event lands.

Inputs: task_id (required), grace_ms.

opencode_dispatchDispatch opencode taskA

Start an opencode run in the background as a directly-spawned child process (no tmux, no shared visibility into the orchestration layer) and return a task_id immediately. Poll with opencode_status, then read opencode_result once done.

Inputs: prompt (required), directory (required), model, variant, +1 more.

opencode_listList opencode tasksA

List all known tasks (this server process's lifetime) with their statuses, newest first.

Inputs: no named parameters.

opencode_resultFetch opencode task resultA

Return the final assistant message and metadata (tokens, cost, session id) for a finished task, parsed from opencode's own --format json event stream. message is only the model's last turn (after all tool calls finish); narration includes intermediate step narration too, in order. Errors politely if the task is still running.

Inputs: task_id (required).

opencode_statusCheck opencode task statusA

Return structured status for a dispatched task: running | done | crashed | cancelled | unknown, plus exit code and log path once finished. Backed by the child process's real exit event, not log string-matching.

Inputs: task_id (required).

opencode_waitBlock until an opencode task finishesA

Block on a running task's real exit event (or a timeout, whichever comes first) and return its status once settled. The closest analog to the built-in Agent tool's auto-resume behavior available over plain MCP request/response, without a poll loop. Capped internally at 45s so the call returns cleanly instead of hitting Claude Code's own MCP tool-call timeout; if status is still 'running' when it returns, call opencode_wait again.

Inputs: task_id (required), timeout_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a unique, well-defined purpose: dispatch starts tasks, cancel stops them, list enumerates tasks, status checks state, result retrieves output, and wait blocks for completion. No overlaps.

    Naming Consistency5/5

    All tools follow a consistent pattern: 'opencode_' prefix followed by a verb (cancel, dispatch, list, result, status, wait). No mixing of styles.

    Tool Count5/5

    Six tools cover the essential operations for managing opencode tasks without unnecessary bloat or gaps. The number is appropriate for the server's purpose.

    Completeness5/5

    The tool set provides complete lifecycle coverage for opencode tasks: create (dispatch), read (list, status, result), delete (cancel), and a blocking wait. No obvious missing operations.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers