# The work queue (https://docs.vitrinka.ai/dev/cli/work)



## See what is open [#list]

Lists the open work items for the current scope — this repository and branch, unless you narrow it.

```bash
vitrinka work list
```

## Hold the queue [#watch]

`watch` monitors the queue and **leases** a scope. One live listener per scope: several sessions can watch at once, but each holds its own scope, and a lapsed lease reverts its in-flight items rather than stranding them.

```bash
vitrinka work watch --project myapp --branch main
```

| Flag            | What it does                                                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--project`     | Watch a project. Defaults to this repository.                                                                                 |
| `--branch`      | Narrow a project scope to one branch. Defaults to the current branch.                                                         |
| `--board`       | Watch one board instead of a project scope.                                                                                   |
| `--all`         | Every scope — the firehose; takes no exclusive lease.                                                                         |
| `--harness`     | The harness this watch wakes, stamped on the lease: `claude` (default), `codex`, `cursor`, `opencode`, `vscode` or `gemini`.  |
| `--exec`        | Headless resume: feed every work line to a `claude` or `codex` listening thread, with that harness's own auto-approve policy. |
| `--once`        | A single lease-free probe. Exits `3` when the queue is idle.                                                                  |
| `--takeover`    | Steal an **expired** lease for this scope.                                                                                    |
| `--keepalive`   | Opt-in seconds between model-waking keepalive lines while a viewer is present. Default `0` (disabled).                        |
| `--quiet-grace` | Seconds to wait between diffs while the queue is non-empty. Default 5.                                                        |

## Host a harness [#listen]

`listen` hosts Codex, Gemini CLI or OpenCode (or Claude Code, when you name it) over the Agent Client Protocol and feeds it this scope's board work: each item arrives in the live session as a prompt. It takes the same scope flags as `watch`.

```bash
vitrinka work listen --harness codex
vitrinka work listen --harness gemini --board acme-audit --auto
```

`--auto` answers every permission request with allow-always, for an unattended listener; without it you approve as usual.

<Callout type="warn">
  You rarely run these by hand — `/vitrinka:listen` picks the rung: a background Monitor on `watch` in Claude Code, the `listen` host for Codex, Gemini CLI and OpenCode, else one scoped drain that ends on idle — [listening](/dev/mcp/clients#listening). Arming on the same machine takes the scope over; a live lease on another machine is never displaced (exit 2).
</Callout>

## Where the session stands [#status]

`status` is the session dashboard: the live board, the open work queue, and the listener lease.

```bash
vitrinka status --live
```

| Flag        | What it does                                           |
| ----------- | ------------------------------------------------------ |
| `--live`    | Repaint every few seconds on a terminal. Ctrl-C exits. |
| `--project` | Project name. Defaults to this repository.             |
| `--branch`  | Branch. Defaults to the current one.                   |
| `--root`    | Capture root. Default `.vitrinka/screenshots`.         |