Conductor

Why Conductor

Modern AI coding interfaces are designed for doom-coding, which is basically vibecoding turned into doom-scrolling because you have nothing to do while the agent runs. However, as AI becomes more and more powerful, human attention and judgement becomes the difference between great projects and glorified slop.

What's Conductor

Conductor is an attention orchestrator for vibe-coding and AI collaborative works in general. It treats your attention as the scarce resource and aims to maximize useful human decisions while minimizing attention fragmentation. Human attention is linear, therefore Conductor is designed to focus the user's attention to one working thread instead of spanning it out to 10 different tabs.

When the work in front of you reaches a long-running agent phase, Conductor keeps it moving in the background and helps redirect your attention to the next thread where your judgment is useful. One coherent thread stays in the foreground while other projects, threads, and workers continue without demanding constant supervision.

Thread User Agents preserve context and handoffs, Project Manager Agents watch dependencies and cross-thread impact, and durable skilled workers execute bounded work under explicit modes and permissions. Together they turn parallel agents into a coordinated collaboration workflow instead of a wall of sessions to babysit. Everything they do is recorded and replayable.

Requirements

• Linux or WSL with a graphical desktop
• Node.js 22 or newer, and npm
• An AI provider: a GitHub Copilot account, or an API key for OpenAI, Anthropic, Gemini, OpenRouter, or another provider supported by LiteLLM

Install

npm install

Configure AI

Conductor is currently preconfigured for GitHub Copilot through copilot-api. To use another provider, put its API key behind a local LiteLLM gateway and point Conductor at that gateway:

Provider	Gateway key variable	Example LiteLLM model route
OpenAI	OPENAI_API_KEY	openai/gpt-4.1
Anthropic	ANTHROPIC_API_KEY	anthropic/claude-sonnet-4-5-20250929
Google Gemini	GEMINI_API_KEY	gemini/gemini-2.5-flash
OpenRouter	OPENROUTER_API_KEY	openrouter/openai/gpt-4.1

Follow AI_CONFIGURATION.md for the exact Copilot setup, per-provider LiteLLM configuration, launch commands, model selection, and troubleshooting. Provider API keys stay in the gateway process; do not put them in Conductor's settings.

Run

npm run dev

To run the packaged desktop build instead:

npm run pack
./dist/linux-unpacked/conductor

First run

A new install has no workspace, so nothing opens until you choose one.

1. Select workspace appears. Choose New Workspace.

2. The setup surface opens. Choose Add project folder and pick an existing directory — a real project you want worked on. It does not need to be a Git repository, but it must already exist.

3. Fill in Project name, First thread, and optionally Thread objective, then Confirm project. A thread is one line of work in that project; the objective is what the thread is for.

4. Staff the thread with Add worker agent and pick a skill. The built-in skills are:

   Skill	Purpose
   Plan	Inspect a codebase and produce an implementation plan before mutation.
   Research	Collect evidence, compare options, and report source-backed findings.
   SWE	Implement and validate focused software changes.
   QA	Reproduce, execute, and verify behavior against its stated requirement.
   Iterate	Interrogate an idea with the user until the design is settled, then record it.
   Writing	Draft and revise prose against a stated audience and objective.
   Review	Critique existing work against its objective and report specific defects.

5. Choose Confirm setup, then Enter recommended thread. Setup will not confirm until every project has a thread, exactly one project is master, and thread names are unique within a project.

You are now in the workspace: the file explorer on the left follows the attentive thread's project, the focused worker sits in the middle, and the work forest and the thread's User Agent sit on the right.

Everyday use

• Send work to a worker. Type in the composer under the worker transcript and press Send prompt or Ctrl+Enter. While a run is already active the same shortcut steers it instead, and Alt+Enter queues the prompt behind it. A worker only accepts work while its thread has attention.
• Choose how much rope it gets. Plan exposes read-only tools, so the worker can inspect and propose but never mutate. Build allows mutation, asking permission before each one unless you have granted a matching rule.
• Copy an answer out. Each turn's final response has a copy button, and right-clicking the transcript offers Copy, Copy All, and Copy Final Response.
• Talk to the thread's User Agent. The worker does the work; the thread UA is where you discuss what the thread should do next and who should do it. It stays visible beside the worker and keeps its own draft and transcript.
• Move on. Complete attention in the top bar ends the current work turn and continues to the recommended thread. Its arrow opens outcomes, milestones, stopping points, destination choice, and switching to another thread without completing.

Where your work is stored

Durable state lives in conductor.sqlite under Electron's user-data directory, with per-project databases beside it and attachment bytes in an adjacent attachments/ directory. SQLite holds the forest snapshot and work turns, conversations and runtime events, worker journals and feed projections, pending decisions, authority rules, queued prompts, approved plans and handoffs, conflict notices, milestones, and append-only audit events. Drafts and viewport state are renderer-local and scoped by worker, UA, or project.

Safety boundaries

• Only confirmed Switch attention, Enter attention, and Complete attention commands move attention.
• Plan Mode exposes only read-only tools. Mutating tools are also rejected server-side if a provider emits one unexpectedly.
• Build Mode requests permission before each mutation unless an active rule exactly matches the tool, normalized resource, and explicit run/worker/project scope.
• Remembered rules are inspectable and revocable.
• Tool paths are project-relative and cannot escape the project root.
• Attachments are copied into project-scoped staging, size- and MIME-checked, SHA-256 identified, and materialized only after project ownership validation.
• Queued prompts are atomically claimed and dispatched at most once.
• A provider response ID never replaces Conductor's worker or run identity.
• Thread complete rejects active runs, queued prompts, and unresolved decisions. Stopping work is a separate audited command.

Validate

npm run typecheck   # both TypeScript projects
npm test            # domain, backend, and renderer unit tests
npm run test:e2e    # builds, then drives the real Electron app
npm run build       # typecheck plus electron-vite build
npm run pack        # unpacked desktop build in dist/

npm run test:e2e launches the built application against an isolated data directory and captures screenshots under test-results/.

Two suites spend real Copilot tokens and are kept out of the default run. They need the proxy up:

npm run test:live        # provider behaviour against the live proxy
npm run test:edit-live   # PM-orchestrated edit queue, end to end

Architecture

src/shared/       Versioned schemas, transition rules, IPC types, scheduler
src/main/         SQLite, Copilot adapter, tools, coordination, application service
src/preload/      Dependency-free sandboxed IPC bridge
src/renderer/     Four-region React workspace and dialogs
src/vendor/       Vendored third-party source with provenance
tests/domain/     Invariant and deterministic policy tests
tests/backend/    Runtime, persistence, queue, handoff, conflict, and authority tests
tests/renderer/   Presentation logic and markdown rendering tests
tests/e2e/        Real Electron workflow and visual coverage

Provider-specific payloads stop at CopilotRuntimeAdapter. The rest of Conductor consumes normalized sequenced runtime events and durable domain records.

Documentation

File	What it is
BRAINSTORMING.md	The product argument. Why Conductor works the way it does, including the two workspace sketches.
AI_CONFIGURATION.md	Connect Copilot or common API-key providers and choose different models for coordinators and workers.
IMPLEMENTATION_PLAN.md	The specification. Invariants, state semantics, contracts, and the test plan.
IMPROVEMENT_NOTE.md	Change log by issue: what was wrong, what was done, how it was verified, what is still limited.
AGENT_GUIDE.md	Working agreement for agents contributing to this repository.
PROVENANCE.md	Third-party source provenance.
AUDIT_PARTIAL_FINDINGS.md, AUDIT_FAILED_FINDINGS.md	Closed QA audits, kept as evidence. Remediation is recorded in IMPROVEMENT_NOTE.md.
CLAUDE_CODE_UI_RESEARCH_REPORT.md, CLAUDE_CODE_FEATURE_COVERAGE_REPORT.md	Prior-art research that informs implementation technique only.
VSCODE_FORK_FEASIBILITY_ANALYSIS.md, VSCODE_FORK_IMPL_PLAN.md	Archive. The VS Code fork route was evaluated and not taken; Conductor is a standalone Electron application.