~/.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
Top-level keys
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
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
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:
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
<config>.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 <cli> --agent <label>.