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.

The compact Async jobs pane shows live top-level jobs, including subagents that are waiting in the queued state. 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.

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

For how the model uses subagents, see Subagents.