ccx-native 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,242 @@
-# Temporary Holding Version
+# ccx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Control and monitor native Claude Code and Codex sessions from the CLI, Python
+or RPC.**
+
+You, your agents and your scripts share the same persistent sessions. They run
+on your own Claude and ChatGPT subscriptions with your existing setup, and you
+can open any of them live with `ccx attach`.
+
+```bash
+npm install -g ccx-native
+ccx skills install
+```
+
+[▶ Examples](#examples) · [Docs](docs/getting-started.md) · Unofficial: read
+[Risks and system changes](#risks-and-system-changes).
+
+## Usage
+
+Most work needs five commands, the same for Claude Code and Codex:
+
+```bash
+ccx new --engine claude "Implement the plan in PLAN.md"   # prints claude:1a2b3c4d-...
+ccx wait 1a2b3c4d
+ccx report 1a2b3c4d
+ccx send 1a2b3c4d "Also update the changelog"
+ccx attach 1a2b3c4d
+```
+
+Use `--engine codex` for a Codex worker. Replace `1a2b3c4d` with a unique prefix
+of at least 8 characters from the id `ccx new` prints. `ccx help` lists the other
+commands.
+
+## Features
+
+- **Let Codex run Claude Code.** Codex starts Claude Code workers, is woken when
+  they finish, reviews their work and sends fixes back. Claude Code can drive
+  Codex workers the same way.
+- **Runs the official Claude Code and Codex.** ccx drives the unmodified
+  `claude` program through a terminal (PTY), as you would, and `codex` through
+  its app-server. Workers are signed in as you and run on your Claude or ChatGPT
+  subscription, with no API keys.
+- **Keep your setup.** Your config, `CLAUDE.md`/`AGENTS.md`, hooks, skills and
+  MCP servers all apply. Start a worker in any folder, which a subagent can't do.
+- **Join any session live.** `ccx attach` opens a worker in the engine's own
+  interface while agents keep driving it. `ccx import` brings in a session you
+  started yourself.
+- **Find and resume workers.** Workers keep their history across turns and
+  restarts, stop when idle and resume on the next message. `ccx list` finds
+  them; `ccx peek` shows what one is doing.
+- **Keep long work going.** Steer a running turn, compact a worker's context
+  between steps, and stop work at a usage cap.
+- **Build on it.** A [Python API](docs/python/README.md),
+  [controllers](docs/controllers.md) and a local [JSON protocol](docs/rpc/README.md)
+  put workers inside your own tools, dashboards and services.
+
+## Examples
+
+### Codex drives Claude Code and Codex workers
+
+https://github.com/user-attachments/assets/661f5247-7614-40e8-866b-b8e9742b158b
+
+I asked Codex for a Claude worker to implement a design, then for a Codex worker
+to check the proxy setup in parallel. Left: the Codex app. Right: its terminal,
+where I attach to the workers and open the dashboard.
+
+Watch for: 0:33 Claude finishes and Codex wakes up · 1:29 Codex tells Claude about
+the Codex worker · 1:45 Codex compacts Claude before the next step.
+
+### Native Claude Code and Codex, one Python API
+
+https://github.com/user-attachments/assets/849efe10-4f8c-457d-a08e-eea7bf17af17
+
+Right: a web chat built on the ccx Python API. Left: the same Claude Code session,
+open with `ccx attach`. Only the chat is used: Claude runs the slow tests in the
+background and has a Codex worker review its changes.
+
+## Controllers
+
+A controller is a Python script that runs a multi-step flow across workers. It
+can stop at a checkpoint for the owner's decision, then resume without redoing
+finished steps.
+
+```mermaid
+%%{init: {"sequence": {"mirrorActors": false}}}%%
+sequenceDiagram
+  participant O as Owner<br/>(you or your agent)
+  participant C as Controller
+  participant CL as Claude worker
+  participant CX as Codex worker
+  O->>C: ccx controller run deploy.py --notify-parent
+  rect rgba(201, 100, 66, 0.12)
+    C->>CL: design template.yaml
+    C->>CX: security review
+    CX-->>C: findings
+    C->>CL: fix the findings
+    C->>CL: write the runbook, create the change set
+  end
+  C-->>O: report: change set ready (wakes the owner)
+  Note over C: The controller stops here
+  O->>C: ccx controller resume deploy --note "Go"
+  Note over C: Finished steps are skipped
+  rect rgba(59, 111, 182, 0.12)
+    C->>CL: deploy the change set, with the owner's note
+    C->>CX: verify the live stack
+    C->>CL: write the ops notes
+  end
+  C-->>O: final report (wakes the owner)
+```
+
+```python
+from ccx import WorkerClient, controller, current, task
+
+workers = WorkerClient()
+
+@task
+def security_review():                    # a fresh Codex worker returns its findings
+    found = {"issues": None}
+    workers.create(engine="codex", model="gpt-6.1-sol", cwd=str(current.workspace),
+                   prompt=REVIEW_PROMPT, variables=found, wait=True)
+    return found["issues"]
+
+# design, fix, prepare, deploy, verify and handover are tasks like this one.
+
+@controller(name="deploy")
+def main():
+    design()                                      # Claude writes template.yaml
+    issues = security_review()
+    if issues:
+        fix(issues)                               # the same Claude worker fixes them
+    change_set = prepare()                        # Claude: runbook + change set
+    if not current.inputs:                        # checkpoint: stop until the owner resumes
+        return current.report(status="awaiting-approval", checkpoint="deploy",
+                              summary="Change set ready. Resume with a note to deploy.",
+                              data={"change_set": change_set})
+    deploy(change_set, current.inputs[0].comment) # Claude follows the runbook
+    verify()                                      # Codex smoke-tests the live stack
+    handover()                                    # Claude writes the ops notes
+    current.report(status="completed", summary="Deployed, verified and documented.")
+```
+
+[Controllers](docs/controllers.md) explains resume and has runnable examples.
+
+## ccx and the Agent SDK
+
+The Claude Agent SDK runs the Claude Code binary from Python or TypeScript.
+The program that starts an SDK session drives it while it is live; other
+processes have no built-in way to inspect or drive that live session. You can
+resume it later with `claude --resume <session-id>`.
+
+ccx provides a shared worker lifecycle for Claude Code and Codex:
+
+- **Shared, live workers.** A worker has a durable id independent of whoever
+  started it. Any agent, shell, Python process or dashboard can inspect,
+  message or steer it, or open it live with `ccx attach`.
+- **Every operation is a command.** Any agent that can run a shell command
+  can drive workers. Python and RPC interfaces are available too.
+- **Built-in lifecycle.** Send a new message or steer a running turn. Questions
+  and approvals go to whoever is driving. Idle workers stop and revive on the
+  next message. A Codex parent is notified when its Claude worker finishes.
+  The same lifecycle covers Claude Code and Codex.
+
+The SDK and ccx serve different layers and can complement each other in the
+same workflow.
+
+## Install
+
+You need:
+
+- Linux, macOS or WSL2, with Python 3.11 or newer
+- [Claude Code](https://docs.claude.com/en/docs/claude-code),
+  [Codex](https://github.com/openai/codex) or both, installed and signed in
+
+Install ccx with whichever tool you like:
+
+```bash
+npm install -g ccx-native     # needs Python 3.11+ on your PATH
+uv tool install ccx-native
+pipx install ccx-native
+```
+
+The package is `ccx-native`; the command is `ccx`.
+
+Optionally, teach your agents to use it:
+
+```bash
+ccx skills install
+```
+
+This adds the ccx skill to Claude Code and Codex (`~/.claude/skills`,
+`~/.agents/skills`) and keeps it current when you upgrade. Or use
+[skills.sh](https://skills.sh):
+
+```bash
+npx skills add ccx-native/ccx -g
+```
+
+Tested with Claude Code 2.1.316 and Codex 0.166 on WSL2, macOS 12 (Intel) and
+macOS 27 (Apple silicon). If `ccx` isn't found after installing, see
+[Installing](docs/troubleshooting.md#installing).
+
+## Risks and system changes
+
+> [!IMPORTANT]
+> - **Unofficial.** ccx is an independent project, not affiliated with or
+>   endorsed by Anthropic or OpenAI. Using Claude Code and Codex through it is
+>   still subject to their terms.
+> - **It can break on updates.** ccx drives Claude Code's interactive interface
+>   and hooks, and Codex's app-server protocol. Neither is a stable public API,
+>   so a new release of either can break ccx until it adapts.
+> - **It spends your quota.** Workers run unattended on your Claude and Codex
+>   plans. Usage caps (`--cap-5h`, `--cap-7d`) help, but they're not exact.
+> - **Workers have your full user privileges by default**: they can read, write
+>   and run anything you can, not only inside their folder. Use
+>   `--permissions restricted` for permission prompts and Codex sandboxing.
+> - **It changes a few things on your machine:** it marks worker folders as
+>   trusted in `~/.claude.json` (`ccx untrust` undoes it), leaves background
+>   processes running (`ccx shutdown` stops them), and adds `python`/`python3`
+>   shell functions inside worker shells for [variables](docs/variables/README.md).
+>   [What ccx changes on your machine](docs/machine-changes.md) has the full list.
+
+## Docs
+
+Start with [Getting started](docs/getting-started.md) and
+[Concepts](docs/concepts.md). The rest:
+[Permissions](docs/permissions.md) ·
+[Usage and caps](docs/usage.md) ·
+[Codex workers](docs/codex.md) ·
+[Controllers](docs/controllers.md) ·
+[Variables](docs/variables/README.md) ·
+[Troubleshooting](docs/troubleshooting.md) ·
+[What ccx changes on your machine](docs/machine-changes.md) ·
+[Python API](docs/python/README.md) ·
+[RPC](docs/rpc/README.md) ·
+[Architecture](docs/architecture.md).
+`ccx help COMMAND` has the details for each command.
+
+## Contributing, security, license
+
+Small fixes are welcome as pull requests; for new features, open an issue
+instead. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+Released under the [MIT License](LICENSE).

package/bin/ccx

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Plain old syntax on purpose: an outdated distro Node should still reach the
+// Python check below instead of failing to parse this file.
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const script = path.resolve(__dirname, "..", "ccx.py");
+// Homebrew's versioned formulas and uv-installed Pythons often only provide
+// a versioned name, so try those after python3.
+const candidates = process.env.PYTHON ? [process.env.PYTHON] : [
+  "python3", "python3.15", "python3.14", "python3.13", "python3.12", "python3.11", "python"
+];
+
+// ccx needs 3.11+; an older interpreter would fail with a SyntaxError or a
+// missing tomllib instead of saying so.
+const versionProbe = "import sys; print('%d.%d' % sys.version_info[:2]); sys.exit(sys.version_info < (3, 11))";
+
+let lastError = null;
+const tooOld = [];
+for (const python of candidates) {
+  const probe = spawnSync(python, ["-c", versionProbe], { encoding: "utf8" });
+  if (probe.error && probe.error.code === "ENOENT") {
+    lastError = probe.error;
+    continue;
+  }
+  if (!probe.error && probe.status !== 0) {
+    tooOld.push(`${python} is Python ${(probe.stdout || "").trim() || "unknown"}`);
+    continue;
+  }
+  const result = spawnSync(python, [script, ...process.argv.slice(2)], {
+    stdio: "inherit"
+  });
+
+  if (result.error) {
+    if (result.error.code === "ENOENT") {
+      lastError = result.error;
+      continue;
+    }
+    console.error(`ccx: failed to run ${python}: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+  process.exit(result.status === null ? 0 : result.status);
+}
+
+console.error(
+  "ccx: Python 3.11+ is required" + (tooOld.length ? ` (${tooOld.join("; ")})` : "") +
+  ". Set PYTHON=/path/to/python if needed."
+);
+if (lastError && process.env.CCX_DEBUG) {
+  console.error(lastError.message);
+}
+process.exit(127);

package/ccx/__init__.py

@@ -0,0 +1,163 @@
+"ccx package.\n\nPublic Python API:\n\n    from ccx import CcxClient\n    cx = CcxClient()\n\n    from ccx import CodexClient\n    codex = CodexClient()\n\n    from ccx import WorkerClient\n    workers = WorkerClient()      # one lifecycle for either engine\n\n    from ccx import controller, current, task\n    # durable task-specific Python orchestration, launched by `ccx controller`\n\nSee :mod:`ccx.client` and :mod:`ccx.codex.client` for the clients,\n:mod:`ccx.types` and :mod:`ccx.codex.types` for returned dataclasses, and\n:mod:`ccx.errors` for the shared typed exception hierarchy. Each client drives\nits engine's same on-disk sessions; durable controllers reference those real\nworkers without creating another worker type.\n"
+
+from __future__ import annotations
+
+from .client import CcxClient
+from ccx.codex.client import CodexClient
+from ccx.codex.types import (
+    CodexApprovalResult,
+    CodexCompactResult,
+    CodexContext,
+    CodexControlResult,
+    CodexReport,
+    CodexReconcileResult,
+    CodexResumeResult,
+    CodexSessionInfo,
+    CodexTelemetryPage,
+    CodexTurnResult,
+    CodexUsage,
+    CodexWaitResult,
+)
+from .errors import (
+    BudgetStopped,
+    CapabilityUnsupported,
+    CompactFailed,
+    CreatePartialFailure,
+    CompactIndeterminate,
+    CcxError,
+    CursorInvalidated,
+    DeliveryRejected,
+    InvalidRequest,
+    AmbiguousWorker,
+    OperationConflict,
+    OperationTimeout,
+    ProviderProtocolError,
+    PayloadTooLarge,
+    SessionNotFound,
+    SessionUnavailable,
+    SessionWaiting,
+    SpawnFailed,
+    SteerIndeterminate,
+    SendIndeterminate,
+    TurnIncomplete,
+    WorkerApiError,
+    WorkerApiPermanent,
+    WorkerApiTransient,
+    WorkerRateLimited,
+    ControllerError,
+    ControllerLaunchRequired,
+    ControllerOperationIndeterminate,
+    ControllerReplayMismatch,
+    ControllerLiveStateLost,
+)
+from .types import (
+    ClaudeContext,
+    ClaudeTask,
+    CompactOperationResult,
+    CompactResult,
+    Event,
+    PendingInput,
+    Question,
+    Report,
+    SemanticDeliveryResult,
+    SendResult,
+    SessionInfo,
+    SessionStatus,
+    SteerResult,
+    Usage,
+    WaitResult,
+)
+from ccx.ops.steer_ops import SteerJournalBusy
+from .workers import WorkerClient, evaluate_quota
+from ccx.ops.creation import new_worker_id
+from ccx.store.discovery import resolve_worker
+from ccx.notify.client import ParentNotificationClient
+from ccx.controllers.controller import (
+    ControllerInput,
+    Task,
+    TaskFuture,
+    TaskOutput,
+    controller,
+    current,
+    task,
+    task_output,
+)
+
+__all__ = [
+    "CcxClient",
+    "CodexClient",
+    "WorkerClient",
+    "new_worker_id",
+    "resolve_worker",
+    "CreatePartialFailure",
+    "ParentNotificationClient",
+    "evaluate_quota",
+    "controller",
+    "task",
+    "current",
+    "task_output",
+    "Task",
+    "TaskFuture",
+    "TaskOutput",
+    "ControllerInput",
+    # errors
+    "CcxError",
+    "CursorInvalidated",
+    "InvalidRequest",
+    "AmbiguousWorker",
+    "OperationConflict",
+    "OperationTimeout",
+    "ProviderProtocolError",
+    "CapabilityUnsupported",
+    "CompactIndeterminate",
+    "SessionNotFound",
+    "PayloadTooLarge",
+    "SessionUnavailable",
+    "SpawnFailed",
+    "SessionWaiting",
+    "DeliveryRejected",
+    "SteerIndeterminate",
+    "SteerJournalBusy",
+    "SendIndeterminate",
+    "TurnIncomplete",
+    "CompactFailed",
+    "BudgetStopped",
+    "WorkerApiError",
+    "WorkerApiPermanent",
+    "WorkerApiTransient",
+    "WorkerRateLimited",
+    "ControllerError",
+    "ControllerLaunchRequired",
+    "ControllerOperationIndeterminate",
+    "ControllerReplayMismatch",
+    "ControllerLiveStateLost",
+    # types
+    "SessionInfo",
+    "ClaudeContext",
+    "ClaudeTask",
+    "SessionStatus",
+    "PendingInput",
+    "Question",
+    "Report",
+    "SemanticDeliveryResult",
+    "SendResult",
+    "SteerResult",
+    "CompactResult",
+    "CompactOperationResult",
+    "WaitResult",
+    "Event",
+    "Usage",
+    # Codex types
+    "CodexSessionInfo",
+    "CodexResumeResult",
+    "CodexTelemetryPage",
+    "CodexTurnResult",
+    "CodexReconcileResult",
+    "CodexControlResult",
+    "CodexWaitResult",
+    "CodexReport",
+    "CodexApprovalResult",
+    "CodexCompactResult",
+    "CodexContext",
+    "CodexUsage",
+]

package/ccx/__main__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+if __package__:
+    from ccx.cli.main import main
+else:
+    # Hosts and hooks may re-exec this file directly after the parent command
+    # was invoked as `python -m ccx`. In direct-script mode Python does not know
+    # the package parent, so add it before importing ccx.cli absolutely.
+    #
+    # Do not import pathlib here before fixing sys.path: when this file is
+    # executed directly, sys.path[0] is the package directory, so stdlib imports
+    # of `types` can accidentally resolve to ccx/types.py.
+    import sys
+
+    normalized = __file__.replace("\\", "/")
+    package_dir = normalized.rsplit("/", 1)[0]
+    root = normalized.rsplit("/", 2)[0]
+    # Direct script execution sets sys.path[0] to the package directory. That
+    # makes top-level stdlib imports like `types` resolve to ccx/types.py. Drop
+    # that entry and import ccx as a package from its parent instead.
+    sys.path = [p for p in sys.path if p.replace("\\", "/") != package_dir]
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    from ccx.cli.main import main
+
+
+if __name__ == "__main__":
+    main()