Docs

Delegate a task, follow the job, and decide what happens to the result. Detailed references live in the repository.

Your first job

A read-only job is the safest start. The brief comes from stdin.

echo "Inspect the repository and report findings" | pactify sub run --read-only --wait 0s

The command returns a job id at once and exits 3, which means the job is still running. Collect the result when it finishes:

pactify sub wait <job-id>pactify sub result <job-id>

For changes, run a write job in its own worktree:

pactify sub run codex --write --worktree --wait 0s < brief.md

A write job without --worktree edits your directory in place, and the CLI prints a note saying so. Exit codes: 0 succeeded, 1 the job failed, 2 invalid arguments, 3 still running.

From Claude Code

With the plugin installed, ask in plain words or use a slash command:

  • /delegate sends the task to the default harness, codex, or to an alias you configured.
  • /delegate-codex, /delegate-kimi, /delegate-opencode and /delegate-agy pick the harness.
  • /jobs lists recent jobs, /jobs all includes older ones and /jobs <id> shows one.

Claude writes the brief, starts the job, waits in the background and reviews the result with you before anything is applied.

Writing a brief

The other agent starts cold. It cannot see your conversation, so the brief carries everything: a title on the first line, the background, numbered goals, known constraints and special cases, general rules and the exact acceptance commands, including the full test suite.

Fix concurrent cache refresh ordering
Background:
src/cache/ expires entries on read; concurrent refreshes can serve stale data.
Goals:
1. Fix refresh ordering in src/cache/ without changing its public API.
2. Add regression coverage; first run each new test and see it fail.
Known constraints and special cases:
Zero TTL means no expiry; preserve it.
General constraints:
Write access only in src/cache/. Do not commit or inspect credentials.
Acceptance commands:
go build ./...
go test ./... -count=1

Delegation has a fixed cost of 20 to 50 thousand tokens on the other side, so it pays off for tasks that span several files, need exploration and test runs, or take more than about ten minutes.

Review and apply

A worktree job runs in a detached worktree based on your current commit. Uncommitted changes in your checkout are not carried over. The result shows the worktree path and base commit; review both tracked and new files:

git -C <worktree> diff <base-commit> --git -C <worktree> ls-files --others --exclude-standard

Rerun your acceptance checks inside the worktree. Then decide:

pactify sub apply <job-id>pactify sub discard <job-id>

Apply copies the changes into your checkout without committing. It checks every affected path first and stops, without applying anything, if your own edits conflict. Discard removes the worktree. A running job must be cancelled with pactify sub cancel <job-id> first.

Check the first lines of every result. pactify warns when the model that ran differs from the one you asked for, when a tool-call limit was hit, or when the final reply was empty.

Rework

To ask for changes, keep the worktree and resume the same session with a new brief:

pactify sub run --resume <job-id> --worktree < rework.md

Resume keeps the harness, the worktree and its base commit, so the summary shows the full change across all turns. A unique prefix of the job id works too.

Models and routing

Pass --model and --effort to choose a model; pactify never switches models silently. In ~/.pactify/router.json you can set defaults, aliases such as @cheap for documentation work, and fallback chains. With a chain configured, a quota failure starts the next harness as a new job, and sub wait follows the chain to the final result. Fallback stops if the failed job already left changes, so you can review them first. See the current configuration with pactify sub router --json.

Watching jobs

pactify sub status --allpactify sub logs <job-id> --tail 20pactify sub cost

pactify sub panel opens a read-only job panel on a random local port. pactify serve runs the dashboard at http://127.0.0.1:7777 with jobs, costs and settings.

Storage

Jobs, logs and caches live in ~/.pactify, or PACTIFY_HOME if you set it. Finished jobs expire after 14 days; pending worktrees are kept. Preview a cleanup with pactify sub prune and run it with pactify sub prune --yes.

Reference

  • Plugin guideDelegation workflow, access modes per harness, known limitations
  • RoutingDefaults, aliases, fallback chains and quota groups
  • Job statusStatus values and the JSON summary contract
  • Cost reportingHow tokens and cost are totalled
  • DoctorEvery check and what counts as evidence
  • OperationsStorage lifecycle, upgrade, uninstall, local server
  • Upstream compatibilityContract checks for new harness CLI versions