# Schaltwerk - AI Agent Orchestration IDE ## Overview Schaltwerk is a native macOS desktop application that enables developers to run and orchestrate multiple AI coding agents in parallel on the same codebase. Described as "The IDE without editor," it provides isolated git worktree environments for each agent session, ensuring changes don't interfere until explicitly reviewed and merged. Built with a Rust backend (Tauri) and React frontend, Schaltwerk has gained traction among developers seeking to coordinate multiple AI agents for complex development workflows, with 123 GitHub stars and active development. ## Key Features - **Isolated Git Worktrees** - Each agent session operates in its own git worktree with dedicated branch, preventing conflicts and enabling parallel work - **Multi-Agent Support** - Run Claude Code, OpenCode, Codex, Gemini, Qwen, Factory Droid, and custom agents simultaneously - **Dual Terminal System** - Top terminal for agent observation (read-only), bottom terminal for manual testing and commands - **Session Management** - Quick switching (⌘1-9), state tracking (SPEC/RUNNING/REVIEWED), and lifecycle management - **Spec-Driven Workflow** - Plan features in markdown specifications, execute through agents, iterate with refined specs - **Built-in Diff Viewer** - GitHub-style diff viewing with inline commenting for thorough code review (⌘G) - **One-Command Operations** - Squash-merge to main (⌘⇧M) or create PR (⌘⇧P) with single keyboard command - **Orchestrator Mode** - Special session (⌘1) that stays on main branch for planning and coordinating multi-agent workflows - **Custom Agent Configuration** - Per-agent environment variables, CLI arguments, and binary selection - **MCP Server Integration** - REST API for automation and agent-to-agent orchestration - **Terminal Only Mode** - Manual work in isolated worktrees without AI assistance - **Session Recycling** - Dismiss and restart sessions with refined prompts without cleanup overhead ## Use Cases - **Parallel Feature Development** - Multiple developers or agents working on different features simultaneously without conflicts, ideal for complex projects requiring concurrent development streams - **Large-Scale Refactoring** - Coordinate multiple agents for systematic code modernization, migration projects, or architectural changes across multiple modules - **Experimental Development** - Test different AI agents or approaches in parallel without risk to main codebase, perfect for comparing agent capabilities - **Multi-Agent Orchestration** - Implement "Scaffold → Swarm → Stabilize" patterns where one agent creates structure, others fill in details, and final agent stabilizes - **CI/CD Automation** - Factory Droid and other agents automate testing, building, and deployment tasks in isolated environments - **Code Review Automation** - Agents review code in isolated branches before merging, ensuring quality without blocking main development ## Platform Support - **Desktop**: macOS 11+ (Big Sur or later) for both Apple Silicon and Intel architectures - **Linux**: Alpha version coming soon - **Windows**: Not currently supported - **Requirements**: Git 2.30+ with worktree support, at least one AI coding agent CLI installed - **Installation**: `brew install --cask 2mawi2/tap/schaltwerk && open -a Schaltwerk` ## Pricing - **Cost**: Free and Open Source - **License**: MIT License - **Source Code**: Available at https://github.com/2mawi2/schaltwerk - **Agent Costs**: Individual AI agents may require API keys or subscriptions (Claude, GPT, Gemini, etc.) - **No Tracking**: Schaltwerk itself doesn't track or collect usage data ## Integrations ### Supported AI Agents - **Claude Code** (Anthropic) - `/opt/homebrew/bin/claude` - **OpenCode** - Open-source terminal agent - **Codex** (Stately) - Git-based AI agent for repository automation - **Gemini** (Google) - Google's Gemini CLI integration - **Qwen** (Alibaba Cloud) - Qwen Code agent - **Factory Droid** - Automation-focused agent for scripts and CI tasks - **Amp** - Additional community agent option - **Terminal Only** - No AI agent, just isolated worktree with shell access ### Git Integration - Automatic worktree creation and cleanup - Branch management and isolation - Squash-merge to main branch - GitHub CLI integration for PR creation - Session resumption support ### API & Automation - **MCP API**: REST API for automating session management and orchestration - **Agent Orchestration**: One agent can control and coordinate others via MCP server - **Custom Agents**: Support for any CLI tool or custom agent binary - **Environment Variables**: Per-agent and per-project environment configuration ## Installation ### Prerequisites - macOS 11+ (Big Sur or later) - Git 2.30+ with worktree support - At least one AI coding agent CLI (Claude Code, OpenCode, Codex, etc.) - Homebrew package manager ### Installation Command ```bash brew install --cask 2mawi2/tap/schaltwerk && open -a Schaltwerk ``` ### Configuration - **Global Settings**: `~/Library/Application Support/schaltwerk/settings.json` - **Project Settings**: `~/Library/Application Support/schaltwerk/<project>/database.db` - **Configurable Items**: Agent binary paths, CLI arguments, environment variables, worktree setup scripts, run scripts ## Technical Details ### Architecture - **Frontend**: React + TypeScript (55.9%) - **Backend**: Rust via Tauri framework (39.2%) - **Build Tools**: Bun, npm, Vite - **Application Type**: Native desktop application with web technology frontend - **Data Storage**: Local SQLite database per project - **Isolation Mechanism**: Git worktrees with dedicated branches per session ### Core Components 1. **Session Manager** - Handles isolated worktree creation and lifecycle 2. **Terminal Manager** - PTY terminal multiplexing for dual terminals 3. **Git Integration Layer** - Automated branch/worktree/merge operations 4. **Agent Orchestrator** - Coordinates multiple AI agents 5. **MCP Server** - REST API for automation and session management ### Session Workflow States 1. **SPEC** - Planning phase in markdown 2. **RUNNING** - Agent actively working 3. **REVIEWED** - Validated and ready for merge ### Keyboard Shortcuts - **⌘1-9** - Switch between sessions (⌘1 is orchestrator) - **⌘N** - Create new session - **⌘⇧N** - Create new spec - **⌘T** - Focus agent terminal (top) - **⌘/** - Focus manual shell (bottom) - **⌘G** - View git diff - **⌘E** - Run configured scripts - **⌘R** - Mark session as reviewed - **⌘⇧M** - Merge session to main - **⌘⇧P** - Create pull request - **⌘D** - Cleanup session - **⌘⇧←/→** - Switch between projects ## Workflow Examples ### Feature Development 1. **⌘1** - Plan in orchestrator 2. **⌘⇧N** - Create specification 3. **⌘N** - Start agent session 4. **⌘T** - Monitor agent progress 5. **⌘G** - Review diff 6. **⌘E** - Run tests 7. **⌘R** - Mark as reviewed 8. **⌘⇧M** - Merge to main 9. **⌘D** - Cleanup worktree ### Multi-Agent Orchestration (Scaffold → Swarm → Stabilize) 1. **Scaffold** - One agent creates initial structure 2. **Swarm** - Multiple agents work on different modules in parallel 3. **Stabilize** - Final agent reviews, tests, and stabilizes integration ## Best Practices - One session per feature or bugfix for clear isolation - Always review changes with ⌘G before merging - Run tests before marking sessions as reviewed - Clean up sessions with ⌘D after successful merge - Use orchestrator for planning and coordination - Write clear, specific prompts (not vague instructions) - Monitor agent progress in real-time via top terminal - Test features manually in addition to automated tests - Use descriptive session names (e.g., 'feature-auth' not 'session1') - Rotate API keys regularly (settings stored unencrypted) ## Common Pitfalls - Merging without reviewing changes first - Canceling sessions before merging (loses uncommitted work) - Creating vague prompts that don't guide agents effectively - Forgetting to run tests before marking reviewed - Letting sessions pile up without cleanup - Working directly in orchestrator for features (should create sessions) - Storing sensitive API keys on shared machines - Not verifying agent version after upgrades ## Development Setup For contributors looking to build from source: ### Prerequisites - Bun or npm - Git - macOS development environment ### Commands ```bash # Install dependencies bun install # or npm install # Run tests bun run test # Development mode bun run tauri:dev # Build production bun run tauri:build ``` ### Optional Tools - Justfile with convenience recipes for common tasks ## Community & Development - **Repository**: https://github.com/2mawi2/schaltwerk - **Stars**: 123 (as of 2025) - **Contributors**: 8 active contributors - **Commits**: 1,579 on main branch - **License**: MIT (open to contributions) - **Documentation**: https://schaltwerk.mintlify.app - **Contribution Model**: Open to contributions via GitHub issues and pull requests ## Remarks Schaltwerk represents a paradigm shift in AI-assisted development by providing true parallel orchestration of multiple AI coding agents through git worktree isolation. Unlike traditional IDEs that wrap or constrain agents, Schaltwerk runs agent CLIs natively and leverages git's powerful branching and worktree capabilities to prevent conflicts while enabling sophisticated multi-agent workflows. The keyboard-driven interface, spec-driven development approach, and built-in review tools make it particularly valuable for developers managing complex projects, conducting large-scale refactoring, or exploring experimental development patterns with AI assistance. As the first "IDE without editor," Schaltwerk fills a unique niche for teams looking to harness multiple AI agents systematically rather than ad-hoc, while maintaining code quality through structured review processes.