ccq
Leave a task in another project's inbox — its agent session picks it up.
English | 한국어
ccq is a tiny, fast message queue for handing work to AI coding-agent sessions
(Claude Code, Codex, …) — across projects, across agents, without interrupting anyone.
You drop a self-contained instruction into a project's queue; the session running there
(now, or whenever one opens) reviews it, runs it, and marks it done.
It's one self-contained macOS binary. No daemon, no server, no runtime dependencies — just
files on disk and the kernel's atomic rename.
Why ccq?
When you're deep in one project and realize another one needs a change, your options are
awkward. Resuming a second session over a live one (claude -p --resume) branches the
transcript and loses messages. Shared "channels" are often blocked by org policy. And you
usually don't want to barge into a session that's mid-thought.
There's also the tempting shortcut — just hand your current session the other project's path
and let it edit there. That implements the change, but the session is still rooted in your
project, so it runs without the target project's Claude Code setup: its hooks never fire,
and its CLAUDE.md, project skills, and permissions aren't loaded. Claude Code resolves those
from the session's working directory, not from whatever paths it happens to touch — so the work
lands outside that project's guardrails and automation. (Hooks especially: they only run for a
session actually executing in that project.)
ccq is the boring, reliable middle ground: a per-project inbox. Anyone — another session,
a script, CI, a different agent entirely — can enqueue work. The receiving session pulls it on
its own terms — in that project, with its hooks, skills, CLAUDE.md, and permissions all in
effect. Nothing interrupts anything; nothing gets lost to a crash or a race.
A quick look
# You're working in ~/code/web and the API needs a migration:
$ ccq send -d ~/code/api "Run the pending DB migration, then report the schema diff."
queued → /Users/you/code/api (1 pending)
# Meanwhile, the session living in ~/code/api:
$ ccq wait # blocks with zero CPU until a message arrives — then exits
$ /ccq:listen # review the queue, pick what to run, execute, mark done
That's the whole idea. A producer leaves a note; a consumer picks it up:
flowchart LR
P["Producer<br/>session · script · CI · agent"]
P -->|"ccq send"| NEW
subgraph Q["Per-project queue — maildir under $CCQ_HOME"]
direction LR
NEW["new<br/>pending"] -->|"claim / next"| CUR["cur<br/>processing"] -->|"done"| DONE["done<br/>archived"]
CUR -.->|"release / reap"| NEW
end
NEW -.->|"ccq wait → wakes (0 CPU)"| C["Consumer session<br/>/ccq:listen · or autonomous loop"]
A claim is atomic (exactly one consumer wins), and if a consumer dies its claim is
automatically returned to new — so nothing is double-run and nothing is lost.
When to use it
- Hand off across projects — "have the
api session run this" while you stay in web.
- Queue work for later — enqueue now; it's waiting when a session next opens that project.
- Cross-agent handoff — a Codex session can leave work for a Claude session in the same
project (the queue and CLI are completely agent-neutral).
- Autonomous loops — a background session blocks on
ccq wait, processes each arrival,
and goes back to sleep. No polling, no wasted tokens.
- Scripts & CI — drop follow-up tasks into a project's queue from any shell.
When not to: ccq is fire-and-forget local IPC, not a request/response RPC, not a
cross-machine broker, and not a high-throughput message bus. For those, reach for a real queue.
Features
- 📨 Per-project inbox keyed at the project root — a message sent to any subpath of a
repo lands in the same queue; monorepo sub-packages can be isolated on purpose.
- ⚡ Instant, zero-CPU
wait — event-driven via kqueue; the session wakes within
milliseconds of an arrival and burns nothing while idle.
- 🤝 Agent-agnostic — any agent or plain shell can send and consume; the store lives in a
neutral location, not under any one agent's home.
- 🔒 Safe by construction — atomic, no-clobber file moves mean exactly one consumer wins a
contended message; dead sessions' claims are automatically recovered.
- 🪶 Zero dependencies — a single ~1.3 MB universal macOS binary. No
jq, no daemon, no lock.
- 🌏 Bilingual output — English by default, Korean via
--lang ko; machine (--json) output
is identical in either.
Install
ccq ships as a Claude Code plugin, in two layers.
1. In a Claude Code session — zero install.
/plugin marketplace add rekyungmin/ccq
/plugin install ccq@ccq
