> ## 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. # Configuration > Configure Cyclops sessions, themes, chrome, and runtime state. Cyclops keeps its config and runtime state under `~/.cyclops`. Set `CYCLOPS_HOME` to use another directory; keep it short enough for a Unix socket path because the daemon creates `$CYCLOPS_HOME/sock`. The main file is `$CYCLOPS_HOME/config.toml`. `cyclops start` creates a minimal one and never overwrites settings you add. ## Example ```toml theme={null} sessions = ["main"] default_workspace = "main" theme = "dark" chrome = "on" ack_timeout_ms = 1500 delivery_retry_max = 1 receipt_block_ms = 2500 gate_hold_notify_ms = 120000 [workspace] sidebar_visible = true sidebar_width = 24 files_rows = 8 tab_bar_visible = true motion = true workspace_order = ["main"] agent_order = ["name:implementer", "name:reviewer"] folder_tracked = [] terminal_default_fg = "#3a2b26" # opt in to themed terminal window padding terminal_default_bg = "#000000" ``` ## Top-level keys | Key | Purpose | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessions` | tmux sessions the daemon watches when it starts. | | `default_workspace` | Workspace opened by a bare `cyclops start`. | | `manifest_dir` | Optional directory containing detection manifests; otherwise Cyclops tries `$CYCLOPS_HOME/manifests`, then `./manifests`. | | `tmux_socket` | Optional tmux `-L` socket name. | | `tmux_config` | Optional tmux config path passed with `-f`. | | `theme` | Active theme name. `cyclops theme ` updates it safely. | | `chrome` | `"on"` or `"off"`; controls Cyclops-owned tmux border decoration. | | `ack_timeout_ms`, `delivery_retry_max`, `receipt_block_ms`, `gate_hold_notify_ms` | The hook ACK window after a doorbell is submitted, retries for failures proven before any bytes reach the pane, the cap on observing an immediately decidable receipt, and the one admin ping for a doorbell held that long. The 1.0 keys `ambiguous_composer_settle_ms`, `unclaimed_reminder_ms`, `force_notification_submit`, and `force_notification_submit_delay_ms` no longer exist; a file that names one boots with a warning. | The full-screen workspace maintains `[workspace]` preferences: the sidebar's visibility and width, how many rows its file panel gets (`files_rows`), whether the tab bar shows, whether chrome fades between states (`motion`), the persisted workspace and agent order, which workspaces follow their active pane's folder (`folder_tracked`), and where the pinned file browser points (`files_pinned_root`). Unknown keys are preserved when it writes preferences. `terminal_default_fg` and `terminal_default_bg` are an operator-owned optional pair: each must be a `#rrggbb` value. Supplying both opts in to themed terminal window padding: Cyclops applies the theme through OSC 10/11 while focused and restores that pair on workspace exit and focus loss. An absent, partial, or invalid pair leaves the host palette untouched. Cyclops does not read terminal input to discover a palette. ## Runtime files | Path | Purpose | | --------------------------------------------------------- | ----------------------------------------------------------- | | `$CYCLOPS_HOME/sock` | Unix socket used by the CLI and daemon. | | `$CYCLOPS_HOME/workspaces//messages.ndjson` | Canonical workspace mailbox journal. | | `$CYCLOPS_HOME/ledger/*.ndjson` | Pane state and per-attempt session records. | | `$CYCLOPS_HOME/registry.json` | Durable pane names and adoption identity. | | `$CYCLOPS_HOME/workspaces/*.toml` | Saved workspace layouts. | | `$CYCLOPS_HOME/manifests/` | Per-CLI detection rules. | | `$CYCLOPS_HOME/themes/` | Semantic color themes. | | `$CYCLOPS_HOME/cyclopsd.log` | Bounded daemon log, including foreground and detached runs. | | `$CYCLOPS_HOME/hook-errors.log` | Bounded diagnostics from short-lived agent hooks. | `cyclopsd.log` is capped at 1 MiB for the full daemon lifetime. When it reaches the cap, Cyclops keeps up to 512 KiB of recent complete lines before appending the new event. One tracing event is capped at 64 KiB and keeps its most recent bytes. `hook-errors.log` is capped at 256 KiB, with each failure limited to one 4096-byte line. A hook drops a diagnostic instead of waiting when another process holds the log lock. Both logs are opened through the protected state root. Cyclops refuses a symlink or multiply linked log instead of following or repairing its target. Use `cyclops health` to identify an unsafe entry, inspect it, and replace it before restarting the daemon. `cyclops daemon log` reads the daemon log. ## Environment variables | Variable | Purpose | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CYCLOPS_HOME` | Runtime home; defaults to `~/.cyclops`. | | `CYCLOPS_THEME` | Theme name or theme-file override. | | `CYCLOPS_LOG` | Daemon tracing filter, such as `debug`. | | `CYCLOPS_AGENT` | Optional namespace for per-pane hook sequence counters. The daemon derives hook identity from the authenticated socket peer, so renaming does not require rewriting hook configuration. | | `CYCLOPS_NO_VENDOR_HOOKS` | Set to any value to install without editing agent CLI configuration. See below. | | `NO_COLOR` | Disable color without removing state words or glyphs. | ## Agent hooks Detecting an agent and hearing from it are different things. Detection reads the pane; hooks are how a CLI reports its own turn edges, and the acknowledgement hook is how a doorbell earns a verified receipt instead of settling on screen evidence. Mailbox receipts report durable acceptance and notification state separately. The installer wires them, by passing `--wire-hooks` to its final `cyclops start --setup-only`. Where they land depends on how each CLI finds them: | CLI | Where its hooks go | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Code | `~/.claude/settings.json` for normal direct launches. Cyclops safely merges its entries there after explicit `--wire-hooks` consent and copies the original aside before the first edit. `cyclops start --agents claude` still generates an isolated settings file for each pane and passes `--settings`. | | Codex | `$CODEX_HOME/hooks.json`, user level. Project-local `.codex/hooks.json` does not load until the directory is trusted, and that dialog cannot be answered in a non-interactive run, so hooks placed there silently never fire. | | Antigravity | `~/.agents/hooks.json`. | | Cursor | `~/.cursor/hooks.json`. | | Kimi Code | `~/.kimi-code/config.toml`. | | Gemini CLI | `~/.gemini/settings.json`; unverified. | | Qwen Code | `~/.qwen/settings.json`; unverified. | | goose | `~/.agents/plugins/cyclops/hooks/hooks.json`; unverified. | For the vendors that read a file of their own, Cyclops merges its entries around whatever is already there, copies the original to a sibling file named `.before-cyclops` before the first edit, and rewrites nothing on a run that would change nothing. A CLI that is not installed is skipped. `cyclops start --setup-only` on its own never touches agent configuration; only `--wire-hooks` does. To install without it, set `CYCLOPS_NO_VENDOR_HOOKS=1`, then wire whichever agents you want by hand with `cyclops hooks install --agent