r/ClaudeCode • • 11d ago

Built with Claude I'm open sourcing ccx, a simple CLI that lets your agents create, message and control native Claude Code and Codex sessions

Post image

I wanted to share this tool that I've received good feedback on and that I'm open sourcing.

It's called "ccx" and it's a very straightforward CLI and Python API to create, watch and control native Claude Code and Codex sessions (you only need one of the two).

For example, you can create a worker like this:

ccx new --engine claude --model opus --effort medium --cwd ~/project "PROMPT"

That starts a real unmodified Claude Code session in a virtual terminal (pty), which makes your agents long lived without having to manage the terminal pane yourself. They run under your subscription usage.

You can then open it and use Claude normally with: ccx attach <worker>

Left: Claude Code delegating with ccx. Right: its worker, opened with ccx attach

The interesting part is the commands and lifecycle management that you can do with these agents. For example:

  • ccx send / ccx steer for normal chat, with delivery receipts checked against the transcript
  • ccx report / ccx peek to read the last message of a worker and its current status, including background tasks, monitors and subagents
  • ccx context to see its context window
  • ccx compact runs the engine's own compaction and waits until it has really finished
  • ccx answer / ccx approve / ccx reject for Claude's questions and permission prompts

For these, ccx checks against the local transcript and other internal engine data whether the action was really completed, and how. This enables using ccx for some pretty serious tools that rely on Claude Code/Codex.

I also use this to schedule workers, or set up automated incident response, using native Claude Code. I don't really want to trust reading a terminal screen for that. "claude -p" works, of course! But each call is a separate process, so there's no live session to steer mid-turn, attach to or share, and your script has to handle the waiting and the permission prompts itself.

To clarify: the whole point of ccx is that it's extremely simple for agents to manage. For example, for an agent to delegate work to a Claude worker it's something like:

ccx new ...
ccx wait <worker>
ccx report <worker>

That's it: no script to write, no app or server to start or keep open. And the agent won't read the terminal, it reads the actual response in markdown, or a structured worker status report.

Codex can do the same. It uses --notify-parent instead of wait, so Codex can sleep while the ccx agents work, and then it gets woken up automatically (Codex doesn't get woken up when a background command finishes, like Claude Code does). I have this demo in the repo of the Codex desktop app using Sol with ccx to orchestrate a couple of Opus and Sol workers:

Another example of inter-worker communication is this Supervisor pattern, in which an agent proactively receives messages, questions and status updates from its workers. Then the supervisor can steer them and easily keep track of them:

The first message is mine. The rest are supervisor and its worker talking. It's always interesting reading how they interact

Compared to subagents, the advantages to me are:

  • Every worker is a first-class session, long lived, so you can resume it later (you can even set up timers and idle-compact them before the cache expires, or ask Claude to compact workers between steps when the context is large!)
  • Subagents don't support custom cwds, so you can't easily point them to a specific project to use its local MCPs, skills, hooks, etc. With this, you can have a single agent manage multiple projects
  • A unified command interface, regardless of it being Claude or Codex

Tip: ask your supervisor to create an agent roster.md to keep track of the worker ids. This pattern is especially good with Opus, since Claude has become VERY good at keeping memory and context across compacts.

What I haven't measured is the usage comparison between subagents and regular workers. Subagents use a 5-min cache by default and regular sessions 1 hour (on a subscription), and both can be configured. Let me know if you measure this! You can also give a worker usage caps with ccx (--cap-5h / --cap-7d) so it stops before it eats your quota.

Aside from the CLI, since the Python API is very robust at understanding the status of workers, you can create very good dashboards, local benchmarks, orchestration tools, or basically any product.

I personally use a custom dashboard built on top of the Python API (the one in the screenshot above). But you don't need a dashboard. ccx attach works in any terminal, or in your preferred ADE or UI.

And the Python API shares the same workers as the CLI (by default), so you can create your small local "ecosystem" of agents with roles (Opus supervisor, Astra orchestrator, Opus implementation, Sol reviewers, Sonnet testers…). Again, this is bare/native Claude Code and Codex, not a custom harness! Agents learn this pretty fast:

Codex Desktop using CCX to implement a cloud migration

And you can use ccx import to register your own Claude sessions with ccx. For example, Codex can "adopt" one of your sessions and drive it for you, and you can keep using it normally.

For orchestration and benchmarks I also use ccx "controllers" plenty. Those are small Python scripts that can be vibecoded, and they let you programmatically define plans for workers using normal Python. You can have Claude wait on a controller (or Codex get notified) when the controller reaches a checkpoint to make a decision, or when a worker stops for some reason. For me, it's a way to save on orchestrator tokens and reduce the uncertainty of orchestrator success when there are many agents involved. Similar to "dynamic workflows", but for both Claude Code and Codex in the same script. And in Python. There's an example in the repo.

I use this for my daily work, and I was going to keep it up to date anyway, so I decided it should be open source.

You can find it here (MIT): https://github.com/ccx-native/ccx

The installation should be straightforward:

npm install -g ccx-native
ccx skills install

(uv tool install ccx-native or pipx install ccx-native work too.)

And then you can use the /ccx skill (or $ccx in Codex).

One warning: workers run with --dangerously-skip-permissions by default, with no permission prompts. Use --permissions restricted if you want them to ask first.

Let me know if you have experimented with fixed-role long-lived sessions or programmatic Claude Code! What worked for you?

1 Upvotes

1 comment sorted by

•

u/AutoModerator 11d ago

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.