Prompting and Input

Writing a prompt

The prompt is a multi-line text area. Type into the prompt and press Enter to send. Shift+Enter and Alt+Enter insert a line break without sending.

Shift+Enter requires a terminal that supports the kitty keyboard protocol. A multiplexer such as tmux can drop the keyboard enhancement after you detach and reattach. Resize the window once to restore the enhancement. Use Alt+Enter for line breaks when Shift+Enter sends instead; Alt+Enter reaches Polytoken as a distinct key even through a multiplexer.

You can remap newline and submission keys through tui.keyboard.commands with insert-newline and submit-prompt. See the configuration reference. A chord matching neither command falls through to ordinary text input.

When the cursor is on the last line of a multi-line text area, pressing Down moves the cursor to the end of that line. This applies to every multi-line text area: the prompt, free-text answers to questions, and the feedback editor. In the prompt window, this behavior applies while you are typing a new prompt. When you have recalled a previous prompt with Up, pressing Down moves to the next newer entry in your prompt history instead. Polytoken preserves the text you were composing while you page through history, and pressing Down past the newest entry restores that text. Moving the cursor inside a recalled prompt keeps your place in history.

Single-click inside the prompt to place the cursor. Clicking beyond a row’s visible text places the cursor at the end of that row; clicking below the prompt text places the cursor at the end of the final line.

Click and drag inside the prompt to select text, then release the mouse to copy the selection. Polytoken copies authored line breaks and ignores soft-wrapped display rows. Double-click the same prompt position to copy the complete prompt. Ctrl+Y copies the complete prompt when the prompt has focus.

Polytoken keeps a separate copy of the prompt text inside the TUI, so you can move text out of the prompt and bring it back even when your terminal does not expose a system clipboard. Ctrl+Shift+Y copies the prompt text and clears the prompt buffer, leaving the text ready to restore with Ctrl+V or your terminal’s paste shortcut. Ctrl+V pastes from the TUI-local copy, so it works over SSH where clipboard passthrough may be unavailable. All three shortcuts are configurable through tui.keyboard.commands under the copy-prompt, cut-prompt, and local-paste command IDs. See the configuration reference.

Ctrl+Y copies prompt text when the prompt has focus and copies the selected card in navigation mode. These copy actions are independent commands, so you can assign a different chord to each.

When you select rendered code rows in an expanded card, the copy matches what the rows show: tabs arrive as spaces, and the copy omits indentation that wrapping discarded at narrow widths. Ctrl+Y on the selected card copies the source Markdown verbatim instead.

Polytoken sends OSC-52 copies to your terminal, and your terminal forwards them to the system clipboard over the terminal connection. Polytoken does not check OSC-52 support at startup. If your terminal does not deliver OSC-52 copies, the copy does not reach the system clipboard. The TUI-local copy shortcuts, Ctrl+Shift+Y and Ctrl+V, still work.

Editing a prompt in an external editor

Press Ctrl+G to open the prompt in your configured external editor. While the editor is open, the editor owns the terminal. Polytoken does not read your keystrokes or draw TUI content during the edit. Ctrl+C and Ctrl+D reach the editor, so use the editor’s controls to cancel or exit.

When the editor closes, Polytoken restores the edited prompt and briefly discards leftover terminal input before accepting new keystrokes.

The Ctrl+G binding is configurable through tui.keyboard.commands under the open-editor command ID. See the configuration reference.

Queuing prompts

Prompts you send while Polytoken is working enter a queue for the next turn. The oldest queued prompt appears as a dimmed line above the prompt text area, with one blank line separating the preview from the conversation. Long previews end with an ellipsis; (+N) shows how many other prompts wait in the queue. Truncation preserves whole character clusters, including emoji and accented characters.

Press Up from the first line of the prompt to load the newest queued prompt into the prompt text area. Polytoken saves the draft text and pending images that the queued prompt replaces. While you are not browsing prompt history, press Down from the last line of the loaded queued prompt to restore the saved draft. Polytoken restores the draft only once, and typing new text discards the saved draft. Pressing Up from a later line moves the cursor instead of editing the queue.

Pasting images

With the prompt focused, press Ctrl+Alt+V to add an image from the system clipboard. Polytoken shows each captured image as a pending chip above the prompt, and Ctrl+Alt+X clears all pending images. Pending chips survive a compaction-triggered history refresh because the chips belong to the current draft, not to server history. Pending chips also survive rewind. Polytoken clears the chips when you submit the prompt, accept a queued submission, clear context with /clear, or use the explicit remove command, Ctrl+Alt+X by default. Both shortcuts are configurable through tui.keyboard.commands under the paste-image and pasted-image-remove command IDs. The same shortcuts also work while the /feedback form is open, where they add or remove feedback screenshots instead of prompt images.

Before submission, Polytoken converts a clipboard image to JPEG, scales the image down when either dimension exceeds 2048 pixels, and replaces transparency with a white background. Clipboard images and images referenced with @ paths share one size allowance for image data, and Polytoken reports an error when a single image or a whole prompt exceeds the allowance.

You can submit an image without prompt text. While Polytoken is working, a prompt containing text, images, or both enters the same queue as any other prompt, and the queued-input indicator shows how many images belong to the next queued prompt.

Use a vision-capable model for prompts with images. If the active model cannot accept images, Polytoken leaves the prompt unsent and reports the problem.

Clipboard images come from the desktop clipboard of the machine where Polytoken runs. SSH, headless, and WSL sessions usually cannot reach that clipboard. In those sessions, reference an image file with an @ path instead.

Referencing things with `@`

Type @ anywhere in the prompt to open the reference picker. As you type after the @, Polytoken fuzzy-matches candidates and shows them in a bar above the prompt. Matching is case-insensitive: a query with uppercase letters matches the same candidates as its lowercase form.

The picker offers files, skills, subagents, models, and model groups:

You want to reference	Type	Short form
A file in your project	`@path/to/file`
The current directory	`@./path`
A file outside your project	`@../path`, `@~/path`, `@/path`
A skill	`@skill:name`	`@s:name`
A subagent	`@subagent:name`	`@a:name`
A model	`@model:name`	`@m:name`
A model group	`@modelgroup:name`	`@mg:name`

@skill: references also resolve in polytoken exec prompts, subagent prompts, plan-handoff continuations, facet templates, and chained skill bodies. Each surface applies its relevant allow and deny lists and fails when a reference is unavailable or blocked. A user-typed reference gives explicit consent and bypasses those lists. An exec prompt that names an unknown skill fails the run before any provider call. See Skills, Subagents, and Facets for authoring details.

The project file picker uses project-relative paths and filters matches as you type. Polytoken ranks matches before limiting the list, then orders the listed candidates by fuzzy match. When the list reaches its limit, the picker header shows List truncated — keep typing to narrow.

The catalog displays each physical name verbatim. Polytoken resolves a final path component when the typed name differs from the physical name only by an NFKC-equivalent Unicode form. The same rule applies to file tools. For a name containing spaces, use the quoted form, such as @"Screenshot 2026-08-15 at 19.03.29.txt". If a path does not exist, Polytoken reports the requested path, whether the parent exists, and nearby entries when available. If multiple physical names fold to the same spelling, Polytoken rejects the reference instead of choosing one.

Polytoken delivers the referenced file’s contents to the model. When a file is not valid UTF-8, Polytoken delivers a short omission note naming the withheld byte count instead of the contents.

By default, Polytoken leaves out hidden files, the project’s .polytoken/ directory, and anything covered by .gitignore, .claudeignore, or .polytokenignore.

You can browse the current directory with @. (or @./). This shows the immediate children of the directory you are working in: the project root by default, or the subdirectory you navigated to with pushd. Unlike the external browse prefixes below, files you reference this way stay inside the project, so they resolve through the project file catalog just like regular project-relative references.

You can also reference files outside the project tree. Three prefixes take you out of the project:

@.. browses the project’s parent directory. Type additional path components to browse subdirectories: @../sibling/notes.md references a file in a sibling directory.
@~ browses your home directory. @~/Documents/report.md references a file there.
@/ browses the filesystem root (Unix only). @/etc/hosts references the system hosts file.

Outside the project, the picker shows only the immediate children of the directory you are browsing. Type a subdirectory name and press / to enter it. Polytoken hides hidden files and .gitignore matches by default in browsed directories; Shift+Tab reveals those entries.

An exactly typed external reference follows symlinks. For safety, Polytoken rejects external symlink candidates whose names match only after Unicode normalization.

When you select a file from outside the project, Polytoken reads its content at submit time and injects it as a system reminder, exactly as it does for project-relative references.

Two extra controls appear while the picker is open, and the bar shows them when they apply:

Shift+Tab toggles the file-ignore rules. With the rules off, the picker includes hidden files, the project’s .polytoken/ directory, and entries that .gitignore would normally hide. Version-control metadata directories such as .git stay hidden.
[ and ] adjust the reasoning level when you have a model reference selected.

Thought cards

When tui.show_all_thinking_blocks is enabled, Polytoken keeps completed model reasoning in the transcript as collapsed Thought cards. Each card shows Thought for 5.37s, where the number is the reasoning pass duration in seconds, or Thought for older history without a duration. Open a card in navigation mode or with its mouse toggle to read the reasoning trace.

The live Thinking... card stays open while the model produces reasoning. If you open that card before the reply arrives, Polytoken keeps it open when the live card becomes a settled Thought card. With tui.show_all_thinking_blocks disabled, Polytoken still shows the live card during streaming and removes the completed reasoning after the reply arrives.

Running commands with `/`

Type / as the first character of an empty prompt to open the command palette. A / later in your text is just text, unlike @, which works anywhere.

Some commands run immediately, some open a second menu to pick a value such as a model or a facet, and some take text you type after them:

/model switches the active model; /facet switches the active facet. /theme previews and switches the active theme for the current session. See Themes.
/compact and /clear manage your context. /reset-shell restores the shell environment without clearing context. See Sessions.
/rewind returns the conversation to an earlier point. See Sessions.
/feedback opens a feedback form where you can send a message and optional current TUI-log and screenshot attachments to the Polytoken team. Press Ctrl+Shift+F from the conversation as another way to open it. See Crash Reporting and Feedback.
/permissions changes how Polytoken handles tool approvals. See Permissions. Ctrl+Shift+P opens the permissions typeahead from the prompt without typing the command, even while the model is working on a turn.
/todo and /jobs show your todos and running jobs. See Managing Work.
/mcp enables or disables an MCP server. Type a server name, then choose enable or disable from the typeahead.
/version shows the TUI and daemon build versions.

The full list is in the Command Reference.

Model service tiers

For OpenAI and Codex catalog models, Polytoken accepts service_tier=fast as an alias for service_tier=priority. Use priority in new model selectors. ChatGPT-subscription accounts can route the effective tier server-side, so the provider may report a different tier from the one you requested.

Run /model-option status to inspect request options. When the provider reports a service tier for a request with an explicit tier, the card shows both the requested and reported values.

Running shell commands with `!`

Shell mode lets you run a shell command directly, without writing a prompt for the model. Press ! as the first character of an empty prompt to turn the prompt into a command line. The prompt area takes on a tint and a ! prefix, and a label reads “Shell Mode (invisible to agent)”. Type a command and press Enter to run it. Shift+Enter inserts a line break, so a command can span several lines.

Press ! again while the command line is still empty to switch to shared shell mode, labeled “Shell Mode (visible to agent)” with a stronger tint. A third ! returns the prompt to normal. Esc exits shell mode from either variant and clears the command you typed. Once the command line has text, ! is an ordinary character.

Variant	Press	Who sees the command and output
Local	`!`	Only you.
Shared	`!` twice	You, and the model from your next prompt onward.

Polytoken runs the command in bash in both variants, in the directory the session is working in, with the same shell environment the model’s shell tool uses. You typed the command yourself, so Polytoken skips the permission prompt. Polytoken rejects backgrounding with &.

When the command completes, Polytoken adds a card showing the command, output, exit status, and a ! or !! marker for the variant. The card shows only the tail of long output.

In local mode, the model never sees the command or its output, so a quick check with ! never spends the conversation’s context. The result card stays in your current view; it disappears after you detach and reattach.

In shared mode, Polytoken saves the command and output to the session. The model receives both on its next turn, and Polytoken tells the model not to act on the output unless you ask. Shared mode requires an idle session: while a turn is running, Polytoken reports an error instead of running the command. Prompts you send while a shared command runs enter the queue, and Polytoken delivers them when the command finishes. Local mode works at any time.

Polytoken records shell commands in your prompt history alongside prompts. Press Up to recall one; the prompt switches into shell mode, in the variant the command ran in. Set tui.history.input-history-mode to separated to give shell commands a history of their own. See the configuration reference.

The typeahead bar

The reference picker and the command palette share the same bar above the prompt and the same keys:

Up / Down move through the candidates.
Tab accepts the highlighted candidate without submitting.
Enter accepts and runs a complete slash command or a selected slash argument, such as a facet, model, or permission mode. When the highlighted command still needs an argument, such as /model, Enter inserts the command and opens its argument picker without submitting. In the @ reference picker, Enter accepts the reference without submitting.
Esc dismisses the bar.

The bar labels the keys that apply at each moment, including the file-ignore and reasoning controls when they are relevant.

A facet sets the model’s prompt framing, the tools the model can use, and the accent color of the session. The same prompt (“fix the login bug”) leads to different behavior depending on which facet is active.

Polytoken ships three facets. Plan is for planning out your work. Polytoken withholds the tools that edit files, so the model investigates and asks questions using read-only tools and read-only shell commands. If the model writes a plan, you can review it before it takes effect.

Execute is for getting things done, including following plans made by the plan facet. Polytoken gives the model access to tools for implementation but withholds the tools that write, edit, and hand off plans. The model carries out the plan you approved or follows new instructions.

Orchestrate coordinates complex work through subagents: the model delegates bounded pieces of a task and keeps responsibility for dependencies, verification, and synthesis.

Switch facets with /facet plan or /facet execute. To open the facet picker, press Shift+Tab or click the facet in the status bar. The picker opens whether or not the prompt has text, and Polytoken preserves any draft you have typed: the text returns to the prompt when the switch completes, and Esc cancels the switch and restores the draft without changing facets. The sidebar updates to show the new facet and its color, and the change takes effect on your next prompt.

A facet switch replaces the system prompt, and that replacement carries a cost. Providers that cache prompt prefixes price the cached portion far below fresh input, and a replaced system prompt breaks the match for everything that follows it. The first call after a facet switch therefore incurs the full uncached rate on every input token, unless the provider still holds a live cache entry for the facet you just switched to. The cache rebuilds under the new facet, and later calls return to the cached rate.

The shipped facets select models through the model groups @mg:polytoken:plan_facet, @mg:polytoken:execute_facet, and @mg:polytoken:orchestrate_facet. Switching facets can change your model when the target group resolves to a different model. Configure those groups to use different models for planning, implementation, and orchestration, or to use one model for all three. A facet you write yourself can select a model or model group with polytoken.model. See Facets for custom facets and Sessions for model groups.

Plan mode

Plan mode uses the plan facet when a request needs a handoff to implementation. The model writes a structured handoff plan for the execute facet, then waits for your decision. You can customize the handoff-plan format; see Facets.

At the handoff, Polytoken offers these choices:

Implement plan with a new context. Switch to execute and start fresh. Polytoken clears the planning conversation and carries the plan forward.
Implement plan within current context. Switch to execute and keep the whole conversation, plan and all.
Refuse (Tab to add feedback). Stay in plan. Selecting this choice without feedback cancels the handoff. The model can revise the plan and hand off again.

When daemon.disable_context_clear is true, Polytoken omits the new-context choice.

To refuse, press Tab to enter the feedback text field. Type your feedback, then press Enter to send the feedback to the planner, who can revise the plan for another handoff.

With text in the feedback field, Esc or Ctrl+C clears the text instead of cancelling the handoff. Press either key again to cancel the handoff. The custom answer field in ask_user_question follows the same clear-first rule.

Press Ctrl+Y at the plan review to copy the full plan text to your clipboard.

Choosing Implement plan with a new context clears the conversation with the same operation as /clear; see Sessions. The plan survives the clear.

Moving through the conversation

The conversation above the prompt is a stack of cards. A card is one selectable piece of the conversation: your prompt, a reply, a tool call, a notice. Most cards start collapsed. A tool card expands to show its result; a compaction marker expands to show what it summarized. Your prompts and Polytoken’s replies always show in full.

With the mouse

Scroll to move through the conversation. Scrolling does not interrupt what you are typing.
Click the bottom-row hint to jump back to the latest messages. While the conversation is scrolled back, its bottom row shows a muted hint reading “click to jump to end”. When new messages arrive below your view, the hint switches to “new messages below (click to jump to end)” in a more prominent color. The Jobs viewer’s subagent detail pane shows the same hint.
Single-click a card to expand or collapse it without leaving the prompt.
Double-click a card to enter navigation mode with that card selected.
Click and drag to select text within a card. Release to copy the selection to your clipboard.
Click and drag inside a plan handoff preview or an ask_user_question explanation area to select and copy that text the same way.
Double-click a link to copy it.
Click a labeled link in a terminal that supports OSC 8 hyperlinks (for example Ghostty) to open it. Polytoken marks up labeled Markdown links with standard hyperlink sequences and leaves the decision to your terminal; terminals without support simply show the styled label, and double-click still copies the URL. Links hidden behind a floating window or the Ctrl+R history-search popup are never marked up, so overlay text is never clickable by accident.
Double-click a flagged file in the sidebar to copy its absolute path.

Collapsing the ask_user_question context

When Polytoken asks you a question with a long explanation, you can hide the context to focus on the question and its options. Press the sidebar-toggle binding (default Ctrl+Shift+B) to collapse the context area. The conversation behind the question becomes visible and you can scroll it with the mouse wheel to read earlier messages while deciding. Press the binding again or click the key hint in the top-right corner of the question panel to bring the context back. The same key that toggles the sidebar outside a question is reused here; the sidebar itself is not affected.

When no question in the batch includes an explanation, Polytoken starts the question panel collapsed so the conversation remains visible. Press the same sidebar-toggle binding to expand the context area when you need it.

Press Ctrl+Y while the question panel is open to copy the focused question’s explanation text to your clipboard.

Scrolling the conversation with the keyboard

The conversation window follows the latest messages by default. To scroll back and read earlier history without leaving the prompt, hold Shift with the paging keys:

Shift+PageUp scrolls up one screen.
Shift+PageDown scrolls down one screen.
Shift+Home jumps to the very first messages in the session.
Shift+End jumps back to the latest messages.

After a terminal resize, the scrollbar settles over the next few frames while the conversation layout converges.

These keys work from the prompt, from navigation mode, and while a dismissible overlay like the Jobs or Todos viewer is open. They do not work inside a modal that captures all input, such as the help overlay, an error dialog, or the feedback form.

Without Shift, PageUp, PageDown, Home, and End behave as ordinary text-editing keys in the prompt composer and in multi-line text fields like the feedback form or a custom answer to an ask_user_question question.

When you accept a prompt while scrolled back, the conversation jumps to the latest messages so your input lands in view. Set tui.scroll.preserve-viewport-on-prompt-accept to true to keep the viewport where you scrolled it instead. The setting also covers resuming a goal, and a new-messages hint appears when content arrives below the preserved viewport. The setting applies when the TUI starts, so changing it requires a restart. Inside the region covered by a still-streaming reply, the preserved viewport does not jump, but rows can still shift while that reply grows.

With the keyboard

Press Ctrl+Up to enter navigation mode. Navigation starts on the first card visible in the transcript, or on the newest card when the transcript has not been drawn yet. From there:

Up / Down move between cards; Shift+Up / Shift+Down page through them. The focused card stays in view as you move.
Left / Right collapse and expand the selected card.
Ctrl+Y copies the selected card’s content.
Ctrl+R opens the rewind view for the selected card. For a prompt card, confirming removes the prompt and every card after it, including the assistant response and any tool calls, and the prompt text returns to the input area so you can edit and resubmit. For a compaction or context-clear card, confirming removes that boundary card and every card after it. See Sessions for what rewind can move past.
Esc returns to the prompt. Pressing a printable character returns to the prompt and inserts that character.

To open the rewind picker without entering navigation mode, press Esc twice at the prompt or type /rewind while the session is idle. The picker shows rewind points in conversation order: prompts, compaction summaries, context-clear boundaries, and ask_user_question tool calls. By default, the picker selects the most recent rewind point. Use Up and Down to move between points, then press Enter to select one. In the confirmation dialog, Enter rewinds and Esc returns to the picker. Press Esc again to close the picker without rewinding.

Cancelling a running turn keeps the rewind picker closed until that turn finishes. If a turn starts while the rewind picker is open, Polytoken dismisses the picker automatically.

These keys are the defaults. Action shortcuts like Ctrl+Y (copy card), Ctrl+R (rewind), and Ctrl+Up (enter navigation) can be remapped through tui.keyboard.commands; arrow keys and other structural navigation remain fixed. See the configuration reference.