Working with Solus

Getting Started

Press ⌥Space. The Solus panel appears above whatever you're doing; press it again to dismiss it. That one shortcut is the core habit.

Your first session

• Pick a project. Press ⌘O and choose the directory the agent should work in.
• Pick a permission mode. Press ⌥⇧Tab to cycle: Ask approves each action, Auto runs uninterrupted, Plan drafts a plan for your review first. Start with Ask; use Plan for anything non-trivial.
• Prompt. Type what you want and press Enter. @ autocompletes files; attach files or screenshots from the input bar.
• Watch it work. Tool calls and diff previews stream in. Keep typing. Follow-ups queue for the next turn.

Pill mode vs. editor mode

Two layouts; toggle with ⌥⇧E.

Agents and models

Solus drives the Claude Code and Codex CLIs you already have installed. Cycle the agent with ⌥⇧G, the model with ⌥⇧M, or open the model / reasoning menu with ⌥⇧Z. Each tab can use a different agent and model.

Sessions & Tabs

Each tab is an independent session with its own project, agent, model, and permission mode, so a refactor, a bug fix, and a question can run at once.

• Open and close sessions. ⌘T starts a new session in the current task, ⌘⇧N starts one without a task, and ⌘⇧W closes the current tab.
• Move between tabs. ⌃Tab / ⌃⇧Tab cycle branch tabs; ⌥⇧N / ⌥⇧P move between sessions in a branch.
• Fork a session. Press ⌥F to branch the conversation into a new tab that keeps all context so far. Explore two approaches from one starting state.
• Resume past work. Press ⌘P and pick any previous session; it reopens with its full conversation.
• Queue while busy. Send a message while the agent is working and it runs on the next turn.
• Isolate risky work. Press ⌥⇧B to run the session on an isolated git worktree; switch worktrees with ⌥⇧H.
• Switch branches. Pick a branch in the git dropdown to check it out for the tab. If a worktree already has that branch, Solus takes you there.
• Follow the goal. The project panel shows the session's Goal card: status and progress against a token budget. Codex sessions can edit, pause, or clear it there.
• Ship from the keyboard. ⌥⇧C commits and pushes the session's changes; ⌥⇧. pulls to sync. The Git panel's primary action goes further — branch, commit, push, and pull request in one step. See Opening & Merging Pull Requests.

The input bar does more than text: @ opens file autocomplete, / opens the slash-command menu, ↑ at the start of the input walks your prompt history, and ⌥⇧= expands the input for long prompts.

Switching Agents

A session isn't married to the agent it started on. Press ⌥⇧G to cycle the active agent, or pick one from the agent chip in the input bar — mid-conversation, any time the agent isn't running.

• Before the first message. Switching a session that hasn't started yet just swaps the agent and its default model. There is nothing to hand off.
• Mid-session, it's a handoff. Solus exports the conversation so far — plus the outgoing agent's reasoning, when its provider saves it — and seeds the new agent with the transcript. It reads the history, then answers your next message as the next turn.
• A divider marks the switch. A "Switched to …" line lands in the transcript at the handoff point, and the full history stays readable across segments.
• Each agent keeps its thread. Every agent holds its own provider thread. Switch back to one you used earlier in the session and Solus restores that thread instead of starting cold.
• The model follows the agent. The session takes the new agent's default model; change it with ⌥⇧M or ⌥⇧Z.
• Busy sessions wait. You can't switch while the agent is working — stop it (⌃C) or let the turn finish first.

Switching the agent on one session never changes other sessions — it only becomes the default for new ones.

Delegated Agents

Ask your agent to delegate ("review this with a second agent", "search the repo with a subagent") and it hands the work off. The exchange lands in the transcript as a card you can follow, answer, and open.

Two ways to delegate

The exchange card

• One card per exchange. A delegating turn shows one card with the other agent, its status, and elapsed time. Several agents dispatched in one turn share the card.
• Follow along. The dialogue streams into the card live.
• Reply directly. The field at the bottom of the card messages that agent's session without adding a turn to yours.
• Answer a blocked agent. If it stops to ask something, the card asks you in place, and answering unblocks it.
• Open the session. Click Open session to take over the peer session in a tab of your own.
• Unattended by design. Delegated runs never enter plan mode and never stall on permission prompts. They finish with the scope they were given.

Delegation is the agent's call. Ask for it in your prompt ("review this with a second agent", "search the repo with a subagent") and it uses the tools it has.

Working with Plans

For anything bigger than a one-liner, make the agent show its approach before any code changes. You mark the plan up like a PR review, so course-corrections happen before the work, not after.

• Enter Plan mode. Press ⌥⇧Tab until the permission mode reads Plan, then send your prompt.
• Read the plan. When the agent is ready, it opens the plan full-screen as Markdown.
• Comment. Select any text to attach an inline comment to that section, or add a top-level comment for the whole plan.
• Approve or reject. Approve into Ask (⌥Y) or Auto (⌥A) mode. Your comments travel with the approval. Reject (⌥R) to stop the agent and redirect it.

Keeping plans around

• Pin or bookmark. Pin a plan (⌥P in the workspace) to keep it on top, or bookmark it (⌥B) to revisit later.
• Revisions. Updated plans keep their previous versions. Compare or revert from the revision dropdown.
• Any model. Plan mode works with every model; Solus handles the orchestration.

Plans are saved to disk as Markdown. Press ⌥⇧L to open the workspace and browse plans across sessions.

Rate Limit Queueing

When a session hits an API rate limit, Solus keeps your work. Set the default under Settings → Rate limit behavior, or override it per tab:

Knowing how much is left

The project panel (⌥M) shows a quota meter for every signed-in agent: how much of the Session and Weekly windows remain, with a countdown to each refill.

Workspace Panes

In editor mode, plans, Works, diffs, reviews, and documents open as panes over or beside the conversation, so you read them without losing your place.

How panes behave

• Focus or split. Press ⌥⇧\ (or use the pane header action) to move a plan, Work, automation, or review between the focused primary pane and the split side pane.
• Diffs and files. ⌥⇧D opens the diff, ⌥⇧O the files pane, ⌥⇧F changed files, each beside the conversation so you can inspect code and keep prompting.
• PR review. A pull request opens with the review maximized; use the Chat control to reveal the conversation beside Activity, Guide, and Diff.
• One commit at a time. Click a commit in the Activity timeline and the Diff narrows to that commit's own changes. A band names the commit and takes you back to all changes. Inline comments are off while one commit is in view, because comment anchors belong to the full diff.
• State stays put. Closing a pane restores the conversation with scroll position and drafts intact.

Diff Panel

When the agent says it's done, verify it. Press ⌥⇧D in editor mode to see every file the session touched.

How it works

• Navigate files. ⌥N / ⌥P step through changed files, ⌥F searches, or click a file in the list.
• Filter by turn. Select a turn in the conversation, or press ⌥→ / ⌥← to move through turns.
• Leave comments. Press ⌥C to start an inline comment on the current line.
• Send feedback. Write a general note in the feedback box, then press ⌥↵. Your line comments and note land in the conversation as one message.

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

Opening Changed Files

Every edit shows an inline diff preview in the conversation. With a default editor set in Settings, each preview gets an Open button that jumps to that file in your editor. Press ⌥⇧F to open every changed file at once.

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

Review Companion

Before you commit or open a PR, have a second agent review the branch (commits, uncommitted edits, and untracked files) and write an inline report of findings.

How to use it

• Open the project panel. Press ⌥M in editor mode and find the Git section.
• Generate a review. Click Review changes. The review runs in the background while you keep working.
• Open the report. When ready, the button becomes View report.
• Jump to a finding. Click any finding to focus that exact file and line in the diff beside it.
• Regenerate. After more changes, click the refresh button in the companion header.

Pick the reviewing agent and model under Settings → Review companion; it defaults to your active agent and its default model.

Opening & Merging Pull Requests

Open a pull request and merge it without opening GitHub:

Publishing the work

The Git section of the project panel (⌥M) shows one primary action that reads your branch state and runs every step it needs:

• On the default branch. Uncommitted work becomes a feature branch first, then a commit, a push, and a pull request.
• On a feature branch. Commit, push and open PR, or just Commit and push once the pull request exists.
• Nothing to commit. Unpushed commits push and open the pull request; a published one opens directly.
• Behind the upstream. Sync first (⌥⇧.) — the action waits until the branch is up to date.
• Messages are written for you. The commit message, the branch name, and the pull-request title and description come from the change itself: commit subjects, diff statistics, and the repository pull-request template when there is one. If generation fails, Solus falls back to a plain draft from the same context.

⌥⇧C still commits and pushes directly. Writing style, template handling, and the model that writes them live under Settings → Source Control.

Merging

• Open the PR. Open the Pull Requests page from the sidebar and select the PR.
• Check readiness. The review surface shows status, required checks, reviewers, and unresolved conversations.
• Merge. Pick Merge commit, Squash, or Rebase and confirm. Branch-protection refusals are reported in place.

Resolving conflicts

If the PR conflicts with its base branch, choose Resolve conflicts: Solus checks the PR out into an isolated worktree and opens an agent session on the conflicted files. The agent resolves, commits, and pushes. Then merge normally.

Works

Ask for a design doc, a migration guide, or a slide draft and Solus saves it as an editable Work instead of a long Markdown block in the chat. Works outlive the session that created them.

• Open the workspace. Press ⌥⇧L or click Folio in the sidebar — plans, documents, and diagrams in one searchable gallery.
• Edit in place. Open a Work to edit it in the Document Editor; saving updates the stored Work.
• Copy or reuse. Press ⌥C while a Work is open to copy its Markdown.
• Storage. Works are stored locally under your Solus data directory. Documents are fully editable; slides are tracked so the app can surface and expand them.

Work modal

These shortcuts are active while a Work is open. The workspace itself has its own set — see Keybindings → Workspace.

Document Editor

Works, prompts, and notes are edited in the Document Editor. It renders Markdown natively; toggle the raw Markdown view with the Markdown button in the top-right corner.

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.

Design Mode

"The button is misaligned" is a paragraph in text and two seconds with an arrow. Screenshot any window, draw on it, and send the image to your agent:

How to use it

• Take a screenshot. Press ⌥⇧S or click the camera icon in the input bar. Solus captures the active window and opens the annotation overlay.
• Annotate. Draw with the left-side toolbar, then confirm. The image lands as an attachment in the input bar.
• Send. Add any extra context and press Enter. The agent receives the annotated screenshot and your message.

Annotation tools

Keyboard shortcuts (annotation overlay)

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

Voice Input: Mic vs Voice Mode

Two voice input modes; both transcribe locally with Whisper, so audio never leaves your machine.

Automations

An automation is a saved prompt that runs on a schedule or on demand: a daily TODO sweep, a nightly dependency check. Press ⌥⇧V to open the Automations page, then ⌥N to create one: write the prompt, pick the agent and model, choose a trigger, and save.

What each automation captures

• Prompt. The instruction the agent runs each time.
• Agent & model. Which agent, model, and reasoning effort. Runs execute headless in Auto permission mode.
• Working directory. Defaults to your active project.
• Max turns. An optional cap per run, as a guardrail.
• Enabled / paused. 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, regardless of schedule.
• Run history. Each automation logs past runs with status, tool-call count, and output or error.
• Open a run. Open a completed run as a full session to see exactly what the agent did.
• Created by agents. Agents can create, edit, and trigger automations for you; theirs are tagged in the list.

Tasks

A task board in the project panel: track work as local tickets or synced GitHub Issues, and start agent sessions straight from a task so the ticket context travels with the work.

• Local tickets and GitHub Issues. Keep lightweight local tickets, or connect a repository to sync GitHub Issues into the same board. Status flows both ways.
• Planning fields. Epics, priorities, labels, due dates, and threaded comments.
• Start a session from a task. The ticket body and comments ride along as context.
• Linked work. Sessions, pull requests, plans, and works stay linked to the task, so the board shows where everything stands.

Hosts & Connections

Any browser on your network can pick up your sessions, and other machines running the Solus server become hosts you can run sessions on, all driven from the same window.

The web UI

With Solus running, open port 3000 (override with SOLUS_PORT) from your phone, tablet, or another computer. The first visit shows the pairing screen.

Every address Solus is reachable from (localhost, LAN, Tailscale / VPN) is listed in Settings → Connections.

Pairing a device

• Generate a pair code. In Settings → Connections, click Generate pair code. You get a 6-digit code plus pairing links, expiring after 5 minutes.
• Connect from the browser. Open a pairing link on the device (AirDrop, Messages, etc.) and the address and token are read from the URL. Or use Manual setup and enter the address and code.
• Name the device. Optional; defaults to your browser and OS.
• Stay paired. The browser keeps a long-lived token and reconnects on every later visit until you revoke it.

The web UI reconnects automatically after sleep or network changes, supports web push notifications on capable browsers, and always opens links on the device you're holding, never on the remote machine.

Adding a host

A host is any other machine running the Solus server. Add one from the host directory:

• Pair over SSH. Point Solus at user@host and it connects, installs the Solus server, and pairs automatically. No SSH? Enter the server's address and pair code by hand.
• Pair with a server. A server you installed yourself prints a pair link and code at startup. Run solus pair to create another link and QR for any client.
• Automatic setup. Once paired, Solus provisions git credentials from your GitHub connection, installs the agent CLIs, and walks you through signing into them.
• Readiness at a glance. The host directory shows what's installed and signed in, with one-click repairs for anything missing.

Run on: choosing where a session runs

Every new session has a Run on picker in its header. Pick any host before the session starts; Solus remembers the choice per repository.

Running on another host is a dispatch. It carries the repository, not your working tree:

• A fresh checkout, every time. The host clones or syncs from the git remote and cuts a fresh worktree from the default branch.
• Uncommitted changes stay put. Unpushed edits don't travel. Commit and push first if you want them there.
• Always isolated. A dispatched session always runs in its own worktree.
• Work comes back as a PR. Commit → push → pull request, same as local work.
• Needs a git remote. No remote, nothing to clone. Open the folder directly on that host instead.

You can also open a project that already lives on a host from the open-project dialog; it behaves like a local one. Once a session has started, its host is fixed.

Managing devices

• Connected devices. The Connections panel lists every paired device with its label and last-connected time.
• Revoke access. Revoking a device invalidates its token immediately; it must re-pair to reconnect.
• Multiple servers. The web app remembers every server you've paired with; remove one with its ✕.

Network & security

• Local only. Traffic stays on your network. Nothing routes through external servers.
• Session tokens. Each device holds its own token; revoking one affects nothing else.
• Tailscale / VPN. Use a Tailscale pairing link to reach your desktop from outside your LAN.
• Loopback (same machine). http://localhost:3000 skips pairing in development mode only; production builds always pair.

Self-hosted server

Run the standalone server on any macOS or Linux box and reach it entirely from the browser. Install through Homebrew:

• Manage from the CLI. solus start, solus logs, and solus update run, tail, and upgrade the daemon. Data lives under ~/.solus.
• Pair every client. solus pair prints a one-time link, code, and QR. Run it again for each additional client.
• Stays updated. Upgrade with brew upgrade solus, or solus update for tarball installs.

Settings

Open Settings with ⌘,. All preferences are stored locally on your machine.

Display

Agent & workflow

Text generation

These are host settings: a remote client uses the models installed on the host the session runs on.

Source control

Review companion

Input

Tools

Settings are persisted to disk and apply immediately. No restart required.