Solus Reference

Keybindings

Global

These work system-wide, even when Solus is hidden.

General

Tabs

View

Compose

Agent

Navigation

Voice

Voice Mode (continuous, hands-free) is enabled in Settings → Input.

Automations

Open the Automations page with ⌥⇧V. These shortcuts are active while it's open.

Tasks

Open the Tasks page with ⌥⇧T. These shortcuts are active while it's open.

Git

Input & menus

Plan modal

These shortcuts are active while a plan is open.

Plans gallery

These shortcuts are active while the plans gallery is open (⌥⇧L).

Diff panel

These shortcuts are active while the diff panel is open.

Works

Works are long-form artifacts created by your agents, including documents and slide drafts. When an assistant returns a fenced document artifact, Solus extracts it from the chat, saves it to disk, and shows it as an editable Work instead of leaving a long Markdown block in the conversation.

• Open the gallery. Press ⌥⇧; or click Folio in the sidebar to search every saved Work.
• Edit in place. Open a Work to make changes in the Document Editor. Saving updates the stored Work and preserves the conversation reference.
• Copy or reuse. Use ⌥C while a Work is open to copy its Markdown content back to the clipboard.
• Storage. Works are stored locally under your Solus data directory, with a manifest plus one content file per Work.
• Supported types. Documents are fully editable today. Slide artifacts are tracked as Works so they can be surfaced and expanded by the app.

Works gallery

These shortcuts are active while the Works gallery is open (⌥⇧;).

Work modal

These shortcuts are active while a Work is open.

Document Editor

The Document Editor is a rich-text Markdown editor for writing structured prompts, plans, and notes. It renders Markdown natively and syncs bidirectionally with raw Markdown — toggle between views using the Markdown button in the top-right corner of the editor.

Formatting toolbar

Select any text to reveal an inline bubble menu with the following actions:

Slash commands

Type / at the start of a line to open the block-type menu. Continue typing to filter.

Editor shortcuts

These shortcuts are active when focus is inside the Document Editor.

Working with Plans

Plan mode is a permission workflow where your agent drafts a full plan before taking any action. Use it when you want to review and guide its approach before it touches your code.

• Enable by selecting Plan as the permission mode on a tab, or press ⌥⇧Tab to cycle through modes.
• When your agent is ready, it opens a full-screen plan view rendered as Markdown.
• Inline comments. Select any text in the plan to attach a comment to that specific section. Comments are included when you approve.
• General feedback. Add a top-level comment that applies to the whole plan.
• Approve. Choose whether your agent should continue in Ask or Auto mode, then confirm. It proceeds with your feedback incorporated.
• Reject. The agent stops — redirect it with a new prompt.
• Pin. Pin a plan to keep it at the top of the plans gallery for quick reference.
• Save for later. Bookmark a plan without pinning it — useful for plans you want to revisit.
• Revisions. When your agent updates a plan, previous versions are preserved. Use the revision dropdown in the plan view to compare or revert.
• Any model. Plans work with every model, not just those that natively support plan mode. Solus handles the orchestration so you can review and approve plans regardless of which AI model powers the session.

Plans are written to disk as Markdown files so you can reference them later. Open the plans gallery with ⌥⇧L to search and browse all plans across sessions.

Diff Panel

The diff panel shows every file your agent has touched in the current session. Open it with ⌥⇧D (editor mode) to review changes file by file, leave line-level comments, and send consolidated feedback back without switching context.

How it works

• Open the panel. Press ⌥⇧D in editor mode, or click the diff button in the editor toolbar.
• Navigate files. Use ⌥⇧F and ⌥⇧B to step through each changed file, search files with ⌥F, or click a file in the file list.
• Filter by turn. Select a specific turn in the conversation, or press ⌥⇧→ and ⌥⇧← to move through turns.
• Leave comments. Press ⌥⇧C to start an inline comment on the current line. Comments are attached to the specific file and line range.
• Send feedback. Add a general comment in the feedback box and press ⌥⇧↵ from anywhere in the panel, or ⌘↵ while focused in the feedback box.

See the Keybindings → Diff panel section for the full list of shortcuts.

Review Companion

The Review Companion turns a second agent loose on your branch. It reviews everything that changed — commits on the branch, uncommitted edits, and untracked files — and writes an inline report of grouped findings. Each finding links directly to the relevant hunk, so a click jumps you to that file and line in the diff. It's a fast second opinion before you commit or open a PR.

How to use it

• Open the project panel. In editor mode, open the project panel with ⌥M and find the Git section.
• Generate a review. Click Review changes. The review agent analyzes the branch diff and builds the report — this runs in the background while you keep working.
• Open the report. Once it's ready the button becomes View report. Click it to open the companion in the main pane.
• Jump to a finding. Click any finding in the report to focus that exact file and line in the diff / preview pane alongside it.
• Regenerate. After more changes, use the refresh button in the companion header (or Review changes again) to produce an up-to-date report.

Choose which agent and model write the review under Settings → Review companion. By default it follows your active agent and that agent's default model.

Design Mode

Design Mode lets you take a screenshot of any window, annotate it with drawing tools, and send the annotated image directly to your agent — all without leaving Solus. It's the fastest way to describe a UI bug, highlight a layout issue, or point your agent at exactly what needs changing.

How to use it

• Trigger a screenshot. Press ⌥⇧S or click the camera icon in the input bar. Solus captures the active window and opens the annotation overlay full-screen.
• Annotate. Use the left-side toolbar to draw on the screenshot. Confirm when done — the annotated image is added as an attachment in the input bar.
• Send to agent. Add any additional context in the input bar and press Enter. Your agent receives both the annotated screenshot and your message.

Annotation tools

Keyboard shortcuts (annotation overlay)

The annotated image is composited at full screenshot resolution before being sent — annotations are baked into the image your agent receives.

Voice Input: Mic vs Voice Mode

Solus has two voice input modes. Both transcribe locally using Whisper — audio never leaves your machine.

Automations

An automation is a saved prompt that runs on a schedule or on demand. Use it for recurring work — a daily TODO sweep, a nightly dependency check, a weekly changelog draft — and let the agent do it unattended. Open the Automations page with ⌥⇧V or the Automations entry in the sidebar; press ⌥N to create one.

What each automation captures

• Prompt. The instruction submitted to the agent on every run.
• Agent & model. Which CLI agent runs it (Claude or Codex), the model, and the reasoning effort. Each run executes headless in Auto permission mode.
• Working directory. The project directory the run executes in — defaults to your active project.
• Max turns. An optional cap on how many turns a single run may take, as a guardrail.
• Enabled / paused. Toggle an automation on or off without deleting it. Paused automations never fire on schedule.

Triggers

Scheduled triggers fire only while Solus is open — they don't run in the background when the app is quit.

Running & history

• Run now. Trigger any enabled automation immediately to test it, regardless of its schedule.
• Run history. Each automation keeps a log of past runs with status (running, succeeded, failed), tool-call count, and output or error.
• Open a run. Open a completed run as a full session to inspect exactly what the agent did.
• Created by agents. Agents can create, edit, and trigger automations for you with their built-in automation tools. Agent-created automations are tagged in the list.

Tasks

Tasks are project-scoped tickets you can browse, create, and start agent sessions from without leaving Solus. Open the Tasks page with ⌥⇧T, from the command palette, or from the task glance on the home screen.

Providers

• Local. The built-in local task list stores tasks per project on your Mac. It supports tasks, epics, sub-tasks, priority, due dates, comments, PR links, and deletes with undo.
• GitHub Issues. Projects can read and update GitHub Issues from their repository remote. Create issues, change status, post comments, and open the source ticket from Solus.
• Project settings. Choose the provider per project in Settings. If a GitHub-backed project needs authentication, the Tasks page offers a direct connection prompt.

Working from a task

• List or board. Use the dense list for grouped tasks and local epics, or switch to the board view to move tasks between Open, In progress, and Done.
• Search and sort. Filter by status, search across task text, scope to work assigned to you, and sort by recent updates, priority, or due date.
• Start a session. Start from any task to open a new tab in that project with the task attached. The first message includes the hydrated ticket context for the agent.
• Resume work. When a session is linked to a task, the task card shows a back-link so you can jump back into the most recent session for that task.
• Capture outcomes. Task details can track the branch and PR that came out of the work, so the ticket stays connected to the implementation.

See the Keybindings → Tasks section for task navigation shortcuts.

Opening Changed Files

Whenever your agent edits or writes a file, a diff preview appears inline in the conversation. If you have a default editor configured in Settings, an Open button appears on each tool result — click it to jump directly to that file in your editor.

To open every file changed in the current session at once, press ⌥⇧F.

Supported editors (auto-detected at launch): VS Code, vim, nvim, helix. Set your preferred editor in Settings.

Rate Limit Queueing

When your AI coding assistant hits an API rate limit, Solus handles it so you don't lose your work. Four behaviors are available, configurable globally in Settings or per-tab at any time:

The global default is set in Settings under Rate limit behavior. Individual tabs can override this independently.

Connections & Web UI

The Solus desktop app doubles as a local server that serves a full web interface. Any browser on your network — phone, tablet, or another computer — can connect and interact with your desktop agent in real time. A one-time pairing step issues a session token; after that, subsequent visits reconnect automatically.

How it works

When Solus is running it listens on port 3000 by default (override with the SOLUS_PORT env var). The web UI is served at that address — navigate to it from any device on your network and you'll see the pairing screen on the first visit.

The exact addresses Solus is reachable from are listed in Settings → Connections — including localhost, LAN, and any Tailscale / VPN addresses.

Step 1 — Generate a pair code (desktop)

• Open Connections. Go to Settings → Connections in the Solus desktop app.
• Generate a pair code. Click Generate pair code. A 6-digit code appears alongside a set of pairing links — one per network interface the server is reachable from. Codes expire after 5 minutes.
• Share with the device. Copy a pairing link and send it to the device (AirDrop, Messages, etc.), or have the 6-digit code ready for manual entry.

Step 2 — Connect from the browser

Navigate to the Solus server address in your browser. On the first visit you'll see the pairing screen. There are two ways to pair:

Either way, you can optionally set a device name — it defaults to your browser and OS (e.g. "Safari on macOS") and appears in the desktop app's connected-devices list so you know what's connected.

After pairing, the browser receives a long-lived session token that is stored locally. On every subsequent visit the web app reconnects automatically — no re-pairing needed unless you revoke the device from the desktop app.

Reconnection & reliability

The web UI maintains a WebSocket connection to the desktop server and retries automatically if it drops — waking from sleep, switching networks, or a momentary blip all recover without any manual action. A connection status indicator appears while reconnecting.

Managing devices

• Connected devices. The desktop Connections panel shows every paired device with its label and last-connected time.
• Revoke access. Click the revoke button next to a device to invalidate its session token immediately. The browser is disconnected and must re-pair to reconnect.
• Multiple servers. The web app remembers every server you've paired with. On subsequent visits, choose from your saved server list or add another one. Hit the ✕ on a server to remove it.

Network & security

• Local only. All traffic between the browser and Solus travels over your local network — nothing is routed through external servers.
• Session tokens. Each paired device holds a unique session token. Revoking one device has no effect on any other.
• Tailscale / VPN. Solus advertises all reachable addresses, including Tailscale IPs. Use a Tailscale pairing link to securely reach your desktop from outside your LAN.
• Loopback (same machine). Navigating to http://localhost:3000 in a browser on the same Mac connects without pairing in development mode. In production builds, the normal pairing flow applies even on loopback.