Coding Tasks Lifecycle Guide

CodeJackRabbit supports autonomous, verifiable Coding Tasks executed inside isolated Git worktrees ("Boxes") or ephemeral sandboxes. Every task runs through a deterministic lifecycle with human-in-the-loop approval gates.

1. Task States & Lifecycle

Every coding task progresses through the following states:

  1. queued / planning: The task prompt, repository, base branch, and constraints are recorded.
  2. running: CodeJackRabbit provisions an isolated Git worktree (boxes/<taskId>), analyzes the target files, and prepares a structured implementation plan or code diff.
  3. waiting_for_approval: When requireApproval is enabled, execution pauses before committing or opening a pull request so an operator can inspect the diff.
  4. completed: Changes are verified against the review engine, committed to a task branch (codejackrabbit/task-<id>), and optionally pushed as a Pull Request.
  5. failed / canceled: Execution stopped due to a verification failure, timeout, or explicit operator cancellation.

2. Launching a Coding Task from the CLI

Create and Run a Local Task

cjr code "Refactor token cache expiration and add unit tests" --branch main

Interactive Approval & Inspection

List active tasks and inspect their prepared diffs:

cjr task list
cjr task show <task-id>
cjr task approve <task-id>

Prepared Local Commit Flow

When working locally, CodeJackRabbit can prepare changes and stage a verified commit:

cjr commit --prepare
cjr commit --confirm

3. Launching a Coding Task via HTTP / RPC API

Create a Task (POST /v1/tasks)

curl -X POST https://api.codejackrabbit.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "x-codejackrabbit-api-key: $CJR_API_KEY" \
  -d '{
    "prompt": "Fix null-dereference in webhook parser and add regression test",
    "repository": { "owner": "acme", "name": "payments" },
    "branch": "main",
    "requireApproval": true
  }'

Stream Live Task Events (WebSocket /ws)

Connect to /ws and subscribe to tasks.subscribe to receive real-time progress events (task.updated, task.log, task.approval_requested, task.completed).

Open a Pull Request from a Completed Task

Once approved, trigger tasks.createPullRequest via RPC or @codejackrabbit plan / @codejackrabbit resolve in a PR comment to push the branch and open a linked Pull Request.