Solus Reference

Keybindings

Global

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

General

Tabs

View

Compose

Agent

Navigation

Voice

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.

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.

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.

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.