craig-cli 0.14.1 → 0.15.1

package/README.md

@@ -10,250 +10,73 @@
   ░          ░░   ░   ░   ▒    ▒ ░░ ░   ░
   ░ ░         ░           ░  ░ ░        ░
 
-         crAIg is that you?
-
 </pre>
 
-**An agnostic agent orchestrator. For the people.**
+**An agnostic orchestrator TUI, for the people.**
 
 [![npm](https://img.shields.io/npm/v/craig-cli)](https://www.npmjs.com/package/craig-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/hallsamuel90/craig/blob/main/LICENSE)
 [![Node 22+](https://img.shields.io/badge/node-22%2B-brightgreen)](https://nodejs.org)
 
-[craig-cli.com](https://craig-cli.com) · [Docs](https://craig-cli.com/docs/) · [Quickstart](https://craig-cli.com/docs/quickstart/)
+[Website](https://craig-cli.com) · [Documentation](https://craig-cli.com/docs/) · [CLI reference](https://craig-cli.com/docs/cli/)
 
 </div>
 
----
-
-Craig is a full-screen TUI that lets you run multiple AI agents across multiple repos at the same time — each in its own isolated git worktree, each with a live PTY, all from one terminal. Spin up Claude, Codex, and Cursor simultaneously. Watch them cook. Inspect diffs and review state while the agent handles repo actions from its PTY.
-
-it's like a game, except the PRs are real.
-
-## Install
-
-```bash
-npm install -g craig-cli
-```
+<a href="https://craig-cli.com">
+  <img src="https://craig-cli.com/craig-agent.gif" alt="Craig running parallel coding agents in its terminal UI">
+</a>
 
-Requires Node 22+, `git`, and `gh` (authenticated). Bring your own agent CLI — Claude Code, Codex, or Cursor.
+Craig gives every task its own Git branch, isolated worktree, and live PTY, then keeps the agents, changes, pull requests, and checks together in one keyboard-driven workspace.
 
-## Start
-
-```bash
-cd path/to/your/workspace
-craig
-```
+Bring the agent CLIs you already use—Claude Code, Codex, or Cursor. Craig is not another coding agent; it is the heads-up display and controls around them.
 
-The TUI opens with a boot overlay, then a three-panel workspace: task navigation on the left, live agent PTY in the center, file/diff/review inspector on the right.
-
-Craig writes all local state under `.craig/` — worktrees, logs, task records, PR metadata. Don't commit it.
-
-## Workflow
-
-1. Press `n` to create a task — type a short task description, pick a runner, press `Enter`.
-2. Craig creates the task record, branch, worktree, and agent tab automatically.
-3. Press `Enter` on the task to attach its live PTY. `Ctrl+]` to return to control mode.
-4. Give the runner its instructions in the agent PTY. The task description is Craig metadata; it is not pasted into the runner automatically.
-5. Use the **Files**, **Changes**, and read-only **Review** inspector panels to check the diff, PR state, checks, and comments.
-
-## Polyrepo support
-
-Point Craig at a directory containing multiple repos and it treats them as a single workspace. Create a task once — Craig provisions a worktree for each repo and runs the agent across all of them in one pass.
-
-```bash
-cd path/to/your/projects   # contains repo-a/, repo-b/, repo-c/
-craig
-```
-
-## TUI Keys
-
-```
-Global
-  ?             help
-  Esc           pause
-  Tab, ]        next panel
-  Shift+Tab, [  previous panel
-  Up/Down, j/k  move selection
-  PgUp/PgDn, Wheel  scroll focused inspection or terminal view
-  z             zoom center panel
-  n             new task
-  q             quit
+_It's like a game, except the PRs are real._
 
-Navigation
-  Left/Right, h/l  switch tabs or inspector mode
+## Why Craig?
 
-Tasks
-  Enter on + New Task       open task prompt
-  Enter on + New Workspace  open workspace browser
-  Enter on task             attach selected task PTY
-  r on + New Task           cycle runner for next task
-  X on task                 close selected task
-  X on workspace            remove selected workspace
+- **Run agents in parallel.** Each task works in an isolated Git worktree, so one agent does not overwrite another.
+- **Keep the native agent experience.** Every runner opens in a real PTY instead of a lowest-common-denominator chat wrapper.
+- **Stay in flow.** Launch agents, move between tasks, inspect changes, and watch PR checks without leaving the keyboard.
+- **Work across repositories.** Treat one repo or a directory of repos as a workspace while preserving real repository boundaries.
+- **Let agents operate the workspace.** The same task model backs the TUI and CLI, so agents and scripts can inspect context and perform Craig actions directly.
+- **Leave and come back.** A local daemon keeps agent sessions and PR synchronization alive when the foreground TUI closes.
 
-Center panel
-  Enter         attach PTY
-  +             create preferred tab kind
-  a             new agent tab
-  t             new terminal tab
-  r             cycle runner for next agent tab
-  x             close tab
-
-Review
-  Enter         refresh status or close task, depending on selected action
-  R             refresh read-only PR/check state
-  o             open tracked PR URL
-  X             close task record
-
-Task prompt
-  Ctrl+R        cycle runner
-  Enter         create task
-  Esc           cancel
-
-Workspace browser
-  Up/Down, j/k  move selection
-  Right, l      open directory
-  Left, h       parent directory
-  Enter         add selected path
-  Esc           cancel
-
-Terminal mode
-  Ctrl+]        return to control mode
-  Wheel, PgUp/PgDn  scroll terminal
-```
-
-## Command mode
+## Install
 
 ```bash
-craig repo add <path>
-craig repo list
-craig repo remove <repo-id>
-
-craig workspace add <path>
-craig workspace list
-craig workspace list --archived
-craig workspace archive <workspace-id>
-craig workspace restore <workspace-id>
-craig workspace remove <workspace-id>
-
-craig task new --repo <repo-id> [--runner codex|cursor|claude] "<task>"
-craig task new --workspace <workspace-id> [--runner codex|cursor|claude] "<task>"
-craig task list
-craig task list --repo <repo-id>
-craig task show <task-id>
-craig task open <task-id>
-craig task logs <task-id>
-craig task diff <task-id>
-craig task check <task-id>
-craig task commit <task-id>
-craig task create-child --parent <task-id> [--repo <repo-id> | --workspace <workspace-id>] [--runner codex|cursor|claude] \
-  [--idempotency-key <key>] "<task>" --json
-craig task children [<task-id>] --json
-craig task cancel-tree [<task-id>] --json
-
-craig agent list [--task <task-id>] --json
-craig agent status [--task <task-id>] [--tab <tab-id>] --json
-craig agent send --task <task-id> [--tab <tab-id>] (--prompt <text> | --prompt-file <path> | --stdin) \
-  [--delivery when-ready|immediate] [--timeout <duration>] [--idempotency-key <key>] --json
-craig task wait [<task-id>] --state <states> [--tab <tab-id>] [--timeout <duration>] --json
-
-craig events list [--task <task-id>] [--type <glob>] [--after <cursor>] --json
-craig events watch [--task <task-id>] [--type <glob>] [--after <cursor>] [--format jsonl]
-
-craig fury validate <file> --json
-craig fury plan <file> [--root-task <task-id>] [--input key=value] --json
-craig fury approve <plan-id> --json
-craig fury run <plan-id> --json
-craig fury status <run-id> --json
-craig fury watch <run-id> [--after <cursor>] [--format jsonl]
-craig fury cancel <run-id> --json
-craig fury resume <run-id> --json
-craig fury step complete --run <run-id> --step <step-id> [--output <json> | --output-file <path> | --stdin] --json
-craig fury step fail --run <run-id> --step <step-id> --reason <text> --json
-craig fury reviews list [--run <run-id>] [--state <state>] --json
-craig fury review show|approve|reject|request-changes|resubmit <review-id> --json
-
-craig command show <command-id> --json
-craig command list [--task <task-id>] --json
-craig command cancel <command-id> --json
-craig command wait <command-id> [--state <states>] [--timeout <duration>] --json
-
-craig link add <task-id> <repo-id>
-craig link list <task-id>
-```
-
-## Config
-
-Optional workspace-local config at `.craig/config.json`:
-
-```json
-{
-  "runners": {
-    "codex": { "enabled": true },
-    "cursor": { "enabled": true },
-    "claude": { "enabled": false }
-  },
-  "checks": {
-    "commands": ["pnpm test", "pnpm typecheck", "pnpm lint"]
-  },
-  "github": {
-    "mergeMethod": "squash",
-    "watchIntervalSeconds": 5
-  },
-  "previews": {
-    "agentActivityIndicators": false,
-    "agentOrchestration": false
-  }
-}
+npm install -g craig-cli
 ```
 
-Feature previews are experimental, workspace-local, and off by default. They can also be toggled from Options > Feature Previews in the TUI.
+Craig requires Node.js 22+ and `git`. Install and authenticate at least one supported runner: Claude Code, Codex, or Cursor. Pull request discovery and review status also require an authenticated `gh` CLI.
 
-### Cursor workspace trust
+## Quick start
 
-Cursor may ask separately whether to trust each Craig-managed worktree or project task bundle. To establish trust once at their common parent, open `~/.craig` in Cursor and approve its workspace trust prompt. Trust only that directory if you are comfortable allowing Cursor agents to work throughout Craig's local task state. Craig does not pass Cursor's `--trust` flag or otherwise weaken the runner's safety settings. For narrower project-only testing, opening `~/.craig/task_bundles` limits the trusted parent to project bundles but does not cover repo worktrees under `~/.craig/worktrees`.
+Run `craig` in a full-screen terminal, then work through the TUI:
 
-An interactive Craig launched from inside an agent session will not implicitly attach to that agent's live workspace. Pass `--workspace-root <live-root>` to confirm that attachment, or create and pass a different directory for an isolated blank workspace. A client also refuses to replace a live PTY daemon that uses an incompatible protocol; exit the other Craig instance before restarting explicitly.
+1. Select **+ New Workspace** and choose a Git repository. You can also choose a parent directory to work across its direct-child repositories.
+2. Press `n`, name the task, and use `Ctrl+R` to choose Claude Code, Codex, or Cursor. Press `Enter` to create it.
+3. Craig creates an isolated branch and worktree, starts the runner there, and takes you directly into its live PTY. Tell the agent what you want it to do.
+4. Press `Ctrl+]` to return to Craig's control mode. Move between panels with `Tab`, navigate with the arrow keys or `hjkl`, and press `Enter` on a task to reattach to its agent.
+5. Press `n` again to start more tasks while the first agent keeps working. Each task remains isolated in its own worktree.
+6. Use **Files** to inspect the worktree and **Review** to follow diffs, pull requests, checks, and review state. Ask the agent to commit, push, create the PR, or merge from its PTY; Craig keeps the status in sync.
 
-Event commands, new prompt dispatch creation, child-task creation, and fury validation/planning require the `agentOrchestration` preview. Preview-enabled agent PTYs receive an opaque workspace-local capability token scoped to their own task, the stable delegation command families, an expiry, and bounded child/depth/concurrency/prompt limits; only a non-authorizing reference is stored on the task. Fury operations reuse that scoped token according to each command's preview and recovery policy without persisting preview-only command families into the base capability record, so stable Craig can still read the workspace after preview use. `task create-child` inherits the parent target when neither `--repo` nor `--workspace` is supplied: project parents create project children, while repo parents create children in the same repo. An explicit repo child of a project task stays owned by that project workspace, so it does not require a separate standalone repo workspace. `task children` and idempotent `task cancel-tree` remain available when the preview is disabled so existing lineage can be inspected and safely stopped. Craig may still maintain durable semantic events internally for stable daemon services such as pull request synchronization. Disabling the preview stops new dispatch and child creation but leaves command inspection, waiting, cancellation, and safe reconciliation available for existing durable work. Prompt delivery defaults to `when-ready`; `immediate` explicitly interrupts a busy target. Craig sends a dispatched prompt and its submit key as separate terminal input events so the submit key cannot be consumed as part of the bracketed paste. A delegated child starts in a daemon-owned agent session immediately and selecting that child in the TUI attaches to the same process.
+See the [TUI reference](https://craig-cli.com/docs/tui/) for every panel and keyboard shortcut.
 
-Fury definitions are strict, versioned YAML DAGs stored under `.craig/fury/`. A `create_child` step can specify `repo`, specify `workspace`, or use an empty mapping (`create_child: {}`) to inherit its planning parent's target. `fury validate` checks the schema, limits, templates, references, dependencies, output schemas, and human-review checkpoints without mutating runtime state. `fury plan` resolves declared inputs, binds the graph to a planning task, persists an immutable content-hashed plan, and requests human sign-off.
+## Local by default
 
-Only a human can `fury approve` the exact plan hash. `fury run` accepts only an approved plan id, creates at most one run for that approval, and schedules every new task as a direct child of the planning task; graph dependencies never create visual grandchildren. Every agent step must explicitly call `fury step complete` or `fury step fail`; terminal silence is never success. Declared outputs are JSON-schema validated before dependents can run. Human-review steps remain blocked until an attributable human approval, while request-changes routes durable feedback to the declared task and requires an explicit resubmission. The sidebar shows one flat Fury attention row when plan or review approvals are waiting. The heartbeat reconciles interrupted dispatch, deadlines, missing agent sessions, and pending work. Retries, conditions, fan-out, and recursive Fury runs remain deferred.
+Craig stores workspace state, task records, worktrees, and runtime metadata under `.craig/` at the workspace root. Do not commit this directory; ignore `.craig/` when the workspace root is itself a Git repository. Craig does not require an account or hosted control plane. Your agent CLIs still use their own authentication and network services.
 
-```yaml
-version: 1
-name: inspect-and-review
-limits: { max_concurrency: 2, max_tasks: 4, timeout: 2h }
-inputs:
-  task_id: { type: string, required: true }
-steps:
-  inspect:
-    task: "${{ inputs.task_id }}"
-    prompt: Inspect the task and submit structured findings.
-    output:
-      schema: { type: object, required: [findings] }
-  review:
-    needs: [inspect]
-    human_review:
-      title: Review findings
-      summary: Review the submitted findings before execution continues.
-      feedback_target: { task: "${{ steps.inspect.task_id }}" }
-      timeout: 1h
-```
+## Go deeper
 
-The TUI sidebar groups descendants beneath their root task while enforcing a single visual child level. Grandchildren and deeper descendants use the same indentation as direct children, and every task row continues to show only that task's agent-tab activity roll-up.
-
-`github.watchIntervalSeconds` is the minimum GitHub polling interval. Craig polls selected PRs with pending checks
-most frequently, backs stable PRs and PR discovery off automatically, and pauses after rate-limit responses. The
-workspace daemon keeps PR discovery and check synchronization running while the TUI is detached or closed, and
-reacts to task and agent completion events for faster refreshes.
+- [TUI reference](https://craig-cli.com/docs/tui/) — layout, controls, and task navigation
+- [Runners](https://craig-cli.com/docs/runners/) — Claude Code, Codex, and Cursor setup
+- [CLI reference](https://craig-cli.com/docs/cli/) — commands for humans, scripts, and agents
+- [Configuration](https://craig-cli.com/docs/config/) — runners, checks, GitHub polling, and previews
+- [Agent orchestration](https://craig-cli.com/docs/orchestration/) — delegation, durable prompts, events, and Fury workflows
 
 ## Contributing
 
-Craig is open source under MIT, but not a community-maintained project. Bug reports and focused questions are welcome. PRs should be discussed with the maintainer first — unsolicited PRs may be closed without review.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+Craig is open source under the [MIT License](https://github.com/hallsamuel90/craig/blob/main/LICENSE), but it is not a community-maintained project. Bug reports and focused questions are welcome. Please read the [contribution guide](https://github.com/hallsamuel90/craig/blob/main/CONTRIBUTING.md) before proposing a change and report security issues through the [security policy](https://github.com/hallsamuel90/craig/blob/main/SECURITY.md).
 
 ## Development
 
@@ -268,4 +91,4 @@ pnpm package:audit
 pnpm package:smoke
 ```
 
-The npm package is published as `craig-cli` from `packages/cli`.
+The npm package is published as [`craig-cli`](https://www.npmjs.com/package/craig-cli) from `packages/cli`.