Managing Work

The sidebar sits on the right side of the screen by default (tui.sidebar.side can move it to the left) and shows the live state of your session in four panes:

Session. Your session title, current model, and facet. Until a title is set for the session, it shows no session title.
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 when you want the full width for the conversation, and open it again to see the panes. The sidebar’s starting state comes from tui.sidebar.default-state: open by default, or collapsed to begin with the sidebar out of the way.

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.

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. A small toggle by the prompt opens the sidebar. In mini mode, the open sidebar overlays the conversation instead of reducing the conversation’s width. Widen the terminal to return the sidebar to its docked layout.

The column width that triggers mini mode is tui.sidebar.collapse-threshold (default 82). Raise the threshold to enter mini mode sooner, or lower the threshold 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: moving a todo to in progress or completing it fails until every dependency is done, and you cannot delete a todo that others depend on.

The todos pane shows pending, in-progress, and blocked todos. Type /todo to open an overlay containing all todos Polytoken retains, including completed todos. With the todo overlay open, press Esc or click outside the overlay to close the view and return focus to the prompt.

The todo list belongs to the session. Polytoken preserves the list through compacting and clearing, and a rewind restores the list 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. See Subagents for how the model uses subagents.

Background work can continue after a turn ends. To avoid signaling completion while that work remains live, Polytoken suppresses the turn-completion bell for finite non-service jobs. A later turn completion rings once no such jobs remain. Polytoken does not queue or replay a suppressed bell when a job finishes.

Opening the Jobs viewer

The compact Async jobs pane shows live top-level jobs, including subagents waiting in the queued state. Queued jobs have a distinct status color from running jobs. The full Jobs viewer shows child jobs beneath their parent, including shells started by a subagent and jobs nested below another subagent. Live jobs appear above completed, failed, and cancelled jobs.

Type /jobs to open the Jobs viewer. Use /jobs <handle> to open a particular job by its handle. Ctrl+F3 and Ctrl+Shift+F3 both toggle the jobs pane. Terminals using the kitty keyboard protocol report the two chords as distinct keys. Some legacy terminals cannot send Ctrl+Shift+F3. Use /inputdebug to see which key events your terminal reports.

Shell, service, and tool-flow details

Select a job row to inspect its details. Shell and service jobs show the command line and one output channel at a time. With a shell or service job selected in the Jobs viewer, press Space to switch between standard output and standard error.

When loaded detail content exceeds the pane, a scrollbar appears on the pane’s right edge. Drag the scrollbar or use the mouse wheel over the detail pane to scroll the loaded content. With the detail pane focused, PageUp, PageDown, Home, and End scroll locally. Selecting another job resets the local view to the top; refreshing the same job preserves the scroll position.

With the job tree focused, PageUp and PageDown request different output pages rather than scrolling the loaded content. Press End in the tree to follow the newest output of a running shell or service job. Polytoken refreshes the tail while you follow, including output from backgrounded shell commands. Paging away from the newest output pauses following and shows a marker when more output arrives. Press End in the tree again to resume following. Following stops when the job completes.

Service details show the service state and offer a copyable URL when the service publishes one.

Tool-flow details show the retained structured result.

Subagent conversations and progress

Subagent details split the pane into two stacked subpanes separated by a horizontal divider. The upper subpane summarizes the subagent: handle, status, progress, activity, model, retry waits, current tool, and history size. The lower subpane shows the subagent conversation. Polytoken keeps the summary to a bounded slice of the pane and gives the conversation the remaining rows. On a terminal too short to fit both, the conversation keeps the pane.

Each subpane scrolls on its own. The pointer wheel and each subpane’s scrollbar affect only the subpane under the pointer, whichever pane the keyboard focuses. Wheeling the job tree scrolls the job list. Dragging a scrollbar moves only its own subpane, and releasing the drag outside the viewer ends the drag safely. A scrollbar appears in a subpane only when that subpane’s content overflows.

The summary carries the compact progress summary Polytoken publishes: the most recently completed items, their total count, and the next action. Long progress, activity, and metadata content stays reachable by scrolling the summary. The pane follows the selected job, and switching the selection or toggling the summary returns it to the top. If you change the selection mid-drag, the drag continues on the newly selected subagent. Compaction markers appear as they do in the main conversation.

In a pane tall enough to afford them, Polytoken labels the two regions: Job status and progress above the summary, and Subagent conversation on the divider between the subpanes. In a shorter pane the labels drop away and the conversation keeps their space; the divider becomes a plain rule.

While a subagent runs, the summary names the current tool and shows its shell command or a compact input summary, along with how long the current tool batch has been running. The job row also displays the current tool name. Last activity shows an age, such as 45s ago, followed by the exact timestamp in parentheses.

With the subagent detail pane focused, press H to collapse the summary to the handle, the current status, and the latest activity lines. Press H in the same pane again to restore the full summary. Polytoken saves this preference, so it survives resizing.

During a provider retry wait, the summary shows the wait reason, countdown, and attempt count. The wait appears even if the wait began before you attached. Polytoken removes the wait display when the retry starts or the subagent completes.

Searching and navigating jobs

With the job tree focused, press / to search metadata such as handles, tool names, kinds, subagent names, and statuses. Search results include matching rows inside folded subtrees. Each indented row has a ├ or └ connector just inside the selection marker to show the row’s place among its siblings.

In the two-pane layout, Tab switches focus between the job tree and a loaded subagent conversation. Selecting any other job keeps focus in the tree. Card navigation in a subagent conversation starts on a visible card and keeps the selected card in view.

With the tree focused, Left and Right fold and unfold subtrees. Rows without children never fold. With a subagent conversation focused, Left and Right collapse and expand the selected card.

Stopping and copying jobs

With a reserved or running job selected in the Jobs viewer, press c to open a stop confirmation. Queued jobs offer stopping after they leave the queue. Services label the action Stop. The confirmation reports how many direct shell children will also stop. Completed, failed, and cancelled jobs do not offer stopping.

If a job finishes while its stop confirmation is open, the confirmation stays open until you answer. Confirming then fails because the job has already finished, and Polytoken reports the failure.

With the job tree focused, press Y to copy the selected job’s handle. With the detail pane focused, Y copies the selected job’s detail: the loaded shell output page (or the shell log path if no output is loaded), the service URL, the retained tool-flow result, or the whole retained subagent conversation.

Narrow layouts and closing the viewer

Below tui.sidebar.collapse-threshold (default 82), the Jobs viewer uses one window with Tree and Detail tabs instead of two panes. In this layout, Tab switches tabs for every selection. The Detail tab supports the same local scrolling and scrollbar as the two-pane layout.

Click outside the Jobs overlay to close the viewer. With the viewer open, Esc backs out one step at a time: dismissing an open stop confirmation, clearing an active search, returning detail focus to the tree, then closing the viewer once the tree has focus. The model starts jobs; you do not start them from the Jobs viewer.

Goals and background work

With an active saved session goal, Polytoken waits for live top-level shell and subagent jobs before automatically continuing the goal, provided notification auto-drain is on. Job completion wakes the session so Polytoken can continue the goal. Service jobs do not pause goal continuation.

Notification auto-drain adds arriving notifications to session history so the model sees them without a manual step. The setting notifications.auto_drain_notifications defaults to on. See Configuration.

Goal mode keeps work moving while you are away. When the model asks a structured question and you have not sent a prompt in this session within the last three minutes, Polytoken guides the model to choose an answer without showing you the question. If you sent a prompt within that window, Polytoken shows the structured question so you can answer directly.

Only prompts you send in the current session count toward the presence window. Restarting or resuming a session resets the window. Automatic goal continuation turns do not count as your presence.

/goal clear and /goal resume queue if you issue either command during a running turn. Polytoken applies a queued /goal clear at the running turn’s next safe point and shows a card when the clear queues and when the clear applies.

Issue /goal set and /goal pause after the turn ends. Both commands fail rather than queue during a running turn.