Ensemblr

A macOS orchestrator for multi-agent coding work, driving the Pi CLI or the Claude Code CLI — whichever
you already run.

The agent inside a workspace can drive the app itself: spawn sub-agents into their own chat tabs, delegate
a unit of work to each, block until they finish, read their reports, and integrate the results. That
permission-gated surface is Ensemblr Control, and the worktree manager underneath it exists to make it
safe — every stream of work gets its own git worktree, branch, and review path, so a fan-out of agents
cannot collide.

Apple silicon Macs only. Bring your own agent CLI — Pi or Claude Code, one is enough. git and an
authenticated gh are required.

No Ensemblr account, no sign-in, no cloud sync, no telemetry. State is a local SQLite database, secrets go
to the macOS Keychain, GitHub tokens stay with gh and are never copied anywhere, and the app ships no
agent binary of its own — it drives the one you installed.

Ensemblr Control driving the app from inside a workspace: the agent names its own tab, moves the workspace to In progress, starts a run script, then delegates to two sub-agents in their own chat tabs and launches a Claude Code harness in a terminal.

• Version: 0.1.0-beta.3 (pre-1.0, polish stage)
• Platform: macOS on Apple silicon
• License: MIT

Status

Ensemblr is pre-1.0, in the polish stage. The core workflows — isolated workspaces, Pi and Claude Code
agent sessions, the review and PR flow, and the GitHub / Linear / git integrations — are implemented and
wired to real services. The first public build is out as a beta; expect rough edges and breaking
changes before 1.0. See CHANGELOG.md for recent changes.

Install

Download Ensemblr 0.1.0-beta.3 (.dmg, Apple silicon) — open it and drag Ensemblr to Applications.

The build is code-signed with a Developer ID certificate, hardened-runtime, notarized by Apple, and
stapled, so it opens without a Gatekeeper prompt and validates offline. Every build is on the
Releases page.

To build it yourself instead, on an Apple silicon Mac with Node 24.x:

npm install
npm run make          # .dmg + .zip under out/make/

A build of your own is signed and notarized only when Apple API credentials are present in the
environment; without them you get an unsigned build that Gatekeeper will hold on first launch. The full
path — prerequisites, channels, unsigned builds, and where Ensemblr keeps its data — is
docs/guide/01-install.md.

Requirements

git, the GitHub CLI (gh, authenticated), and at least one agent runtime — either the Pi CLI or the
Claude Code CLI. The two are gated against each other: a machine carrying only one of them is ready.
Ensemblr checks all of this itself at first launch and offers a fix per failing check. Every check is
documented in docs/guide/02-requirements.md.

Documentation

Using Ensemblr — the user guide:
install ·
requirements ·
first run ·
concepts ·
workspaces ·
agents ·
terminals & run scripts ·
reviewing changes ·
agent control ·
integrations ·
app settings ·
repository settings ·
shortcuts ·
troubleshooting

Working on Ensemblr — CONTRIBUTING.md ·
docs/onboarding.md (clone → run → first change) ·
docs/architecture-map.md (which directory owns which concern) ·
docs/adr/ (47 Architecture Decision Records) ·
docs/agent-control.md ·
docs/harnesses.md ·
docs/build-and-release.md ·
CONTEXT.md (product definition and ubiquitous language) ·
SECURITY.md

What it does

Agents drive the app — that is the point. Ensemblr Control is a permission-gated surface that lets an
agent spawn conversations, launch harnesses, run terminals, open file and diff tabs, read the workspace
diff and leave review comments on it, read and write Linear issues, ask you a multiple-choice question, and
move its workspace across the board. Pi reaches it through a shipped extension; Claude Code and any
MCP-capable harness reach the same operations through an embedded MCP server, so the two surfaces cannot
drift.

Multi-agent orchestration, not just a fan-out button. The root agent delegates a unit of work per
sub-agent, each in its own tab and its own context, then blocks on ensemblr_wait_for_agents until they
report back — no hand-rolled polling loop. Sub-agents do their own work and never delegate onward, so the
tree stays one level deep. Depth, spawn count, and spawn rate are capped. Linear writes are withheld from
sub-agents, and nothing at any depth can move an issue to a completed or canceled state: agent work stops
at In Review, enforced in code rather than in a prompt.

Two agent runtimes, one chat surface. Pi runs as a CLI in RPC mode; Claude Code is driven through the
Agent SDK against your own claude binary — Ensemblr ships none. Both share the same timeline, tool
cards, model and thinking pickers, tool-approval prompts, git-backed checkpoints, session branching, and
composer attachments. Plan mode holds an agent to read-only tools until it submits a plan, enforced per
tool call rather than by instruction, and inherited by every sub-agent it spawns.

A worktree manager underneath. Start a workspace from an existing branch, a GitHub PR, or a Linear
issue. Each one is a git worktree with its own branch, working tree, agent sessions, run state, and review
path. A workspace either adopts an existing branch or cuts a fresh one; the base branch is fetched and
fast-forwarded first, and can be retargeted later without touching the worktree. A dashboard board groups
workspaces into Backlog, In progress, In review, Done, and Canceled.

Local-first review that ends in GitHub. One panel with Files, Changes, and Checks. Source-scoped diffs,
per-file discard, a live file tree, and review comments anchored to specific lines that agents can read,
answer, and resolve. Then an inline PR editor, commit and push, per-check status through gh, and a
two-step merge — or archive the workspace instead.

Terminals and run scripts. An xterm.js dock over real PTYs, restored across restart. A repository
declares any number of named run scripts in its committed .ensemblr/settings.toml, each with a command
and an icon, one of them the ⌘R default; single-command setup and archive scripts run on the same
lifecycle, with setup fingerprinted so an unchanged workspace skips it.

Three languages. The app ships in English, Russian, and Greek — window, native menu bar, and the prose
agents write back. A user-facing string a change adds ships translated in the same change.

The scope rests on five commitments: the agent can drive the app under permission; isolation is the
product; the agent runtime is pluggable and never privileged; review is local-first and ends in GitHub;
configuration is committed, legible, and ours.

What it stores, and where

There is no Ensemblr account to create, nothing to sign in to, and nothing synced off your machine.

• No account, no server. Ensemblr talks to GitHub, Linear, and your agent CLIs directly. There is no
  Ensemblr backend in the path and no telemetry.
• GitHub tokens stay with gh. Ensemblr stores none — no token field in settings, no OAuth screen, no
  second place one can leak from. It shells out to the CLI you already authenticated.
• Secrets live in the macOS Keychain, never a file and never an environment variable. Linear's OAuth
  tokens go straight there; the app can list what it holds without reading it back.
• State is a local SQLite database (Node 24's built-in node:sqlite), alongside worktrees under a root
  directory you choose.
• No agent binary ships in the app. Your pi and claude installs, your credentials, your models,
  your config — the ~260 MB the Claude Agent SDK would bundle is deliberately left out.

The threat model, including what is explicitly out of scope, is SECURITY.md; what each
integration stores is docs/guide/10-integrations.md.

Core vocabulary

Full glossary in CONTEXT.md; the user-facing tour is
docs/guide/04-concepts.md.

Tech stack

Contributing

Issues are welcome. For code, open an issue to discuss the change first — this is a pre-1.0 codebase with
opinionated structure, and a large unsolicited diff is hard to take. Start at
CONTRIBUTING.md.

Security reports go to SECURITY.md, never to a public issue.

License

MIT © Philipp Soldunov

Built with love in Cyprus 🇨🇾