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.

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.

The prompt accepts mouse input. Single-click inside the prompt to place the cursor where you clicked. A click beyond a row’s visible text moves the cursor to the end of that row. A click below the prompt text moves the cursor to 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.

The prompt copy shortcut and the navigation card copy shortcut both default to Ctrl+Y, but they are independent commands. One acts in the prompt, the other acts in navigation mode, and you can set them to different chords.

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 terminal input from the handoff. The quiet window lasts roughly 10 to 50 milliseconds, depending on when the terminal finishes delivering stale input. Normal TUI input resumes after that window.

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

Prompts you send while Polytoken is working go into a queue, and Polytoken delivers queued prompts on the next turn. While the queue holds messages, Polytoken shows the next one (the first message you queued, which Polytoken delivers next) as a single dimmed line just above the prompt, separated from the conversation by one blank line. Polytoken cuts a long message short with an ellipsis, and when more messages wait behind it, Polytoken appends (+N) to show the count. Press Up from the first line of the prompt to load the newest queued prompt into the editor. Polytoken saves the draft text and pending images that the queued prompt replaces. Press Down at the fresh prompt boundary to restore the saved draft once. 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 remains an explicit-consent path 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.

Project file references use the project-relative path and show every file in the project tree, filtered as you type. Polytoken ranks query matches before it limits the picker list, so the best-ranked matches survive the server-side cap. The picker then orders the surviving candidates with its client-side fuzzy matcher. When Polytoken caps the matching list, 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.

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. Keep typing path components to drill in: @../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. The same ignore rules apply in browsed directories: hidden files and .gitignore matches are hidden by default, and Shift+Tab reveals them. An exactly typed external reference keeps the existing symlink-following behavior. A fold-matched external symlink candidate is rejected for safety.

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 turns off those ignore rules. When it is on, hidden files and the project’s Polytoken directory appear in the picker alongside everything .gitignore would normally hide. Version-control metadata directories such as .git stay hidden, since referencing their internals is never useful.
[ 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 tool approvals are handled. 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 to the conversation with the command, its output, its exit status, and a ! or !! marker for the variant. Long output keeps only its tail.

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 one. For slash commands and slash arguments (facets, models, permissions), Enter accepts the selection and submits the prompt in a single press. For the file reference (@) picker and for commands that need further input (like /model), Enter accepts the selection 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. The model has access to every tool and 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, or press Shift+Tab (or click the facet in the status bar) to open the facet picker. 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 pin no model, so switching among them never changes your model: you can plan, execute, and orchestrate on different models, or hold one model across all three. A facet you write yourself can pin a model with polytoken.model, and switching to that facet switches the model too. To write your own facets, see Facets in Harness Engineering.

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 you get three choices plus a refuse field:

Implement in a new context. Switch to execute and start fresh. Polytoken clears the planning conversation and carries the plan forward.
Implement in the current context. Switch to execute and keep the whole conversation, plan and all.
Cancel. Stay in plan. The model can revise the plan and hand off again.
Refuse (Tab to add feedback). Stay in plan. The model can revise the plan and hand off again. Press Tab to enter a feedback text field where you can type refusal feedback that gets sent back to the planner.

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

If you have text in the feedback field and press Esc or Ctrl+C, the text clears instead of cancelling. Press Esc or Ctrl+C again to cancel the handoff normally. This is the same clear-first rule the custom answer field in ask-user-question uses.

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

The first choice 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.
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.
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.

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.

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 rewind without entering navigation mode, press Esc twice at the prompt when no turn is running. Cancellation also keeps the picker closed until the cancelled turn finishes. If a turn starts while the picker is open, Polytoken dismisses the picker automatically. You can also type /rewind when the session is idle to open the same picker. The picker shows every rewind point in conversation order: prompts, compaction summaries, context-clear boundaries, and ask_user_question tool calls. Use Up and Down to move through them, then press Enter to select a point. In the confirmation dialog, Enter rewinds and Esc returns to the picker. Press Esc again to close the picker without rewinding. The most recent rewind point is selected by default.

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.