Skip to main content
Cyclops currently installs from source. The installer builds both cyclops and cyclopsd, places them in a user-writable bin directory, and creates the initial ~/.cyclops configuration. The build is a full release compile of a Rust workspace: budget a few minutes on a fast machine, longer on older or low-power hardware. Prebuilt binaries are not published yet.

​
Requirements

  • macOS or Linux
  • tmux 3.2 or newer
  • A Rust toolchain with cargo, recent stable (1.85+). Cyclops builds from source, so this is a hard requirement, but not a manual step: when cargo is missing, the installer installs Rust with rustup itself (non-interactive, shell profiles untouched; CYCLOPS_NO_RUSTUP=1 declines). Installing Rust yourself? Use rustup, not Homebrew or apt: package-manager Rust pins the compiler it shipped with, and rustup is what keeps a stable toolchain current.
  • curl and Git when using the one-line installer

​
Install

The script fetches the current main branch and builds it locally. It never uses sudo. It prefers a bin directory already on your PATH; otherwise it uses ~/.local/bin and offers to add that directory to your shell profile, after making a timestamped backup. Setup also merges Cyclops-owned hook entries into detected agent CLI configs and can add the final Cyclops skill file below an existing private canonical skill parent. It preserves unrelated vendor settings, backs up a vendor config before its first edit, and does not create homes or skill directories for agent CLIs that are not installed. Set CYCLOPS_NO_VENDOR_HOOKS=1 to skip hook and skill wiring. To build a clone you already have:
Use --prefix to choose the bin directory, or --no-path to prevent any shell-profile edit:

​
Verify and start

A bare cyclops opens the full-screen workspace, starting a tmux session and the daemon when neither is already running. If the installer added a PATH block, first open a new shell or run the reload command it printed.

​
If Codex reports TERM=dumb

Do not continue into the interactive TUI from that shell. Run:
An agent pane inside tmux normally reports tmux-256color; a regular terminal outside tmux commonly reports xterm-256color. Cyclops does not set TERM=dumb. Remove that value from the shell profile, launcher, or automation that created the shell, then create a new tmux pane or restart the pane shell and agent. Existing processes keep the old environment. Do not claim richer terminal capabilities in a non-interactive pipe merely to suppress the warning. Headless tmux control clients may report dumb without changing an agent pane. Check the value in the exact pane where the agent starts. The full diagnostic is in the repository’s troubleshooting guide.

​
Update

It names the running build, checks the source, and builds a candidate matched CLI and daemon pair. Before activation, the candidate proves its build identity and replays a private copy of the current journals. One selector activates the pair after the exact running daemon generation quiesces. The previous pair is retained for recovery. A daemon that was running is restarted on the selected pair. When no daemon was running, update leaves it stopped; the next cyclops or cyclops start starts the selected daemon.
Rollback validates the retained pair and proves that it can replay a private copy of the current journals before changing the selector. Configuration, manifests, workspaces, and journals remain under ~/.cyclops; rollback does not restore earlier state or promise compatibility beyond that replay proof. A running daemon is quiesced and restarted. A stopped daemon stays stopped. Existing setup files stay unchanged. Known unedited shipped themes and hook artifacts may advance with the installed release; manifests and skills remain in place and can report outdated state. Update also refreshes Cyclops-owned vendor hook entries unless CYCLOPS_NO_VENDOR_HOOKS=1 is set. Pair activation is the update commit point. If later home setup needs repair, the matched pair remains active and the installer prints the exact cyclops start --setup-only --wire-hooks repair command. An older daemon that cannot report its exact process generation is never stopped automatically. The update prints a one-time manual stop and rerun sequence. A legacy direct pair without matching source-build identity is used only to preserve executable continuity during migration, never as rollback. The first setup on the new build also repairs prepared hook artifacts under ~/.cyclops/hooks/ when their receipts prove they are still unedited. With vendor wiring enabled, setup also refreshes Cyclops-owned hook entries already merged into installed agent configs. Edited or unreceipted files are named and left unchanged.

​
Uninstall

From a clone:
Without a clone:
Uninstall stops the validated selected daemon and removes the complete current Cyclops state home, the two public binary links, the validated managed pair store, exact Cyclops hook entries, unedited seeded skills, and the installer-owned profile block. It refuses an altered pair store instead of deleting an unproven tree. Both public names are removed only from one prefix, selected by --prefix or by the cyclops command on PATH. Uninstall never resolves cyclopsd from a different prefix. If no cyclops anchor exists but cyclopsd is present, it refuses and asks for --prefix. Homebrew and Nix packages are not published yet.