ccx-native 0.0.1 → 0.2.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.2.0",
+  "description": "Native Claude Code and Codex sessions shared by your agents, scripts and terminals. Works with your own Claude and ChatGPT 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.2.0"
+description = "Native Claude Code and Codex sessions shared by your agents, scripts and terminals. Works with your own Claude and ChatGPT 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,166 @@
+---
+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 history TARGET...`: earlier turns as text. Lines carry addresses
+  (`#184.0`); `--turns 184.0` prints one message whole, `--turns 180-186` the
+  exchange. Search the workers you name with `--grep RE`, `--cmd pytest` or
+  `--errors` (the newest 20 hits each); `--view map` gives a long history at a
+  glance.
+- After a compaction, read what you lost with `ccx history` on yourself
+  (`$CCX_SELF_WORKER_ID`), not the raw transcript. See
+  [references/history.md](references/history.md).
+- `ccx logs TARGET`: the whole conversation as JSON, for programs.
+- `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.
+- `ccx models` lists each engine's models and the efforts each supports. A
+  Claude alias such as `opus` can point to a newer model after a Claude Code
+  update; pass the full id from the Resolved column to stay on one model.

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/history.md

@@ -0,0 +1,50 @@
+# Reading worker history
+
+`ccx history` prints past conversations of the workers you name, as text, and
+searches them. It never sends anything and works on stopped and busy workers.
+
+## What a line means
+
+    #184.0 10-25 00:40 U: do we need to support apple silicon?
+        .7 A*: Yes for the CLI, no for the dashboard…
+        [12 tools · 4m10 · pytest×3, git×2]
+
+- `#184.0` is turn 184, message 0: the same numbers as `ccx logs`. Inside a
+  turn, `.7` is message 7 of that turn.
+- `U` user, `U+` a message sent while the turn ran, `N[kind]` a notification
+  or event (`bg`, `monitor`, `agent`, `cron`, `system`, `ccx`, …), `/` a slash
+  command, `!` an interrupt, `A` assistant text, `A*` the final answer, `A…`
+  the latest text of a turn still running, `T` a tool call (`✗` failed).
+- `══ #212.3 compaction` marks a compaction; `--turns 212.3` prints its summary
+  when one is stored (Codex encrypts its summaries).
+
+## Recipes
+
+| need | command |
+|---|---|
+| what a worker did lately | `ccx history W` |
+| a long history at a glance | `ccx history W --view map` |
+| where something was decided | `ccx history W --grep 'cache|eager' --role user,final` |
+| the exchange around a hit | `ccx history W --turns 1032-1034` |
+| one message in full | `ccx history W --turns 1033.12` |
+| every instruction the user gave | `ccx history W --role user --turns 1-` |
+| what woke a worker | `ccx history W --role notify` |
+| how a worker tested | `ccx history W --cmd pytest --role tool,output` |
+| what failed | `ccx history W --errors` |
+| your children's last turns | `ccx history A B C --turns -1` |
+| several workers in one period | `ccx history A B --since '11-07 21:00' --until '11-07 22:00'` |
+| after your own compaction | `ccx history $CCX_SELF_WORKER_ID --turns <latest compaction address> --max-chars 2000` |
+
+## Things worth knowing
+
+- A search shows the newest 20 hits per worker, oldest first; the count line
+  says how to see older ones. `-C 1` reads the matching turns instead of hit
+  lines.
+- `--cmd` matches the command each shell call ran, not words inside it:
+  `--cmd python` finds `cd x && timeout 30 .venv/bin/python -m pytest`, not a
+  message that mentions python. `--grep` searches text.
+- Tool output is searched only with `--role output`. A cut summary
+  (`--max-chars`) keeps its end, where current work and next steps are.
+- Turn times come from the session; times are local, and the header names the
+  zone.
+- Searching your own running turn finds your own `ccx history` call.