convez.ai
AgenteAutomaçãoAvançado
AshokNaik009

Chorus — Gerenciador de Terminais Claude Code em Paralelo

AshokNaik009/Chorus

Execute 6 agentes Claude em paralelo com grid, workspaces e persistência

Ver no GitHub
InicialPluginScore · de 0 a 100

Centro de comando para executar múltiplos agentes Claude Code em paralelo dentro de uma única janela. Oferece grid redimensionável de panes de terminal, workspaces nomeados, persistência de sessões, suporte a enxames de agentes com isolamento git e status ao vivo de cada sessão.

Instalação

$npx convez-ai AshokNaik009/Chorus

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar múltiplos agentes Claude Code em tarefas paralelas
  • Gerenciar fluxos de trabalho complexos com isolamento de branches git
  • Revisar e mesclar trabalho de enxames de agentes automaticamente
  • Monitorar saúde de contexto em tempo real durante execução de sessões

Veredito

Solução robusta e de código aberto para orquestração de agentes Claude Code. Bem arquitetada com persistência, suporte a swarms com isolamento git e interface desktop/web unificada — ideal para workflows que exigem paralelismo e rastreabilidade.

README

A tradução para o português deste README ainda está na fila.

Chorus — Parallel Claude Code Terminal Manager

Run multiple Claude Code sessions in parallel inside a single window: a resizable grid of terminal panes grouped into workspaces, a two-tier sidebar with live status badges, adjustable layouts, and pane maximize. Workspaces, layouts and sessions are persisted and restored on relaunch. A focused, open-source take on the BridgeSpace / cmux idea, scoped to Claude Code.

Chorus running three Claude Code sessions in a 1×3 layout, with the two-tier workspace sidebar, live status badges, and the Voice / Export / Import controls in the header

Built bottom-up against a stable PtyBackend seam so the whole UI runs in a browser dev harness and the Electron desktop app from the same @app/ui — only the host transport differs (websockets vs. Electron IPC).

Features

  • Layout templates — 1, 1×2, 1×3, 2×2, 2×3 panes (the layout tree supports arbitrary nesting), with draggable dividers that reflow the PTYs.
  • Multi-workspace — a workspace is a named group of sessions with its own layout and a default working directory new panes inherit. The two-tier sidebar shows workspaces as collapsible groups with their sessions nested underneath.
  • Naming — name a session when you launch it, and rename any workspace or session anytime (✎ button, or double-click).
  • Live status — per-session badges (idle / waiting / running …) driven by Claude Code hooks → OSC, with a stream heuristic fallback. A workspace with a waiting session shows an attention dot.
  • Maximize — zoom one pane to fill the area; other panes stay mounted and their PTYs keep running.
  • Persistence — workspaces, layouts, sessions and cwds survive a reload (web: localStorage) or relaunch (desktop: a JSON file in userData). Saved sessions are re-spawned automatically.
  • Manual vs Swarm modes — a workspace is either a hand-driven grid of terminals (pick 1–6 panes from a dropdown) or a swarm board; switching modes confirms first if live sessions would be lost.
  • Agent swarms — fan one task out to up to 6 role-named agents (one pane each — the grid's limit), each launched as a real Claude Code TUI with its task as the first prompt and a role system-prompt. Broadcast a message to all (or selected) agents, or stop every agent with one click.
  • Git worktree isolation — each swarm agent whose directory is a git repo gets its own branch + worktree so agents never trample each other's files (see Agent swarms & git worktrees).
  • Review & merge — when the agents finish, review each branch's diff (files ±, commits, dirty state) and Merge / Squash / Discard it into the repo's current branch, right from the app.
  • Context health — every pane shows a live NN% context-window occupancy badge (green < 50%, amber < 70%, red ≥ 70%; tune via CHORUS_HANDOFF_PCT / CHORUS_HANDOFF_WATCH_PCT). Past the red line, a Hand off button copies a handoff-brief scaffold for starting a fresh session.
  • Voice dictation — on-device WASM Whisper into the focused pane (no cloud STT).
  • Export / import — portable .chorus bundles: workspace layout everywhere, plus full conversation transcripts on desktop. Every Claude pane's session id is pinned at launch (--session-id) and saved, so an import resumes exactly that conversation (--resume <id>); importing a session that is still live in the current list forks it (--fork-session) instead of clobbering the running one.

Architecture

TypeScript monorepo (npm workspaces + Turborepo). The UI depends only on @app/core interfaces; each host injects a concrete PtyBackend + Persistence.

packages/
  core/          @app/core — framework-agnostic models, the PtyBackend +
                 Persistence seams, status reducer, layout tree, workspace
                 ops, OSC scanner (zero UI/host deps)
  ui/            @app/ui   — React + xterm.js (TerminalPane, LayoutView,
                 two-tier Sidebar, PaneLauncher, StatusBadge, App)
  app-web/       dev harness — Vite page + ws server + node-pty;
                 WebPtyBackend + WebPersistence (localStorage)
  app-electron/  Electron host — main: node-pty over IPC; preload:
                 contextBridge; renderer: ElectronPtyBackend +
                 ElectronPersistence + the same @app/ui App

The single seam between UI and host is PtyBackend (terminal I/O) and Persistence (workspace state). See packages/core/src/.

Agent swarms & git worktrees

Fan-out (Swarm mode → Fan out) turns one task into up to 6 parallel Claude Code agents. Per agent, Chorus:

  1. Checks the agent's directory — each worker can point at its own dir, so one swarm can span several repos.
  2. Creates an isolated worktree when that dir is a git repo:
    • branch chorus/<swarm>-<runid>/<role> off the repo's current HEAD (the <runid> keeps re-runs of a same-named swarm from colliding with the previous run's branches);
    • worktree at <repo>/.chorus/<swarm>-<runid>/<role> — under the repo so the work is visible where you asked for it; .chorus/ is added to the repo's local ignore (.git/info/exclude), never to a tracked .gitignore.
    • If worktree creation fails (or the dir isn't a repo, or the host is the web harness), the agent falls back to running directly in the directory and its system prompt says so honestly — isolated agents are told to commit when done, shared-dir agents are told to stay in their lane.
  3. Launches the agent in that worktree via CLI args (task as the positional first prompt, role framing via --append-system-prompt, optional --dangerously-skip-permissions when auto-start is on). No TUI typing, no MCP server. Each agent self-verifies its own slice — there is no separate verifier agent.

When agents finish, the Review view summarizes each branch vs. the repo's current branch (files ±, commits, uncommitted edits) and offers Merge (auto-commits dirty worktree edits first), Squash, or Discard (removes the worktree and deletes the branch). On a merge conflict the merge is aborted and the base branch left intact. Worktrees are cleaned up on swarm end, workspace close, or the next fan-out, so they don't accumulate.

Requirements

  • Node >= 20 (developed on Node 22)
  • A C toolchain for node-pty (Xcode CLT on macOS, build-essential on Linux, VS Build Tools on Windows)
  • claude on your PATH to launch real Claude Code sessions

Build, run & verify

1. Install + build the packages

npm install          # installs all workspaces; builds node-pty natively
                     # (postinstall fixes the node-pty spawn-helper exec bit)
npm run build        # turbo build across all packages
npm run typecheck    # type-check everything
npm run test         # unit tests (status reducer, layout + workspace ops, …)

2. Browser harness

The dev harness runs the exact same @app/ui + @app/core the desktop app uses — only the host transport differs (websockets here, Electron IPC there).

npm run dev:web      # starts the ws/pty server AND Vite together

Open the printed URL (default http://localhost:5173).

Verify:

  • Pick a layout — 1 / 1×2 / 1×3 / 2×2 / 2×3 → that many panes appear.
  • In an empty pane, optionally set a session name, set a working directory, and click Run Claude (or Shell). The terminal becomes interactive and the claude TUI renders.
  • Drag the dividers between panes — terminals resize and the PTY reflows.
  • Each pane is an independent session; input/output never cross panes.
  • Watch the status badge on each pane/sidebar row change as a turn runs.
  • Use the pane header's maximize button to zoom one pane and restore it.
  • In the sidebar: create workspaces (+ new), collapse groups, rename a workspace or session (✎ / double-click), click a session to focus its pane, × to close (kills the PTY and collapses the layout).
  • Reload the page → your workspaces, layouts and sessions come back (saved sessions are re-spawned).
  • Close the browser tab → all child PTYs are killed (no orphan processes).

3. Desktop app — Electron

packages/app-electron is a real Electron host built with electron-vite. Because node-pty is a native module, rebuild it for Electron's ABI once before running:

npm run rebuild -w app-electron   # @electron/rebuild for node-pty (one-time)
npm run dev     -w app-electron   # hot-reload Electron window
npm run dist    -w app-electron   # electron-builder: dmg / nsis / AppImage
npm run dist:dir -w app-electron  # unpacked build (no installer) for quick checks

Installers land in packages/app-electron/release/. Persistence is a JSON file in the app's userData directory.

Milestones

MilestoneEpicsOutcomeStatus
M00, 1Browser page: one live terminal, then claude running in it✅
M12UI drives sessions purely through core + PtyBackend✅
M23, 41 / 1×2 / 2×2 layouts, resizable panes, session sidebar✅
M35Live status badges via Claude Code hooks → OSC✅
M46Multi-workspace model, 1×3 / 2×3 layouts, maximize, persistence + restore✅
M57Installable Electron app (main: node-pty over IPC; renderer: @app/ui)✅
M1111Workspace export/import — portable .chorus bundle (both hosts)✅
M99Voice dictation into the focused pane (on-device WASM Whisper)✅
M1010Agent swarm — broadcast, fan-out, shared blackboard, swarm view✅
M1211Conversation/memory export/import + resume (Electron, Layer 2)✅
—10Swarm v2 — CLI-arg agent launch, git worktree isolation per agent, per-agent self-verification✅
—10Review & merge — per-agent branch diff, Merge / Squash / Discard into the current branch✅
——Explicit Manual vs Swarm workspace modes; swarm fan-out capped at 6 agents✅
——Context-health badge (% of model window) + handoff-brief export✅
—11Exact session resume — ids pinned at launch (--session-id), --resume on import, --fork-session when the conversation is still live✅

Beyond the PRD v1: the multi-workspace model, the two-tier sidebar, the 1×3 / 2×3 layouts, pane maximize, and session naming are agreed extensions. Chorus v2 adds voice dictation (Epic 9), agent swarms (Epic 10), and portable session memory (Epic 11) — all on-device / local, no cloud STT.

Notes

  • Uses npm workspaces (not pnpm).
  • One dark theme only in v1.
  • @app/ui depends only on @app/core interfaces — never a host package or node-pty directly. Hosts inject a PtyBackend + Persistence.
  • Auto-update (electron-updater) is not wired yet — a future addition.
Ver o original no GitHub

Bom para

Relacionados