Skip to main content

​
Open it

With no tmux server running, or none with sessions on it, Cyclops starts one: session main, one shell pane in the directory you ran it from, and tabs numbered 1, 2, 3… No preset or manual tmux new needed. Cyclops starts cyclopsd too, if nothing answers: every detected name, status glyph, and pane border decoration comes from the daemon, so the sidebar reads cyclopsd offline until one is running.

​
What’s on screen

  • Sidebar (left): a session tree of workspaces and agents, over a file browser. Drag the dashed rule between them to resize either half.
  • Tab bar (top): one tab per tmux window, plus + for the next one. Hide it from the Tab bar row on the settings card’s View section.
  • Pane canvas: the live tmux panes, one terminal cell to one tmux cell, each with its own border. The workspace also paints the terminal’s own background in the theme’s color while it has focus, handing it back the moment focus leaves.
  • Composer / footer: Ctrl+B s, or the sidebar footer’s @ button, opens a one-line message composer; the footer also has ☰ menu and a + for a new workspace from the focused pane’s folder.
A named pane carries its identity in its top border, e.g. implementer · ● working, collapsing to one of four glyphs:

​
Driving it

Bindings are prefix-first, Ctrl+B then a key, tmux’s own shape. Unbound keys, including modified keys like Claude Code’s Shift+Tab and bare arrow keys, pass through to the focused pane. Ctrl+B w (or the footer’s +) creates a session named for the focused pane’s folder and keeps following it on cd; a hand-typed rename (Ctrl+B W, or right-click) sticks for good. Mouse: click a pane, tab, or sidebar row to focus or switch to it, or right-click it for a menu. Drag the ⠿ grip in a pane’s bottom-right corner onto another pane to swap them; drag a border between stacked panes, or the sidebar’s outer edge, to resize. [▴] collapses a pane to its title bar (only on a pane stacked above or below another) and [▾] restores it. Ctrl+B s or the @ button opens the composer: @name then the message, taken literally. Enter sends; Alt+Enter (Shift+Enter / Ctrl+J) breaks the line instead. The dialog stays open and leaves @name in the field for the next send.

​
The file panel

Two browsers behind one header. The agent browser follows the focused agent’s directory: a pane switch or active-pane output requests one short, settled snapshot. That lets the panel catch a cd without polling the filesystem. The pinned browser stays where you last left it, remembered across launches (files_pinned_root). The header’s chip flips between them: [pin] while following the agent, [agent] while pinned. Click a file and its path is typed into the focused pane as @src/main.rs , relative to the panel’s root: nothing is submitted. A file clicked in the pinned view still resolves for the agent: relative under its folder, absolute outside it.

​
Preferences

Sidebar width, tab bar visibility, motion, and sidebar orderings persist under [workspace] in config.toml:
Motion fades pane borders, status ink, and dissolving notices instead of snapping, and turns itself off under NO_COLOR or without truecolor. See Configuration for the rest, including files_pinned_root and custom [workspace.bindings]. The optional terminal palette pair themes the window padding while the workspace is focused and restores the supplied colors through OSC 10/11. Both values are required; without them Cyclops leaves the host palette untouched and never queries terminal input for colors.
  • cyclops start builds or restores a saved workspace or preset without the full-screen UI; it’s still the front door for preset-built layouts.
  • cyclops watch is the narrower stream TUI: live events, no panes, with --json / --plain output.
  • Plain tmux attach reaches the same session without the chrome: no glyphs, composer, or file panel; those belong to the workspace TUI, not tmux.