ccx-native 0.0.1 → 0.1.0

package/ccx.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""ccx: run persistent Claude Code and Codex workers."""
+from __future__ import annotations
+
+from ccx.cli.main import main
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,10 +1,42 @@
 {
   "name": "ccx-native",
-  "version": "0.0.1",
-  "description": "Placeholder for CCX: persistent native Claude Code and Codex agents. First release coming soon.",
-  "author": "Fernando",
-  "license": "UNLICENSED",
-  "bin": { "ccx": "bin/ccx" },
-  "files": ["bin/ccx", "README.md"],
-  "homepage": "https://github.com/oneferdev/ccx"
+  "version": "0.1.0",
+  "description": "Control and monitor native Claude Code and Codex sessions from the CLI, Python or RPC, on your own subscriptions.",
+  "author": "Fernando <ccx@delega.ai>",
+  "license": "MIT",
+  "bin": {
+    "ccx": "bin/ccx"
+  },
+  "files": [
+    "bin/ccx",
+    "ccx.py",
+    "ccx/**/*.py",
+    "!ccx/codex/schema.py",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml"
+  ],
+  "scripts": {
+    "test": "python3 -m compileall -q ccx ccx.py"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agent",
+    "terminal",
+    "pty",
+    "automation"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ccx-native/ccx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ccx-native/ccx/issues"
+  },
+  "homepage": "https://github.com/ccx-native/ccx#readme"
 }

package/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ccx-native"
+version = "0.1.0"
+description = "Control and monitor native Claude Code and Codex sessions from the CLI, Python or RPC, on your own subscriptions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fernando", email = "ccx@delega.ai" }]
+dependencies = []
+keywords = ["claude-code", "codex", "agent", "cli", "terminal", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development",
+]
+
+[project.scripts]
+ccx = "ccx.cli.main:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-xdist>=3.6"]
+
+[project.urls]
+Homepage = "https://github.com/ccx-native/ccx"
+Repository = "https://github.com/ccx-native/ccx"
+Issues = "https://github.com/ccx-native/ccx/issues"
+
+[tool.hatch.build.targets.sdist]
+# Allowlist: hatchling's default sdist ships every file not ignored by VCS,
+# which would include internal memos, plans and evidence at the repo root.
+# Only the package, its tests, public docs and project metadata are published.
+only-include = [
+  "ccx",
+  "ccx.py",
+  "bin",
+  "docs",
+  "examples",
+  "scripts",
+  "skills",
+  "tests",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "CONTRIBUTING.md",
+  "SECURITY.md",
+  "package.json",
+  "pyproject.toml",
+]
+exclude = [
+  "/tests/evidence",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ccx"]
+# Maintainer tooling for scripts/check_codex_protocol.py and its contract
+# test; nothing at runtime imports it, so installs do not need it.
+exclude = ["/ccx/codex/schema.py"]
+
+[tool.hatch.build.targets.wheel.force-include]
+# The agent skills ship as package data; `ccx skills` prints where they are.
+"skills" = "ccx/_skills"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+# Start with what can only be a bug: syntax errors, invalid comparisons and
+# undefined names. Widen (e.g. F401 unused imports) once existing hits are fixed.
+select = ["E9", "F63", "F7", "F82"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/skills/ccx/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ccx
+description: Run persistent Claude Code and Codex workers with the ccx CLI. Start workers, send follow-ups, wait or get notified, read replies, and coordinate work with Python controllers.
+---
+
+# ccx workers
+
+If `ccx` is missing, install it with `uv tool install ccx-native` (or
+`pipx install ccx-native`). The engine you pick must be installed and signed in.
+
+Workers keep their own history and stay reachable after your conversation ends.
+Use `ccx help COMMAND` for flags.
+
+## The core loop
+
+For Claude Code or a person:
+
+```bash
+W=$(ccx new --engine codex --cwd ~/repo -n auth-tests "Fix the failing tests in tests/auth.")
+ccx wait "$W"                  # until it finishes or needs input
+ccx report "$W"                # its last reply
+ccx send "$W" "Now add a regression test."
+```
+
+- Keep the handle from `new`. Worker targets accept it, the full UUID or a
+  unique UUID prefix of at least 8 lowercase hex characters. Names are labels
+  for `ccx list`, never targets.
+- Give a self-contained task and the right `--cwd`. Project instructions,
+  skills, MCP servers and config come from that folder; your conversation
+  isn't inherited.
+- For long or literal prompts use `--file task.md`, or `--stdin <<'EOF'` with
+  the delimiter quoted so the shell leaves backticks and `$VARS` alone.
+- Model and effort default to the engine's settings. Claude accepts aliases
+  (`opus`, `sonnet`, `haiku`); Codex needs a full model id from its model list.
+
+## Waiting depends on who you are
+
+- **Claude Code or a person:** use `--wait` or `ccx wait`; `send` waits by
+  default. Claude can background a long wait and let its harness wake it.
+- **Codex parent:** add `--notify-parent` to `new`, `send` or `compact`, or arm a
+  running worker with `ccx notify TARGET`. Then carry on or end your turn: ccx
+  resumes you when it settles. Don't wait, sleep or poll. This works from a ccx
+  Codex worker, the Codex app, or a default `codex` terminal. A `codex` started
+  with `-c`, `--profile` or `--no-daemon`, and `codex exec`, can't be woken; ccx
+  refuses and says to wait instead. In the notification, trust the turn's
+  `status`; `workerState` is only a hint.
+  Run `ccx` with full access: it starts processes and writes outside the workspace.
+- `--no-wait` returns at once and wakes nobody.
+
+## Talking to a worker
+
+| The worker is | Do |
+|---|---|
+| idle or stopped | `send`; stopped workers revive with their history. |
+| busy | `steer TARGET "..."`, or let it settle before `send`. |
+| waiting for input | `peek`, then `approve`/`reject` a permission request; on Claude, `answer` a question or `respond` to an MCP form. `send` is refused. |
+| going the wrong way | `stop` cancels the turn, not background work it started. `kill` stops the runtime; `send` revives it with its history. |
+
+## Reading results
+
+- `ccx peek TARGET`: state, latest messages, tools and errors. Start here.
+  `ccx peek A B --status` checks several workers at once.
+- `ccx report TARGET`: the last reply.
+- `ccx logs TARGET`: conversation JSON when the report isn't enough.
+- `ccx list`: find workers by name, state or folder.
+
+## Permissions
+
+Workers default to full permissions: they can read, write and run anything your
+user can, without permission prompts. Put read-only or "no edits" boundaries in
+the task. Restrict permissions only if the user asks.
+
+## Reuse, compact or start fresh
+
+Treat a worker like a teammate with working memory: reuse it when that memory
+helps the next task, compact it when a smaller context will repay the cost of
+summarizing it, and start fresh when the next task doesn't benefit from it.
+
+`ccx peek TARGET --status --json` shows both what you need:
+`context.tokens_used` (what the worker carries now, not total usage) and
+`last_turn_age_s`.
+
+- **Reuse** for the same task when the history helps. Design and strategy
+  conversations deserve long contexts; don't cut them for size alone.
+- **Start fresh** for unrelated work or a different working set, even in the
+  same repository.
+- **Compact** with `ccx compact TARGET` at a clean boundary above about 150k
+  tokens when most context is implementation residue (tool output) and the
+  next task uses the same files or domain. Summarizing costs tokens; when in
+  doubt, continue. Engines also compact automatically.
+
+**Claude only:** treat the prompt cache as warm for one hour after the last
+turn. Changing model or effort (`ccx set TARGET --model M --effort E`)
+invalidates it. Above about 100k tokens with a warm cache, compact before
+switching. With a cold cache, switch directly or start fresh if the history
+is dispensable. These cache rules don't apply to Codex.
+
+## Variables: structured state between workers
+
+Workers can share JSON state without files or parsing prose. Attach it with
+`--var NAME=JSON` on `new`, `send` or `fork`; inside the worker, plain
+`python3` sees `NAME` as a variable it can read and change, and changes
+persist. Read it back with `ccx vars TARGET NAME --json`, and give another
+worker, on either engine, the same shared state with `--vars-from TARGET`.
+
+```bash
+A=$(ccx new --engine claude --cwd ~/repo --var 'plan={"steps": [], "done": false}' \
+      "Draft an implementation plan. With python3, append steps to plan['steps'], then set plan['done'] = True last.")
+ccx wait "$A"
+ccx vars "$A" plan --json
+```
+
+Read [references/variables.md](references/variables.md) when sharing state
+between workers or when `python3` doesn't see the variables.
+
+## Controllers: programmable workflows that run unattended
+
+A controller is a Python script that drives many workers on its own, so you
+don't have to start, wait on and collect each one by hand. It's ordinary
+Python: it can branch on results, loop or fan out as the work requires. Its
+steps are recorded, so a run can stop for a decision and resume later without
+redoing finished steps, and workers hand back structured results through
+shared variables instead of prose. A few lines from one:
+
+```python
+futures = [review.submit(area) for area in ("api", "storage")]  # workers in parallel
+findings = [f.result() for f in futures]                         # structured results
+if not current.inputs:                                           # stop for a decision
+    current.report(status="needs-review", checkpoint="findings", data=findings)
+    return
+```
+
+Start one with `ccx controller run SCRIPT` (a Codex parent adds
+`--notify-parent` before the script). Read
+[references/controllers.md](references/controllers.md) before writing one.
+
+## When something looks off
+
+A wait timeout doesn't mean the work failed. Check `peek` or `report`;
+for uncertain delivery, use `ccx reconcile TARGET --delivery-id ID`.
+A server or watcher left running doesn't mean the task is unfinished.
+
+Exit codes: 0 success · 1 bad input or usage · 2 not found · 3 unavailable ·
+4 waiting for input · 5 refused in this state · 6 incomplete (timeout, failed
+turn or uncertain delivery) · 7 usage cap · 8 Anthropic rate limit ·
+9 transient API error.
+
+More in [references/troubleshooting.md](references/troubleshooting.md).
+
+## Also useful
+
+- `ccx fork TARGET ["prompt"]` copies a settled conversation into a new worker.
+- `ccx attach TARGET` opens the worker in a terminal; Ctrl-Z detaches.
+- `--cap-5h PCT` or `--cap-7d PCT` on `new` or `send` stops that turn when
+  account usage reaches PCT%. `ccx usage` shows the current levels.

package/skills/ccx/references/controllers.md

@@ -0,0 +1,244 @@
+# ccx controllers
+
+A controller is a Python script that drives ccx workers. Its `@task` results
+are recorded, so a run can resume and skip finished steps.
+
+- [A complete controller](#a-complete-controller)
+- [Replay rules](#replay-rules)
+- [Structured results through variables](#structured-results-through-variables)
+- [Checkpoints and input](#checkpoints-and-input)
+- [Loops and failures](#loops-and-failures)
+- [Before you finish](#before-you-finish)
+- [Python API](#python-api)
+- [CLI](#cli)
+
+## A complete controller
+
+Review two areas in parallel, stop for a decision, then apply what the user
+approves in a worktree:
+
+```python
+from ccx import WorkerClient, controller, current, task
+
+workers = WorkerClient()
+
+@task
+def review(area):
+    shared = {"result": {"done": False, "findings": []}}
+    workers.create(
+        engine="codex", cwd=str(current.workspace), name=f"review-{area}",
+        prompt=f"Review {area} without editing. With python3, append findings "
+               "to result['findings'], then set result['done'] = True last.",
+        variables=shared, wait=True)
+    result = shared["result"]
+    if not result["done"]:
+        raise RuntimeError("Review result is incomplete")
+    return result
+
+@task(workspace="worktree", commit="Apply approved fixes")
+def implement(input_id, instruction, findings):
+    created = workers.create(
+        engine="codex", cwd=str(current.workspace), name=f"fix-{input_id[:8]}",
+        prompt=f"Apply only this: {instruction}\nFindings:\n{findings}",
+        wait=True)
+    return {"worker": created["worker"]}
+
+@controller(name="review-fix", workspace="/repo")
+def main():
+    areas = ("api", "storage")
+    futures = [review.submit(area) for area in areas]     # start all, fixed order
+    findings = {area: f.result() for area, f in zip(areas, futures)}
+
+    if not current.inputs:                                # first run: ask
+        current.report(status="needs-review", checkpoint="findings", data={
+            "findings": findings,
+            "resume": f"ccx controller resume {current.run_id} --note '...'"})
+        return
+    for item in current.inputs:                           # after resume: act
+        implement(item.id, item.comment, findings)
+    current.report(status="done", data=findings)
+
+if __name__ == "__main__":
+    main()
+```
+
+On `ccx controller resume RUN --note "Fix the SQL injection only"`, both
+`review` tasks return their recorded results at once, and the note arrives as
+`item.comment`.
+
+## Replay rules
+
+Code outside tasks runs again on every resume; a task that finished runs once.
+
+- Outside tasks, don't read the clock, random values, files, Git state or
+  workers. Do it in a task and use the returned value.
+- Outside tasks, branch only on task results, script arguments and
+  `current.inputs`.
+- Call tasks in the same order with the same arguments every time. A
+  different call raises `ControllerReplayMismatch`.
+- A task's result never changes. To act on new input, call a new task with
+  `item.id`; don't expect a recorded task to return something else.
+
+```python
+files = subprocess.check_output(["git", "ls-files", "src"], text=True).split()
+for f in files: review.submit(f)       # wrong: a different list on resume breaks replay
+
+@task
+def list_files():
+    return subprocess.check_output(["git", "ls-files", "src"], text=True).split()
+for f in list_files(): review.submit(f)   # right: the list is recorded once
+```
+
+Resume needs the script unchanged and the same script arguments. After editing
+the script, start a new run; it starts from the top. Workers keep running when
+a controller stops, and ordinary `ccx` commands work on them.
+
+## Structured results through variables
+
+Pass `variables=` instead of parsing worker prose. Inside the worker, plain
+`python3` or `python` reads and updates those names; `command python3` runs
+normal Python.
+
+- Read results from the dict you passed: a worker can rebind a top-level name.
+- Set a sentinel such as `done: False` and ask the worker to set it last, so an
+  untouched value can't pass as an empty result.
+- Live variables last for one attempt. Keep the worker call and the JSON you
+  return from it in the same task; otherwise a replay raises
+  `ControllerLiveStateLost`.
+- Return small JSON values (verdicts, paths, worker handles), not transcripts.
+
+## Checkpoints and input
+
+`current.report(...)` publishes status; it doesn't stop the run. To stop for a
+decision, report a stable `checkpoint` id with what's needed to decide
+(findings, options, the resume command), then return from the controller.
+Workers stay alive meanwhile, so resuming days later is fine.
+
+```bash
+ccx controller resume RUN --note "..."                      # resume with a note
+ccx controller resume RUN --worker codex:<uuid> --comment "..."
+ccx controller input RUN --note "..."                       # record without resuming
+```
+
+Input is recorded for the controller; it isn't sent to any worker. Loop over
+every `current.inputs` item in order and pass `item.id` to the task that
+handles it.
+
+## Loops and failures
+
+Bound every loop, and let code decide when it's done rather than a worker's
+claim:
+
+```python
+@task
+def fix_round(n, failing):
+    workers.send(fixer, f"Fix these failures:\n{failing}", wait=True)
+    run = subprocess.run(["pytest", "-q"], cwd=str(current.workspace),
+                         capture_output=True, text=True)
+    return {"passed": run.returncode == 0, "failing": run.stdout[-2000:]}
+
+result = {"passed": False, "failing": initial}
+for n in range(1, 4):
+    result = fix_round(n, result["failing"])
+    if result["passed"]:
+        break
+else:
+    current.report(status="stuck", checkpoint="tests-failing", data=result)
+    return
+```
+
+- A task that raised or was interrupted runs again from its start on resume;
+  finished tasks, including parallel siblings, stay recorded. A worktree task
+  reuses its worktree, so write prompts that check the current state first.
+- A worker call can raise `ControllerOperationIndeterminate` (acceptance
+  unknown), `SessionWaiting` (input needed) or `TurnIncomplete`. `create` wraps
+  first-turn failures in `CreatePartialFailure`; retain its worker and delivery
+  ids. Catch failures inside the task, inspect the worker and return a result
+  for a checkpoint before deciding whether to send again.
+- Don't wrap task calls in a broad `except Exception`: it would also swallow
+  replay errors.
+- Quota is a reading, not a reservation. Check it right before a wave with
+  `evaluate_quota(workers.usage("claude"), {"five_hour": 70})` and checkpoint
+  if `allowed` is false; `caps={"5h": 80}` on `create` or `send` stops a turn.
+
+## Before you finish
+
+- `python -m py_compile SCRIPT` passes.
+- Worker calls, and anything time-, file- or Git-dependent, happen inside tasks.
+- Every task returns small JSON; every loop has a bound and a checkpoint for
+  hitting it.
+- Irreversible actions (push, deploy, messages) follow a checkpoint, or the
+  task checks whether they already happened.
+
+## Python API
+
+Everything below is importable from `ccx`. Worker arguments are the handle a
+create returns (`claude:<uuid>` / `codex:<uuid>`) or the full UUID; prefixes
+and names are not accepted. Results are plain dicts.
+
+**Controller building blocks**
+
+| Name | Use |
+|---|---|
+| `@controller(name=None, workspace=None)` | The entry point. `workspace` is the base folder (default: where `ccx controller run` started). |
+| `@task(name=None, workspace="shared", commit=False)` | A recorded step. `workspace="worktree"` runs it in its own Git worktree; `commit="message"` commits its changes there. |
+| `task.submit(*args)` | Start a task in parallel; `.result()` waits for its value. |
+| `task_output(value=..., report=...)` | Return JSON `value` plus prose `report`; on replay the task returns the same `.value` and `.report`. |
+| `current.workspace` | The task's folder inside a task, else the controller's. |
+| `current.run_id`, `current.controller_name`, `current.run_dir` | Run identity and its storage folder. |
+| `current.inputs`, `current.latest_input` | Recorded input: `id`, `created_at`, `worker`, `worker_name`, `comment` (a `--note` has `worker=None`). |
+| `current.workers` | Workers this run created. |
+| `current.report(status, checkpoint=None, summary=None, report=None, data=None)` | Publish the run's status; `data` must be JSON. |
+| `evaluate_quota(usage, limits)` | Compare a `workers.usage(...)` reading with limits such as `{"five_hour": 70}`; returns `allowed` and details. |
+
+**`WorkerClient()` methods**
+
+| Method | Use |
+|---|---|
+| `create(engine, cwd, prompt=None, name=None, model=None, effort=None, permissions="full", wait=False, timeout=None, idle_timeout=None, caps=None, variables=None, variables_from=None, worker_id=None)` | New worker. Returns `worker`, `worker_id`, `engine`, `state`, and with `prompt` + `wait=True` `reply` (the reply text) and `report`. |
+| `send(worker, text, wait=True, timeout=None, caps=None, variables=None, variables_from=None, delivery_id=None)` | New turn on an idle or stopped worker. `reply` holds the reply text when there is one. |
+| `steer(worker, text, wait=True, timeout=120, delivery_id=None)` | Add to a busy worker's running turn. |
+| `wait(worker, timeout=None)` | Until idle, waiting for input or stopped. A timeout is `status="timeout"`, not an exception. |
+| `report(worker, max_chars=None, turn_ref=None)` | The latest finished reply: `text`, `truncated`, `turn_ref`. Raises `SessionUnavailable` when no turn has finished. |
+| `status(worker)`, `list(engine=None, cwd=None, state=None, parent=None, limit=None)` | Recorded state; nothing is sent. |
+| `context(worker)` | Carried context: `tokens_used`, `window_size`, `percent_used`. |
+| `stop(worker)`, `kill(worker)`, `resume(worker)` | Cancel the turn; stop the runtime; reload without a turn. |
+| `fork(worker, prompt=None, name=None, wait=False, ...)` | New worker from a copy of a settled worker's history. |
+| `compact(worker, wait=True)` | The engine's own compaction. |
+| `approve(worker, request_id=None)`, `reject(worker, request_id=None, reason=None)` | Resolve a permission request. |
+| `set_model(worker, model)`, `set_effort(worker, effort)`, `set_name(worker, name)` | Settings for future turns. |
+| `variables(worker, name=None)` | Read a worker's durable JSON variables. |
+| `usage(engine=None)` | Account quota for one or both engines. |
+| `conversation_page(worker, cursor=None)`, `events(worker, after=None)` | Bounded history and lifecycle events. |
+
+`caps` takes `{"5h": PCT, "7d": PCT}` (Claude also `"opus"`).
+
+**Exceptions** (all subclass `CcxError`): `ControllerReplayMismatch` (task calls
+changed on resume), `ControllerLiveStateLost` (live variables from a failed
+attempt), `ControllerOperationIndeterminate` (acceptance unknown),
+`SessionWaiting` (input needed), `TurnIncomplete` (the turn didn't finish),
+`CreatePartialFailure` (creation didn't finish; it carries the worker id),
+`ControllerLaunchRequired` (the script wasn't started by `ccx controller run`).
+
+Full reference: [Python API](https://github.com/ccx-native/ccx/blob/main/docs/python/README.md)
+and [controllers guide](https://github.com/ccx-native/ccx/blob/main/docs/controllers.md).
+
+## CLI
+
+Options go before the script; arguments after it go to the script.
+
+```bash
+ccx controller run [--notify-parent] [--name NAME] SCRIPT [ARGS...]
+ccx controller resume [--notify-parent] RUN [ARGS...]
+ccx controller status RUN                  # tasks, worktrees and workers
+ccx controller report RUN [--json]         # --json includes the reported data
+ccx controller logs RUN
+ccx controller stop RUN                    # workers keep running
+ccx controller list
+```
+
+A Codex parent adds `--notify-parent` and ends its turn (`ccx controller
+notify RUN` follows a run already going); Claude or a person waits by default.
+`RUN` is a controller name (its newest run) or a unique run-id prefix. Launch
+through `ccx controller run`, never directly with Python. ccx never merges,
+pushes or removes worktrees: review and integrate the results yourself.

package/skills/ccx/references/troubleshooting.md

@@ -0,0 +1,94 @@
+# ccx troubleshooting
+
+## Delivery and steering
+
+`send` and `steer` have delivery ids (`--json`, or supply `--delivery-id`).
+Retry the same message with the same id to avoid duplicate delivery.
+`ccx reconcile TARGET --delivery-id ID` checks without sending; Codex also
+accepts `--turn-id`.
+
+If a `new` reply was lost, `ccx list` may find the worker. For retryable
+creation, choose a UUIDv4 first and reuse it with `--worker-id`; bare `new`
+always creates another worker.
+
+A Claude `steer` watches for where the message landed:
+
+| Status | Meaning |
+|---|---|
+| `consumed-current-turn` | the running turn took it |
+| `started-next-turn` | it runs as the next turn |
+| `accepted-pending` | ccx holds it; placement is unproven. Wait or reconcile; don't resend. |
+| `unknown` | reconcile before retrying |
+
+Pending Claude steering blocks other sends and steers; the refusal names its
+delivery id. Codex steering accepts or rejects at once.
+
+## Stopped, failed and revived workers
+
+Idle workers stop after `--idle-timeout`. Stopped or failed workers revive on
+`send`, keeping their history. Interrupted turns aren't resumed or resent:
+check `report`, then send what remains.
+
+`ccx resume TARGET` reloads without starting a turn. `ccx shutdown` stops
+runtimes, preserving histories; `--engine` limits it to one engine.
+
+## Workers waiting on background work
+
+A Claude worker can finish a turn while a background task or monitor keeps
+running, then wake for another turn. `peek` and `report` show background tasks.
+
+To follow finite work the worker is waiting on (tests or a build):
+
+- Claude or a person: `ccx wait TARGET --next-turn`
+- Codex: `ccx notify TARGET --next-turn`
+
+A server or watcher left running doesn't mean the work is unfinished.
+
+## Input requests
+
+`ccx peek TARGET` shows pending input and its request id.
+
+- **Question (Claude):** `ccx answer TARGET "Option label"`; see help for
+  multiple questions or selections.
+- **Permission:** `ccx approve TARGET` or `ccx reject TARGET`.
+- **MCP server form (Claude):** `ccx respond TARGET --accept --field
+  name=value`, `--decline` or `--cancel`.
+
+To follow the resumed turn, Claude/human parents add `--wait` where supported;
+Codex parents use `--notify-parent`.
+
+## Context and compaction
+
+Right after compaction, `ccx context TARGET --json` may show `tokens_used: null`
+until the next reading; `reason` explains why.
+
+Claude compaction revives stopped workers; Codex compaction needs an idle
+worker. `ccx notify TARGET` follows a compaction already running.
+
+`ccx set TARGET --model M --effort E` needs an idle or stopped worker. Codex
+uses the settings next turn. For a running, idle Claude worker, add `--restart`
+to stop its runtime; the next send revives it with the new settings. A stopped
+Claude worker uses them on revival. Let compaction settle before `set`.
+
+## Usage caps
+
+Caps stop a turn at the given account usage percentage (exit 7). Check
+`ccx usage` first. Caps apply only to that message; later sends need their own.
+If usage can't be read, the turn keeps running.
+
+## Deeper inspection
+
+- `ccx peek TARGET --full`: untruncated messages and tool errors.
+- `ccx logs TARGET --full`: conversation JSON without tool-result truncation,
+  including stopped workers. Claude's `--jsonl` gives the raw transcript.
+- `ccx events TARGET --follow`: lifecycle events for diagnostics.
+- `ccx import ID`: bring an idle Claude session into ccx, or fork a Codex
+  thread whose latest turn completed.
+
+## Engine differences
+
+- `answer`, `respond`, `--cap-opus`, `--next-turn` and `logs --jsonl` are
+  Claude-only. `--settle` (also wait for workers a Codex worker started) and
+  `reconcile --turn-id` are Codex-only.
+- Codex workers share one ccx-managed Codex daemon. `kill` unloads a single
+  worker and leaves the others running.