Managing Work

The sidebar shows the session state, active todos, flagged files, and background jobs.

The sidebar sits on the right side of the screen and shows the live state of your session in four panes:

Session. Your current model and facet.
Flagged files. Files the model or Polytoken has marked as important to the work at hand.
Async jobs. Background work currently running.
Todos. The task list for the work in progress.

Collapse the sidebar to give the conversation more width when you want the full width for the conversation, and open it again to see the panes.

The flagged-files pane reflects choices the model and Polytoken make, not choices you control. The plan facet, for instance, flags the plan the model is working from. Polytoken marks a flagged file in one of two ways: it keeps the file’s contents alongside the session, or it records the file by name alone. Sessions explains what that distinction does.

Double-click a flagged file to copy its absolute path to your clipboard. This is handy when you need to paste the path into another tool or a shell command.

Mini mode

When the terminal is too narrow to show the sidebar and the conversation side by side, Polytoken switches to mini mode. The sidebar starts retracted so the conversation has the full width, and a small toggle by the prompt opens it. Because there is no room beside the conversation, an open sidebar in mini mode floats over it rather than narrowing it. Make the terminal wide enough again and the sidebar returns to its docked layout.

The column width that triggers mini mode is tui.sidebar.collapse-threshold (default 82). Raise it to enter mini mode sooner, or lower it to keep the docked sidebar on tighter terminals. See Configuration for the full setting.

Todos

A todo is one task in a list. The model uses todos to track work that takes several steps: as it works, it adds todos, marks each one in progress, and completes them.

Each todo has a status (pending, in progress, done, or blocked), and a todo can depend on others. Polytoken enforces those dependencies: a todo cannot become in progress or done until everything it depends on is done, and you cannot delete a todo that others depend on.

The todos pane shows the active list: todos that are pending, in progress, or blocked. Completed todos drop off the sidebar once they are done, but they are not gone. Typing /todo opens the full todo view as an overlay, which includes every retained todo. Close it with Esc or by clicking outside the overlay, which also returns focus to the prompt. The list belongs to the session: it carries through compacting and clearing unchanged, and a rewind restores it to the point you return to. See Sessions.

Jobs

A job is background work that continues while you use the conversation. Polytoken shows shell commands, services, tool flows, and subagents as jobs. A subagent is a separate model task that handles a bounded piece of work. While a finite non-service background job remains live, Polytoken suppresses the turn-completion bell. A later turn completion rings once no such jobs remain. Polytoken does not queue or replay a suppressed bell when a job finishes.

The compact Async jobs pane shows live top-level jobs, including subagents that are waiting in the queued state. Queued jobs carry their own status color in the sidebar, distinct from running jobs, so you can tell waiting work from active work at a glance. Child jobs stay in the full viewer so the compact pane remains easy to scan. Type /jobs to open the retained-job viewer. Type /jobs <handle> to open a particular job when you already know its handle. The viewer keeps live jobs above completed, failed, and cancelled jobs. Child jobs appear beneath their parent, including shells started by a subagent and jobs nested below another subagent. Ctrl+F3 and Ctrl+Shift+F3 both toggle the jobs pane: terminals that speak the kitty keyboard protocol deliver the two chords as distinct keys, some legacy terminals cannot send Ctrl+Shift+F3 at all, and /inputdebug shows which key events your terminal actually delivers.

Select a row to inspect its details. Shell and service jobs show the command line and output one channel at a time: press Space to switch between standard output and standard error. The detail content scrolls locally when it exceeds the pane: a scrollbar appears on the pane’s right edge, dragging it or the mouse wheel over the pane moves the view, and with the detail pane focused PageUp, PageDown, Home, and End move the local view. This local scroll position is separate from the remote output window that PageUp and PageDown page through while the tree pane is focused. Switching to another job resets the local view to the top; refreshing the same job keeps it. Subagent details show the subagent conversation in a pane of its own with a scrollbar you can drag directly: dragging it scrolls that subagent’s conversation without touching the main conversation behind the viewer, and it follows the job you have selected, so changing the selection mid-drag continues on the newly selected subagent. Press End to follow the newest output of a running job; Polytoken refreshes the tail while you follow it, including output from backgrounded shell commands as the command runs. Scrolling away from the newest output pauses following and shows a marker when more output arrives; press End again to resume. Following stops on its own once the job completes. Service details also show the service state and offer a copyable URL when the service publishes one. Tool-flow jobs show their retained structured result. Subagent details show the latest progress and activity above the subagent conversation and the launch model reference, including request options, effort, status, and elapsed time. The progress header stays compact: it lists at most the three most recently completed items, labeled with how many exist in total (for example Completed (latest 3 of 12)). When the header shortened the list, Polytoken renders a full-ledger block at the top of the subagent conversation area whenever the pane has room for one. Polytoken caps the height of both the expanded header and that ledger block so neither can crowd out the conversation below, and neither clips silently: the full-ledger block shows the tail of the ledger behind an explicit elision marker, and the expanded header keeps its leading lines and ends with an explicit elision marker (… (later header lines elided in this view)) when its later lines no longer fit. Only a pane too short to hold a marker alongside the header’s first line clips without one. Even when Polytoken clips those blocks, the complete ledger data stays available through the job’s output and retained snapshots. While a subagent runs, the detail header also names the tool the subagent is executing right now, with the shell command or a compact input summary and how long the current tool batch has been in flight, and the job row in the tree appends the tool name. Last activity reads as an age, such as 45s ago, followed by the exact timestamp in parentheses. Press H in the subagent detail pane to collapse the header to the handle and current status. Press H again to restore the full header. The activity block stays visible below the collapsed header: Polytoken shows activity: followed by the block’s leading lines, capped so the subagent conversation below keeps its reserved space. Activity lines wider than the pane end with an ellipsis. When later lines do not fit, the block ends with an explicit marker (… (later activity lines elided in this view)). A pane with room for only one activity line shows that line alone; a pane with no room for an activity line shows none. Compaction markers in a subagent conversation appear in the same way as compaction markers in the main conversation. When a subagent’s provider is making Polytoken wait before a retry, the detail header shows the wait reason, a countdown, and the attempt count; the line appears whether the wait started while you watched or before you attached, and it disappears when the retry fires or the subagent completes.

Press / to search job metadata such as handles, tool names, kinds, subagent names, and statuses. A search shows matching rows even inside a folded subtree. Every indented row carries a ├ or └ connector, placed just inside the selection marker, that marks its place among its siblings. Tab switches between the job tree and its detail pane. Card navigation starts on a visible card, and moving the selection keeps the selected card in view. In the tree, Left and Right fold and unfold a subtree; rows without children never fold. In a subagent conversation, Left and Right collapse and expand the focused card. Press c on a live job to open a confirmation before stopping it. Services label the action Stop. The confirmation discloses the direct shell children that will also stop. Terminal jobs do not offer stopping. When a job finishes while the confirmation is open, Polytoken closes the dialog and shows an error instead of stopping anything. Press Y to copy the handle, visible output, log path, service URL, or selected subagent card, depending on the current selection.

Below the tui.sidebar.collapse-threshold width (default 82), the same width that switches the sidebar to mini mode, the viewer trades its two panes for one window with Tree and Detail tabs; Tab switches between them for every selection, and the detail tab carries the same local scrolling and scrollbar as the two-pane layout. Press Esc to close the viewer, or click outside the overlay. The model starts jobs; you do not start them from the Jobs viewer.

When you keep a saved session goal active, Polytoken pauses automatic goal continuation while a top-level shell or subagent job remains live and notification auto-drain is enabled. The TUI resumes the goal after the job finishes. A service job does not pause goal continuation.

Goal mode normally answers the model’s questions on your behalf so work keeps moving while you are away. If you have sent a prompt in this session within the last three minutes, Polytoken instead shows you the model’s structured question so you can answer it directly. The window tracks only prompts you sent in this session: restarts and resumes start empty, and continuation turns the Goal Driver starts on its own never count as your presence.

Goal commands you issue while a turn is running queue instead of failing. /goal clear applies when the running turn reaches its next safe point, and the TUI shows a card both when the clear is queued and when it applies.

For how the model uses subagents, see Subagents.