# Cyclops
**One eye. Many agents. A single coordinated team.**
Cyclops coordinates coding agents that run in tmux. It gives them a durable
mailbox, a one-line doorbell into the recipient's pane, and an optional
workspace where a human can see and control the whole team.
The messaging protocol and the workspace are deliberately separate. Agents can
use Cyclops without opening the UI. If the UI closes, accepted messages remain
in the append-only journal.
Cyclops is at version `1.1.0`. It ships fifty-two detection manifests. Five
are measured against a live CLI: Claude Code, Codex CLI, Antigravity CLI,
Cursor Agent CLI, and Kimi Code CLI. The other forty-seven are written from
vendor documentation and say so with `version_tested = "unverified"`.
Thirty-eight products that never run in a pane, the IDEs and desktop apps in
the same catalog, get the Cyclops skill seeded and nothing else. See
[STATUS.md](STATUS.md) for the evidence behind each and the limits that
follow from it.
[usecyclops.dev](https://www.usecyclops.dev) · [quickstart](docs/guides/QUICKSTART.md) · [documentation](#documentation)
## Why Cyclops
Raw `tmux send-keys` is immediate, but it has no durable acceptance, sender
identity, ordering, claim, or receipt, and it types over whatever a human has
half-written in the composer. Cyclops adds the missing boundaries:
- A send is durably accepted, fsynced, before any terminal write begins.
- The sender is whoever connected to the socket. Nothing in a request can
name a sender.
- Message bodies stay in the authenticated mailbox. The pane gets one line:
a summary beside the exact claim command.
- Doorbells are FIFO per recipient and bound to a stable pane and process
identity.
- A doorbell is written and submitted for a bound, live agent process unless
a human draft is positively observed or a named block is on screen (a
modal, a permission prompt, a quota screen, a dead pane, copy-mode, or a
doorbell the recipient has not consumed). An ambiguous or unreadable
composer does not hold it.
- Every outcome is recorded, including the uncertain ones. A line that could
not be read back is `submitted_unverified`; a physical write failure is
`attention_required`. Nothing is retried on a timer.
The human-draft guard is strong, not absolute. It depends on the manifest
recognizing typed text, and an unverified manifest carries no such rule, so
a doorbell to one of those panes is effectively a raw write with a receipt.
### How fast
Measured on 2026-09-05 by `src/cyclopsd/tests/evidence/communication_benchmark.rs`,
50 operations per lane, median of three runs, on an Apple M5 Pro with tmux
3.6a. The rig owns an isolated Cyclops home, daemon, and tmux server.
| Lane | p50 | p95 | What it proves |
|---|---:|---:|---|
| Raw `tmux send-keys` | 2.61 ms | 3.03 ms | Nothing. No record, no sender, no ordering, no claim, no receipt |
| Raw `tmux capture-pane` | 2.50 ms | 2.60 ms | Nothing. One read of the screen |
| smux tmux-bridge cycle (modeled) | 7.65 ms | 8.26 ms | A read guard, a capture, a literal write, and Enter |
| `cyclops msg.send` | 3.06 ms | 4.04 ms | The message and one mailbox entry per recipient, appended and fsynced |
| `cyclops inbox.claim` | 15.12 ms | 17.44 ms | Sender identity, the body, and the claim on the record |
The rows are four different contracts, not a race. The tmux and smux lanes
each pay one or more process starts and prove nothing durable; the Cyclops
send lane starts no process and pays an fsync the others never pay.
**The smux row runs no smux code.** It reconstructs that project's
documented tmux-bridge cycle out of real tmux calls, so it is the price of
that shape on this machine, not a benchmark of the implementation.
Against 1.0.2 on the same machine, no median moved. The slow end of a claim
did: p95 went from 21.84 ms to 17.44 ms across non-overlapping samples. The
full before-and-after, every harness, and what each lane leaves out are in
[docs/reference/BENCHMARKS.md](docs/reference/BENCHMARKS.md).
## First five minutes
Cyclops needs tmux 3.2+, Git, and curl. The installer downloads a published
release pair for your platform when one exists and otherwise builds from
source, installing Rust with rustup when it is missing. It never uses
`sudo` and prints every file it changes.
```bash
curl -fsSL https://www.usecyclops.dev/install.sh | sh
exec "$SHELL" -l
cyclops
```
Or install from a clone:
```bash
git clone https://github.com/cyclops-team/cyclops.git
cd cyclops
./scripts/install.sh
```
The installer puts a matched `cyclops` and `cyclopsd` pair in place, writes
the initial config, and can wire supported vendor hooks and the Cyclops
skill without replacing unrelated settings. Use `CYCLOPS_NO_VENDOR_HOOKS=1`
to skip that wiring. See the [installation guide](docs/guides/install.md)
for paths, options, updates, rollback, and uninstall.
## Uninstall completely
The managed uninstall stops the matching daemon, removes the complete current
Cyclops state home, installed binary pair, Cyclops hook entries, unedited
seeded skills, and installer-owned PATH block:
```bash
curl -fsSL https://www.usecyclops.dev/install.sh | sh -s -- --uninstall
```
Export anything you want to retain before running it. `cyclops remove --all`
remains available when you want its explicit preview and confirmation without
removing the installed binary pair.
It removes only exact Cyclops hook commands from vendor configuration and
only byte-for-byte known Cyclops skill seeds. Unrelated hooks, settings, and
edited skills stay untouched. If a file cannot be safely proved, uninstall
stops before state or binaries are removed. The
[installation guide](docs/guides/install.md#uninstall) lists the full boundary.
## How to run Cyclops
For normal interactive use, run `cyclops`. It opens the full-screen workspace
and starts tmux and the daemon when needed.
| Command | What it opens | Use it when... |
|---|---|---|
| `cyclops` | The full Cyclops workspace with sidebar, tabs, panes, and Messages | You want the recommended everyday interface. |
| `cyclops start --preset duo`, then `cyclops` | The full workspace with a named two-pane layout | You want Cyclops to construct a preset before opening the UI. |
| `cyclops start --preset duo`, then `tmux attach -t main` | The same session in a native tmux client, without Cyclops workspace chrome | You want a headless script, a custom tmux setup, or a raw-tmux recovery path. |
| `cyclops watch` | The standalone Stream and Messages monitor | Your agents already run elsewhere and you only need coordination visibility. |
The daemon and mailbox do not depend on any interface remaining open. Closing
the workspace or watch UI does not discard accepted messages.
## Send, wake, and claim
```bash
cyclops name implementer --self
cyclops send reviewer --subject "Review the parser" \
--body "Please review commit abc123."
```
A send returns after durable acceptance. The doorbell follows asynchronously.
`--summary` is optional: when you omit it the daemon derives the one-line
preview from the subject. Use `--require-wake` only when the caller must wait
for the doorbell to reach `submitted` or `notified`:
```bash
cyclops send reviewer --subject "Review the parser" \
--summary "The parser change is ready for review." \
--body "Please review commit abc123." --require-wake
```
The recipient sees the preview plus an exact `m-att_...` claim token on one
line. A narrow pane may soft-wrap it; the bytes are unchanged. Claiming
through the socket does not cancel the queued doorbell. Claiming the token
retrieves the authorized envelope, including TO, FROM, subject, summary, the
full body, and reply context:
```bash
cyclops inbox claim m-att_
cyclops reply --body "Reviewed. No blockers."
```
`cyclops reply --last` answers the most recently claimed message.
These are different facts:
1. **Accepted** means the journal has the message.
2. **Notified** means the doorbell was written and submitted.
3. **Claimed** means the recipient retrieved the exact body.
4. **Completed** requires an explicit agent-side reply. Cyclops does not infer
task completion from idle state.
### The raw transport
`cyclops send --raw` (and `cyclops reply --raw`) pastes the whole message,
header, body, reply hint, and end marker, into the recipient pane and presses
Enter with no composer check. It exists for exactly two cases: Cyclops's own
composer reading is wrong for that pane, or the recipient is an unverified
vendor. The journal records it as an unverified raw write, so nobody mistakes
it for a gated delivery, and Cyclops never selects it on its own.
## The composer rule
Agent activity and the composer are separate questions.
- `idle` and `working` describe agent activity for the human.
- The composer check asks one thing: is a human draft positively visible, or
does a delivery already own the composer? Only then does a doorbell wait.
A working agent gets its doorbell during the turn; the vendor queues the line.
An idle agent with an unreadable composer gets it too, and the journal marks
the attempt `submitted_unverified` if the line could not be read back. A
positively observed draft holds the same attempt until the draft is seen
erased or the turn ends, never on a clock. A modal, a permission prompt, a
quota screen, a dead pane, or copy-mode holds on its name and pings the admin
once after `gate_hold_notify_ms`.
## The workspace
The full-screen workspace keeps tmux as the terminal owner while adding:
- sessions, workspaces, tabs, splits, resizing, and drag controls;
- live terminal cells with keyboard, mouse, selection, and clipboard support;
- named agents and conservative idle, working, gating, blocked, and failed
status;
- a bordered Messages peer pane with authorized threads, recipient state, and
operator actions;
- themes, sounds, unread projection, and independent viewport state.
Closing the workspace does not stop the daemon or discard accepted messages.
The CLI, daemon, mailbox, and `cyclops watch` remain independently usable.
## Recovery and honesty
Cyclops never converts uncertainty into success.
- A failure proven before the paste leaves the message queued or durably
blocked, with nothing written and the cause named.
- A paste that could not be read back is still submitted once and recorded
as `submitted_unverified`; a missing receipt ends as `notified` with no
verifier. Neither is retried.
- A physical write failure (a paste or submit command that failed, or a pane
whose occupant changed after the paste) stops as `attention_required` for
a human to inspect. `cyclops requeue ` starts a fresh attempt
after the cause is understood.
- A daemon restart replays the journal, closes every attempt caught between
the paste and its receipt to `attention_required`, and reconstructs
mailbox state.
- Stable tmux and process identities prevent a renamed or replaced pane from
inheriting another occupant's delivery.
Start troubleshooting with `cyclops health`, `cyclops status`, and
[`docs/guides/troubleshooting.md`](docs/guides/troubleshooting.md).
## Useful commands
| Command | Purpose |
|---|---|
| `cyclops` | Open the full workspace |
| `cyclops start --preset duo` | Create a workspace from a shipped layout |
| `cyclops name --self