> ## Documentation Index
> Fetch the complete documentation index at: https://usecyclops.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Build and install the current Rust implementation of Cyclops.

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](https://rustup.rs) 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

```bash theme={null}
curl -fsSL https://www.usecyclops.dev/install.sh | sh
```

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:

```bash theme={null}
git clone https://github.com/cyclops-team/cyclops.git
cd cyclops
./scripts/install.sh
```

Use `--prefix` to choose the bin directory, or `--no-path` to prevent any
shell-profile edit:

```bash theme={null}
curl -fsSL https://www.usecyclops.dev/install.sh | sh -s -- --prefix "$HOME/bin" --no-path
```

## Verify and start

```bash theme={null}
cyclops --version
cyclops
```

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:

```bash theme={null}
printf '%s\n' "$TERM"
```

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](https://github.com/cyclops-team/cyclops/blob/main/docs/guides/troubleshooting.md#codex-warns-that-term-is-dumb).

## Update

```bash theme={null}
cyclops 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.

```bash theme={null}
cyclops update --rollback
```

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:

```bash theme={null}
./scripts/install.sh --uninstall
```

Without a clone:

```bash theme={null}
curl -fsSL https://www.usecyclops.dev/install.sh | sh -s -- --uninstall
```

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.