These are example tasks, not a recording. You can follow this workflow with ordinary shells; Agent reports are optional. Each Agent or program still owns its work. Deck helps you choose where to look.
1. Give each piece of work its own card
- Select a project in Deck and create a session with ＋. Run your usual command or installed Agent CLI in its terminal. New to Deck? Start here.
- Double-click the title to give the card a useful name, such as “Review change”, “Investigate bug” or “Run tests”. Repeat for your other work.
- Return to the Board with the back button. The programs keep running. Place cards in the groups that help you find them later; live status never moves cards between groups.
Separate cards make each session easier to identify. Agent status reflects the active pane of a session's current tmux window; it is not a census of every Agent in manually created tmux splits.
2. Keep important work in view
Click ☆ on a card to Follow card. Open Needs attention in the sidebar, then use Followed to find these cards across projects. This works for the test shell too, without an Agent integration.
A star records your intention to return. It does not say the program is waiting, finished or successful. It stays until you unfollow the card, including after viewing its terminal or restarting Deck. Unfollow when you no longer need that manual follow-up; another attention reason can still keep the card in the list.
3. Add Agent reports when supported
In Settings, find the Claude Code or Codex status integration for the CLI you actually use. Both are off by default. Read the confirmation before enabling: Deck adds hooks to that CLI's configuration. Existing non-Deck hooks are preserved.
Use the matching CLI in a Deck session, then check whether it reports a state. Merely enabling an integration is not proof that reports are arriving. CLI event support and configuration affect coverage; other CLIs do not automatically gain explicit input-request or turn-ending reports.
For Codex: installed hooks may still need review and trust in Codex
/hooks. With a shared background service, Deck may be unable to attribute events reliably to the right terminal. Treat missing reports as a coverage gap. Input-request hooks do not cover every question or MCP elicitation.
4. Choose what to open next
In Needs attention, read each row's project and group before opening it. Labels can vary with your installed version; focus on the reported fact.
| What you see | What to do |
|---|---|
| Input requested (or Needs input) | Open the terminal and read the actual question or permission choice. The report says input was requested; check what the Agent needs now before responding. |
| Turn ended · unread | Read the result and verify the outcome that matters to you. A turn ending is not task completion or success; the Agent or background work may continue. |
| Followed | Revisit work you chose to keep visible, including ordinary shells. Inspect the terminal for its current situation. |
| No valid state, quiet or recent output | Open the terminal when you need to know. Without a valid Agent report, recent output is activity and quiet is only a lack of output. Quiet is not readiness. |
A turn ending becomes read only when the terminal attaches and displays successfully. Opening a card does not answer an input request or prove it was handled. If you separately use a prompt list with human inspection, reading the terminal does not release that checkpoint. Inspect before continuing.
5. Check gaps before relying on an empty list
- No entries: check No valid state and your followed cards. An empty attention list does not prove there is nothing to handle.
- No Agent reports: confirm the matching integration and CLI configuration, and inspect the terminal directly. Keep an important card followed while coverage is missing.
- Old snapshot or failed refresh: retry the refresh. The last observation may be useful context, but it is not current status.
- Stopped or stale session: locate the original card and inspect what is available. Locating it does not prove the process resumed or the task finished.
After handling a session, return to Needs attention; its filter and scroll position are restored. Read markers last only for the current app run. Unread history and missed-event replay are not guaranteed across Deck restarts. The saved follow-up star is separate from that temporary read state.
Use the back button to leave a terminal view. Closing a card ends its session; do not close one just to clear an unread result. Machine restarts and service restarts can end session processes. Read the session lifecycle guide before leaving long-running work.
Technical references: product boundaries · attention and read state · Report an issue