> ## 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.

# The workspace

> The full-screen TUI a bare cyclops opens: session tree, file browser, tab bar, and live tmux panes.

## Open it

```bash theme={null}
cyclops                   # workspace (TTY required)
```

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:

| Glyph | Meaning                                                       |
| ----- | ------------------------------------------------------------- |
| `○`   | idle: no turn running                                         |
| `●`   | working: a turn is running                                    |
| `⚠`   | needs attention: open item in the daemon's attention register |
| `✕`   | dead: the pane's process exited                               |

## Driving it

Bindings are prefix-first, `Ctrl+B` then a key, tmux's own shape.

| Key                | Action                                                    |
| ------------------ | --------------------------------------------------------- |
| `Ctrl+B` `d`       | Detach (no separate quit; the tmux session keeps running) |
| `Ctrl+B` `n` / `p` | Next / previous tab                                       |
| `Ctrl+B` `c`       | New tab with the next number                              |
| `Ctrl+B` arrows    | Focus the pane in that direction                          |
| `Ctrl+B` `%` / `"` | Split right / down                                        |
| `Ctrl+B` `x` / `z` | Close / zoom pane                                         |
| `Ctrl+B` `m`       | Name the focused pane or agent                            |
| `Ctrl+B` `b`       | Collapse or reopen the sidebar                            |
| `Ctrl+B` `g`       | Put the keyboard in the file panel; Esc gives it back     |
| `Ctrl+B` `s`       | Send a message to an agent                                |
| `Ctrl+B` `?`       | Open the keybinding reference, every active binding       |

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`:

```toml theme={null}
[workspace]
sidebar_visible = true
sidebar_width = 28
tab_bar_visible = true
motion = true
terminal_default_fg = "#3a2b26" # opt in to themed terminal window padding
terminal_default_bg = "#000000"
```

Motion fades pane borders, status ink, and dissolving notices instead of
snapping, and turns itself off under `NO_COLOR` or without truecolor. See
[Configuration](/docs/reference/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.

## Related

* `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`](/docs/guides/attach-tmux) reaches the same session
  without the chrome: no glyphs, composer, or file panel; those belong to
  the workspace TUI, not tmux.