Coding agents

You can always run an agent CLI by hand in a terminal, and for a quick one-off that is often the right thing. When Deska starts the same CLI as a structured session it speaks the tool’s own protocol instead of reading its screen output, and that buys four things:

• Streamed events instead of scraped text. Messages, tool calls, plan updates, delegated subtasks and provider notices arrive as separate items, so the transcript can render each one properly rather than as a wall of terminal output.
• Approvals and questions as interface cards. A permission request pauses the turn and shows a card you answer with a key or a click, in the panel or on your phone, rather than a prompt buried in scrollback that only the focused terminal can answer.
• Conversations that survive a restart. Deska records a resume cursor for every session, so reopening the app and sending the next message reopens the same provider conversation with its context intact. A turn that was in flight when the app closed is reported as failed rather than silently replayed, because re-running side effects you never re-issued would be worse than saying so.
• Real token accounting. Input, output and cached tokens are folded per thread, with a context ring shown only when the provider actually reported its window size.

Structured sessions are what the Inbox board supervises. See Agent threads for the board itself, and Agents & Dex for the canvas-aware chat.

The runtime mode is the single most important setting on an agent: it decides how much the agent may do without asking you. Deska maps your choice onto each provider’s own permission and sandbox policy at session start, so most prompts never happen at all and the ones that remain arrive as approval cards.

• Approval required runs the agent in a read-only sandbox. It can read and reason, and every command or edit comes back to you first. Use it on an unfamiliar repository, or when you want to watch an agent think before it touches anything.
• Auto-accept edits is the default. The agent may write inside the workspace it was started in without asking each time, and anything reaching outside that boundary still needs your approval.
• Auto (AI reviews risky actions) keeps the same workspace boundary but routes risky-action approvals to a reviewing model instead of to you. Not every provider has a reviewer; where none exists the session behaves as auto-accept edits rather than pretending to review.
• Full access removes the sandbox entirely. Nothing is confined to the workspace and nothing pauses for approval.

You pick the mode when you create a thread and can change it mid-conversation from the composer footer. Modes that the current provider and model provably cannot honour are shown disabled rather than silently ignored.

One machine often has more than one way to run the same agent: a work account and a personal one, a stable install and a nightly build. A provider instance is a named setup you define once and then pick per thread. Manage them under Settings → Coding agents → Instances, a page of its own under AI capabilities.

Instances matter for one more reason, and it is the headline one: they are also the engine behind Dex. The assistant does not run on a Deska-managed model; it runs on one of these same instances, and the one you pick under Settings → Dex, in the Who answers section, is the agent that answers every question you type or speak.

If the one you picked is not installed on this computer, or nobody ever signed into it, Dex tries the next instance you have rather than failing on the first. When none of them can answer, the reply says which agent it needed and whether it wants an install or a sign in, with a button that takes you straight to the page that fixes it.

Each instance can carry its own:

• Binary path, when the CLI is not the one first on your PATH.
• Home directory, which is how two instances of the same provider stay signed in to different accounts. Deska maps it to the provider’s own config directory variable.
• Default model, default runtime mode and, where the provider supports it, a default reasoning effort.
• Extra command-line arguments for provider flags Deska does not model, appended verbatim when the session starts.
• An accent color, purely so its threads are recognisable at a glance on the board.

Values resolve from most specific to least: what a thread pins, then the project default, then the instance default, then the provider’s own. Deska also probes each instance’s credential store cheaply and badges the ones that look signed out, so a thread that is about to fail on authentication says so before you send a message.

Plan mode changes what a turn produces rather than what it is allowed to do. Press ShiftTab in the composer to arm the next turn as planning, and a PLAN MODE badge appears. That turn researches the codebase read-only and comes back with a proposed plan instead of editing files, whatever runtime mode the session is in.

Each provider does this its own way, through its native planning permission mode, a read-only per-turn policy, or a built-in planning agent, so you get the same behaviour across all three. The result lands as a Proposed plan card in the thread, where Implement sends the plan back for execution, Refine prefills a follow-up asking for changes, and Implement in new worktree thread starts a sibling thread in its own checkout so planning and execution never share a working tree.

Deska does not ship a hardcoded model list for these agents. It asks each installed CLI for its own catalog over the protocol the CLI already speaks, then shuts that probe down. You get the models your install and your account actually have, including ones released after your copy of Deska. Discovery runs on demand from settings, is time-bounded, and its results are cached, so nothing waits on it during normal work.

Sessions also pick up what the CLI advertises about itself. Slash commands the provider exposes become available in the composer (Codex lists its own skills behind $ as well), and providers with named agents or personas expose those too. Changing the model on a thread is safe at any time: with nothing running it applies the next time the thread starts, and mid-conversation it applies from the next turn, never disturbing a turn already in flight.

An agent CLI left running holds real resources: a process, sometimes a local server and a port. A session with no active turn and no pending approval or question for thirty minutes has its provider process stopped. Nothing about the conversation is lost. The session keeps its identity, and your next message transparently restarts the provider from the resume cursor and carries on where it left off. The only thing you notice is that the first message after a long pause takes a moment longer to start.

When a session cannot start or dies, Deska names the cause rather than showing a raw stack: the CLI could not be launched, you need to sign in to that provider, the installed CLI is too old, the provider answered unexpectedly, the process is gone, or it stopped responding. Failures with no recognisable cause show their message unchanged instead of being labelled with a cause nobody established. Troubleshooting covers what to do about each one.