Why Solus
Coding agents live in the terminal, and the terminal is a bad place to supervise them. You lose the thread when you switch windows, plans and diffs scroll away, and running two agents at once means juggling panes.
Solus puts agents in a focused workspace above whatever you are doing. Sessions are tabs, plans are reviewable documents, diffs are commentable, and everything has a keybinding. Show it with ⌥Space, then hide it when you are back in flow.
Features
A typical loop: summon Solus, describe the change, review the plan it drafts, watch the diff as it works, send line-level feedback, then commit and merge — without leaving the panel. The features below follow that loop in order, and each links to its section in the docs.
| |
|---|
| Sessions & tabs | Every tab is an independent session with its own project, agent, model, and permission mode. Fork a conversation to explore two approaches, resume any past session, queue messages while the agent is busy, or isolate risky work on a git worktree. |
| Plans | In Plan mode the agent drafts before it executes. Mark the plan up like a PR — inline comments on any selection — then approve into Ask or Auto mode. Plans are saved to disk with revision history, and work with every model, not just those with native plan support. |
| Workspace panes | Plans, Works, automations, reviews, and diffs open as focused panes or beside the live conversation. Closing a pane restores the chat with scroll position and drafts intact. |
| Diff panel | Every file the agent touched, in a side panel. Step through files, filter by conversation turn, leave line-level comments, and send them back as one structured message. |
| Opening changed files | Jump from any inline diff preview straight into VS Code, Cursor, Zed, Sublime Text, a JetBrains IDE, or a terminal editor like Vim, Neovim, Helix, or Emacs — or open every file changed in the session at once. |
| Review companion | A second agent reviews your branch — commits, uncommitted edits, and untracked files — and writes a report of grouped findings. Click a finding to land on that exact hunk. |
| Pull requests | One action branches, commits, pushes, and opens the PR — commit message, branch name, title, and description written from the change itself. Then merge, squash, or rebase from its review surface, with status, checks, required approvals, and unresolved conversations in view; open a single commit's changes from the Activity timeline. The status card names the first blocker and offers the one action that clears it: conflicted PRs are handed to an agent in an isolated worktree, and failing checks or an out-of-date branch open a drafted agent session for the branch. |
| Works | Docs, slides, and diagrams the agent produces are extracted from the chat and saved as standalone artifacts you can search, edit, and export — they outlive the session that made them. |
| Document editor | Native Markdown editing with a selection toolbar, slash commands for block types, and bidirectional raw-Markdown sync. |
| Voice input | Push-to-talk or a continuous hands-free loop, both transcribed locally on your device — audio never leaves your machine. |
| Automations | Save a prompt and run it on a schedule — interval, daily, weekly, monthly, or raw cron — or on demand. Every run keeps a history you can open as a full session. Agents can create automations for you. |
| Rate limit queueing | Hit a limit mid-task and Solus asks, queues and re-sends, continues, or stops — globally or per tab. |
| Hosts & connections | The desktop app doubles as a server: pair your phone or another browser, add other machines as hosts, and choose where each session runs. |
| Tasks | A project-scoped board of local tickets and GitHub Issues, with sessions started straight from a task. |
Install
Homebrew — recommended, and it keeps itself current:
brew install --cask Ashton-Sidhu/tap/solus # macOS desktop app
Direct download — a signed and notarized .dmg from solus.sh, or from the releases page. Drag Solus.app to /Applications. The app updates itself in place from there.
Then press ⌥Space to summon the window (⌘⇧K if that's taken), pick a project with ⌘O, and start typing.
Requirements
| |
|---|
| OS | macOS 12 Monterey or later, Apple Silicon |
| Agent | Claude Code CLI, installed and authenticated |
| Optional | Codex CLI, for Codex sessions |
Solus drives the agent CLIs you already have installed and auto-detects which are available — it doesn't ship its own agent or ask for an API key.
Keyboard shortcuts
Global shortcuts use ⌥⇧, sub-page shortcuts use ⌥. These are the ones worth learning first — the full reference lives in the keybindings docs, or press ⌥⇧/ in the app.
| Shortcut | Action |
|---|
⌥Space | Toggle the window (system-wide) |
⌥L | Focus input |
⌘O | Open a project on the current host |
⌘⇧O | Open or clone a project on any host |
⌘T | New tab |
⌥⇧Tab | Cycle permission mode (Ask → Auto → Plan) |
⌥⇧D | Toggle diff panel |
⌥⇧B | Toggle worktree mode |
Headless server
Run Solus on Linux x64/arm64 or an Apple Silicon Mac. The server includes Node,
the CLI, and the web client. Homebrew and a separate Node installation are not required.
Install, start, and pair in one command:
curl -fsSL https://github.com/Ashton-Sidhu/solus/releases/latest/download/install.sh | sh -s -- --setup
The command installs Solus, starts it as a user service, and prints a temporary
pairing link, code, and QR for desktop, web, or mobile. On Linux the service
uses systemd and checks lingering so the server can run after logout and at
boot. If permission is needed, it prints the command to enable lingering. On
macOS it uses a LaunchAgent: keep the Mac logged in and awake for remote access.
To link the host to Solus Cloud instead, copy the command from cloud onboarding
("Where do your agents run?" → link a computer). It passes --link CODE, which
starts the service and links the host with that one-time code. The same command
works when Solus is already installed. Add $HOME/.local/bin to your PATH to
run solus afterwards.
| Command | Purpose |
|---|
solus setup | Install/start the background service, check health, then connect it: in a terminal, choose direct pairing, a personal account link, or an organization attachment, and optionally sign in a provider; without a terminal, print pairing details. --link CODE links (or attaches) with a code from Solus and asks nothing |
solus start | Run in the foreground (--host, --port, --data-dir) |
solus status | Show installed/running versions, service state, and provider versions |
solus service start, stop, restart | Control the background service |
solus service status | Show the background service state |
solus service uninstall | Remove background startup; keep user data |
solus logs | Follow the server log (--lines N) |
solus pair | Create another temporary client pairing link |
solus connect, connect status, connect remove ORG, connect unlink | The linking steps of solus setup for a running server (--code CODE uses a link code); show kind, attachment, Solus API, and delivery; take one organization back; unlink, which makes an attached server personal again |
solus update | Check and update the running host through its shared update service |
Versions live under ~/.local/share/solus/versions; current selects the active
version. The launcher lives at ~/.local/bin/solus. Set SOLUS_RUNTIME_DIR and
SOLUS_BIN_DIR before installation to change these paths. Data lives in
~/.solus; use --data-dir or SOLUS_DATA_DIR consistently for another data
location. The data and runtime directories must be separate. Setup saves its
data path and SOLUS_HOST/SOLUS_PORT values in the service configuration.
The default port is 3000.
Update from any connected client's Update Solus action or run solus update
on the host. Both download and verify the release, wait for accepted work to
finish, then restart. You can cancel while waiting. The updater backs up the
host data after shutdown and restores it with the previous version if the new
server cannot start. Requests remain blocked during candidate verification.
Checks are automatic; installation requires an action. Project files and
provider-owned data outside the Solus data directory are not part of rollback.
The CLI can time out while the host is still waiting; solus status shows its state.
For startup failures, use solus logs. Linux also records process output in
journalctl --user -u solus.service; macOS records it in the data directory's
logs/solus.log. Run solus setup to restore a missing service definition.
Keep older version directories until the running supervisor has stopped.
The desktop app can also host Solus and uses its own desktop updater.
To build a server release from this checkout:
bun run build
bun scripts/package-server.ts --platform linux --arch x64
SOLUS_VERSION=<package-version> \
SOLUS_INSTALL_ARCHIVE="$PWD/release/solus-server-linux-x64.tar.gz" \
SOLUS_INSTALL_SHA256SUMS="$PWD/release/SHA256SUMS" sh scripts/install.sh
The release workflow attaches the installer to new server releases. These
source changes do not publish or replace an existing release.
Build from source
You'll additionally need Bun and the Xcode Command Line Tools.
git clone https://github.com/Ashton-Sidhu/solus.git
cd solus
bun install
bun run dev # development
For a fresh test profile, run SOLUS_SKIP_ONBOARDING=1 bun run dev to open the
desktop workspace without first-run onboarding. In a browser, add
?skip-onboarding to the client URL. scripts/agent/open-app.ts adds this flag
by default; pass { skipOnboarding: false } to test onboarding. The flag only
affects that launch and does not mark onboarding complete.
bun run build # verify the app + web client compile
bun run dist # produces a Solus.app bundle in dist/
.env is optional — copy .env.example if you're testing analytics, Google integration, or release signing. Leave those values empty otherwise.
How it works
renderer → window.solus.<method>() (apps/desktop/src/preload — wraps as an RPC envelope)
→ SolusServer.handle() (packages/server/src/transport/server.ts)
→ handler in transport/handlers/ (one file per domain)
→ SessionRuntime / managers (packages/server/src/execution/session-runtime.ts)
events ← broadcast back over RPC topics
| Path | Owns |
|---|
src/main/ | Electron main process — sessions, agents, git, RPC server |
src/main/agents/ | Agent backends (claude/, codex/) and the backend registry |
src/renderer/ | Svelte 5 UI — one folder per feature, stores in contexts/ |
src/shared/ | RPC method and topic definitions shared by both sides |
client/ | Web client served by the headless server |
docs/adr/ | Architecture decision records |
Built with Electron + electron-vite, Svelte 5, TypeScript, Tailwind CSS v4, and the @anthropic-ai/claude-agent-sdk.
Contributing
Contributions are welcome. Start with CONTRIBUTING.md for setup, code style, and PR expectations; CLAUDE.md documents the conventions agents (and humans) should follow in this repo. Please also read the Code of Conduct.
Found a security issue? See SECURITY.md — please don't open a public issue.
License
Business Source License 1.1 — free for personal and internal use; converts to Apache 2.0 on 2030-07-14. You may not resell Solus or offer it as a competing hosted service before then.
