Skip to content

docs: modernize README #4677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Kitenite wants to merge 6 commits into from
Closed

docs: modernize README #4677

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
17baacc
docs: modernize README
Kitenite May 17, 2026
0b3c0ee
docs: fix README issues for HN launch
Kitenite May 21, 2026
dfac87f
docs: add agent icons to table, tighten copy
Kitenite May 21, 2026
957808b
docs: improve scannability, add Mastracode to supported agents
Kitenite May 21, 2026
936000b
docs: align README style with popular repos (uv, Zed, Ghostty)
Kitenite May 21, 2026
300fcb9
docs: front-load Getting Started to match high-star repo layout
Kitenite May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 55 additions & 137 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,92 +1,59 @@
<div align="center">

<img width="full" alt="Superset" src="apps/marketing/public/images/readme-hero.png" />
<img width="100%" alt="Superset" src="apps/marketing/public/images/readme-hero.png" />

### The Code Editor for AI Agents
### Run 100+ coding agents in parallel.

A macOS app that gives every agent its own git worktree, terminal, and review surface — and notifies you when one needs your input.

[![GitHub stars](https://img.shields.io/github/stars/superset-sh/superset?style=flat&logo=github)](https://github.com/superset-sh/superset/stargazers)
[![GitHub release](https://img.shields.io/github/v/release/superset-sh/superset?style=flat&logo=github)](https://github.com/superset-sh/superset/releases)
[![License](https://img.shields.io/github/license/superset-sh/superset?style=flat)](LICENSE.md)
[![License](https://img.shields.io/badge/license-ELv2-blue)](LICENSE.md)
[![Twitter](https://img.shields.io/badge/@superset__sh-555?logo=x)](https://x.com/superset_sh)
[![Discord](https://img.shields.io/badge/Discord-555?logo=discord)](https://discord.gg/cZeD9WYcV7)

<br />

Orchestrate swarms of Claude Code, Codex, and more in parallel.<br />
Works with any CLI agent. Built for local worktree-based development.

<br />

[**Download for macOS**](https://github.com/superset-sh/superset/releases/latest) &nbsp;&bull;&nbsp; [Documentation](https://docs.superset.sh) &nbsp;&bull;&nbsp; [Changelog](https://github.com/superset-sh/superset/releases) &nbsp;&bull;&nbsp; [Discord](https://discord.gg/cZeD9WYcV7)

<br />

[**Download for macOS**](https://github.com/superset-sh/superset/releases/latest) &nbsp;&bull;&nbsp; [▶ Watch the demo](https://www.youtube.com/watch?v=mk02bSQmEKY) &nbsp;&bull;&nbsp; [Website](https://superset.sh) &nbsp;&bull;&nbsp; [Docs](https://docs.superset.sh) &nbsp;&bull;&nbsp; [Discord](https://discord.gg/cZeD9WYcV7)

</div>

## Code 10x Faster With No Switching Cost

Superset orchestrates CLI-based coding agents across isolated git worktrees, with built-in terminal, review, and open-in-editor workflows.
## What it is

- **Run multiple agents simultaneously** without context switching overhead
- **Isolate each task** in its own git worktree so agents don't interfere with each other
- **Monitor all your agents** from one place and get notified when they need attention
- **Review and edit changes quickly** with the built-in diff viewer and editor
- **Open any workspace where you need it** with one-click handoff to your editor or terminal
Superset is a macOS app for running many CLI coding agents in parallel. Each agent gets its own git worktree, terminal, and diff view — so they work on different branches at once without trampling each other or your main checkout.

Wait less, ship more.
**How it works:**

## Features
1. **Create a workspace** — Superset cuts a git worktree on a fresh branch and runs your setup script.
2. **Run any agent in it** — Claude Code, Codex, Cursor Agent, or any CLI agent, each in its own terminal.
3. **Review and merge** — Superset pings you when an agent needs input; review the diff in-app and merge through your normal flow.

| Feature | Description |
|:--------|:------------|
| **Parallel Execution** | Run 10+ coding agents simultaneously on your machine |
| **Worktree Isolation** | Each task gets its own branch and working directory |
| **Agent Monitoring** | Track agent status and get notified when changes are ready |
| **Built-in Diff Viewer** | Inspect and edit agent changes without leaving the app |
| **Workspace Presets** | Automate env setup, dependency installation, and more |
| **Universal Compatibility** | Works with any CLI agent that runs in a terminal |
| **Quick Context Switching** | Jump between tasks as they need your attention |
| **IDE Integration** | Open any workspace in your favorite editor with one click |
## Why Superset

## Supported Agents
- **Agent-agnostic** — if it talks to stdin/stdout, Superset runs it. Mix Claude Code, Codex, Cursor, and others across workspaces — no vendor lock-in.
- **Local-first** — worktrees, file edits, and agent processes run on your machine. Your code and git history never leave it.
- **Bring your own keys** — Superset doesn't proxy or resell agents. They use the subscriptions and API keys you already have.

Superset works with any CLI-based coding agent, including:
## Getting Started

| Agent | Status |
|:------|:-------|
| [Amp Code](https://ampcode.com/) | Fully supported |
| [Claude Code](https://github.com/anthropics/claude-code) | Fully supported |
| [OpenAI Codex CLI](https://github.com/openai/codex) | Fully supported |
| [Cursor Agent](https://docs.cursor.com/agent) | Fully supported |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully supported |
| [GitHub Copilot](https://github.com/features/copilot) | Fully supported |
| [OpenCode](https://github.com/opencode-ai/opencode) | Fully supported |
| [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) | Fully supported |
| Any CLI agent | Will work |
> [!NOTE]
> Superset is macOS-only and requires a free account (GitHub or Google sign-in). Windows and Linux aren't supported yet.

If it runs in a terminal, it runs on Superset
**[Download Superset for macOS](https://github.com/superset-sh/superset/releases/latest)**, then sign in with GitHub or Google.

## Requirements
### Requirements

| Requirement | Details |
|:------------|:--------|
| **OS** | macOS (Windows/Linux untested) |
| **Runtime** | [Bun](https://bun.sh/) v1.0+ |
| **Version Control** | Git 2.20+ |
| **GitHub CLI** | [gh](https://cli.github.com/) |
| **Caddy** | [caddy](https://caddyserver.com/docs/install) (for dev server) |

## Getting Started

### Quick Start (Pre-built)

**[Download Superset for macOS](https://github.com/superset-sh/superset/releases/latest)**

### Build from Source
| **OS** | macOS (Windows and Linux are not supported) |
| **Git** | 2.20+ — Superset manages real git worktrees |
| **Account** | A free Superset account (GitHub or Google sign-in) |
| **GitHub CLI** | [gh](https://cli.github.com/) — optional, for PR workflows |

<details>
<summary>Click to expand build instructions</summary>
<summary>Build from source</summary>

Building from source additionally requires [Bun](https://bun.sh/) v1.0+ and [Caddy](https://caddyserver.com/docs/install).

**1. Clone the repository**

Expand Down Expand Up @@ -136,81 +103,47 @@ open apps/desktop/release

</details>

## Keyboard Shortcuts

All shortcuts are customizable via **Settings > Keyboard Shortcuts** (`⌘/`). See [full documentation](https://docs.superset.sh/keyboard-shortcuts).

### Workspace Navigation
## Features

| Shortcut | Action |
|:---------|:-------|
| `⌘1-9` | Switch to workspace 1-9 |
| `⌘⌥↑/↓` | Previous/next workspace |
| `⌘N` | New workspace |
| `⌘⇧N` | Quick create workspace |
| `⌘⇧O` | Open project |
### Parallel agents in isolated git worktrees

### Terminal
Each task runs in its own git worktree off the same repository — shared object store, independent branch and working directory. Agents install dependencies and run tests without touching each other or your main checkout.

| Shortcut | Action |
|:---------|:-------|
| `⌘T` | New tab |
| `⌘W` | Close pane/terminal |
| `⌘D` | Split right |
| `⌘⇧D` | Split down |
| `⌘K` | Clear terminal |
| `⌘F` | Find in terminal |
| `⌘⌥←/→` | Previous/next tab |
| `Ctrl+1-9` | Open preset 1-9 |
### Notifications when an agent needs you

### Layout
Superset watches every workspace and pings you the moment an agent asks a question or finishes. The sidebar shows every workspace's state at a glance, so you jump straight to the one that needs you.

| Shortcut | Action |
|:---------|:-------|
| `⌘B` | Toggle workspaces sidebar |
| `⌘L` | Toggle changes panel |
| `⌘O` | Open in external app |
| `⌘⇧C` | Copy path |
### Built-in diff review and inline editing

## Configuration
Every workspace has a diff view for uncommitted, staged, and last-turn changes. Edit and commit in-app — or hand the worktree to VS Code, Cursor, Zed, or your terminal in one click.

Configure workspace setup and teardown in `.superset/config.json`. See [full documentation](https://docs.superset.sh/setup-teardown-scripts).
### Reproducible workspace setup

```json
{
"setup": ["./.superset/setup.sh"],
"teardown": ["./.superset/teardown.sh"]
}
```
A `.superset/config.json` defines what runs on create and destroy — copy `.env`, install dependencies, run migrations, tear down branches. New workspaces come up identical to your main checkout in seconds.

| Option | Type | Description |
|:-------|:-----|:------------|
| `setup` | `string[]` | Commands to run when creating a workspace |
| `teardown` | `string[]` | Commands to run when deleting a workspace |
## Supported Agents

### Example setup script
These agents run out of the box — no per-agent configuration:

```bash
#!/bin/bash
# .superset/setup.sh
| | | |
|:--|:--|:--|
| <img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/claude.svg" /> &nbsp;[Claude Code](https://github.com/anthropics/claude-code) | <picture><source media="(prefers-color-scheme: dark)" srcset="packages/ui/src/assets/icons/preset-icons/codex-white.svg" /><img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/codex.svg" /></picture> &nbsp;[OpenAI Codex CLI](https://github.com/openai/codex) | <img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/cursor.svg" /> &nbsp;[Cursor Agent](https://docs.cursor.com/agent) |
| <img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/gemini.svg" /> &nbsp;[Gemini CLI](https://github.com/google-gemini/gemini-cli) | <picture><source media="(prefers-color-scheme: dark)" srcset="packages/ui/src/assets/icons/preset-icons/copilot-white.svg" /><img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/copilot.svg" /></picture> &nbsp;[GitHub Copilot](https://github.com/features/copilot) | <img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/amp.svg" /> &nbsp;[Amp Code](https://ampcode.com/) |
| <picture><source media="(prefers-color-scheme: dark)" srcset="packages/ui/src/assets/icons/preset-icons/mastracode-white.svg" /><img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/mastracode.svg" /></picture> &nbsp;[Mastracode](https://code.mastra.ai/) | <picture><source media="(prefers-color-scheme: dark)" srcset="packages/ui/src/assets/icons/preset-icons/opencode-white.svg" /><img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/opencode.svg" /></picture> &nbsp;[OpenCode](https://github.com/opencode-ai/opencode) | <picture><source media="(prefers-color-scheme: dark)" srcset="packages/ui/src/assets/icons/preset-icons/pi-white.svg" /><img height="16" align="top" src="packages/ui/src/assets/icons/preset-icons/pi.svg" /></picture> &nbsp;[Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) |

# Copy environment variables
cp ../.env .env
**Plus any other CLI agent** — if it runs in a terminal, it runs on Superset.

# Install dependencies
bun install
## What runs locally

# Run any other setup tasks
echo "Workspace ready!"
```
Superset runs on your machine. Your code, git worktrees, and agent processes never leave it.

Scripts have access to environment variables:
- `SUPERSET_WORKSPACE_NAME` — Name of the workspace
- `SUPERSET_ROOT_PATH` — Path to the main repository
- **Local** — every git worktree, file edit, diff, and agent process runs as a local process on your Mac. Your source code is never uploaded.
- **Account** — Superset requires a free account (GitHub or Google sign-in). The hosted backend stores only your account and workspace metadata — names, branches, status — to sync state across sessions.
- **Your agents** — Superset doesn't proxy your agents; they use whatever subscriptions or API keys you've already configured.

## Mastra Dependencies
## Configuration

This repo uses the published upstream `mastracode` and `@mastra/*` packages directly. Avoid adding custom tarball overrides unless there is a repo-specific blocker.
Configure workspace setup, teardown, and presets in `.superset/config.json`. See the [configuration docs](https://docs.superset.sh/setup-teardown-scripts). Keyboard shortcuts are customizable via **Settings > Keyboard Shortcuts** (`⌘/`) — see the [shortcut reference](https://docs.superset.sh/keyboard-shortcuts).

## Tech Stack

Expand All @@ -227,33 +160,18 @@ This repo uses the published upstream `mastracode` and `@mastra/*` packages dire
<a href="https://trpc.io/"><img src="https://img.shields.io/badge/tRPC-2596BE?logo=trpc&logoColor=white" alt="tRPC" /></a>
</p>

## Private by Default

- **Source Available** — Full source is available on GitHub under Elastic License 2.0 (ELv2).
- **Explicit Connections** — You choose which agents, providers, and integrations to connect.
Superset is a desktop app built on Electron.

## Contributing

We welcome contributions! If you have a suggestion that would make Superset better:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

You can also [open issues](https://github.com/superset-sh/superset/issues) for bugs or feature requests.

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions and code of conduct.
We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and the PR workflow. For bugs or feature requests, [open an issue](https://github.com/superset-sh/superset/issues).

<a href="https://github.com/superset-sh/superset/graphs/contributors">
<img src="https://contrib.rocks/image?repo=superset-sh/superset" />
</a>

## Community

Join the Superset community to get help, share feedback, and connect with other users:

- **[Discord](https://discord.gg/cZeD9WYcV7)** — Chat with the team and community
- **[Twitter](https://x.com/superset_sh)** — Follow for updates and announcements
- **[GitHub Issues](https://github.com/superset-sh/superset/issues)** — Report bugs and request features
Expand All @@ -267,4 +185,4 @@ Join the Superset community to get help, share feedback, and connect with other

## License

Distributed under the Elastic License 2.0 (ELv2). See [LICENSE.md](LICENSE.md) for more information.
Superset is **source-available** under the Elastic License 2.0 (ELv2). You can read, modify, build, and self-host it for free. ELv2 is not an OSI-approved open-source license — the one real restriction is that you can't offer Superset as a hosted service to third parties. See [LICENSE.md](LICENSE.md) for full terms.
Loading