Cyclops

# 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