DOCSEARCHbyAlgolia
Submit Docs

Schaltwerk

repository·main·Indexed 43 days ago

https://github.com/2mawi2/schaltwerk

An AI-powered git worktree session manager and orchestration tool for AI coding agents. It enables parallel, isolated development workflows by creating separate Git worktrees for each agent session, allowing multiple agents like Claude Code or GitHub Copilot CLI to run simultaneously without workspace conflicts. Includes a Model Context Protocol (MCP) server for agent-driven session management and a spec-driven development lifecycle.

Tokens
79.9K
Snippets
232
Records
368
Agent score
53%

What's inside Schaltwerk

  2. Navigate the Schaltwerk Layout

    main

    The Schaltwerk interface is divided into three main areas:

    • Top Bar: Contains tabs for open projects, a Settings gear icon, an Open button (⌘⇧O) to launch the active worktree in your external editor/terminal, and a Keep-awake button (coffee icon) to prevent system sleep during long tasks.
    • Sidebar: Provides access to the Orchestrator, session filters (Specs, Running, Reviewed), and quick actions. Use ⌘\ or Ctrl+\ to collapse/expand the sidebar.
    • Center: The main workspace containing grouped Terminals and diff/review panels for each session.

  3. What is the Orchestrator and how does it work?

    main

    The Orchestrator is a specialized terminal environment that runs directly on your primary repository branch (e.g., main or a feature hub). Unlike standard sessions that use isolated worktrees, the Orchestrator provides full access to your repository to coordinate multiple AI agents and manage complex workflows.

    Key Characteristics:

    • Direct Branch Access: Commands run in the Orchestrator modify the current branch immediately. Use isolated sessions if you require a disposable sandbox.
    • Planning Hub: Allows you to create, manage, and refine multiple technical specifications (specs) before execution.
    • Agent Coordination: Enables launching multiple agents in parallel to work on different specs simultaneously.
    • MCP Automation: Supports programmatic session management and external tool integration via the Model Context Protocol (MCP).

  4. Understand the documentation file structure

    main

    The documentation site is organized into several key directories and files:

    • mint.json: Mintlify configuration file.
    • package.json: Project dependencies.
    • introduction.mdx: The homepage.
    • installation.mdx: Installation guide.
    • core-concepts/: Contains high-level abstractions like sessions-and-specs.mdx and worktrees-and-terminals.mdx.
    • guides/: Practical user guides including using-schaltwerk.mdx, pull-requests.mdx, agent-setup.mdx, and keyboard-shortcuts.mdx.
    • mcp/: Documentation for Model Context Protocol (MCP) integration and prompting.
    docs-site/
├── mint.json              # Mintlify configuration
├── package.json           # Dependencies
├── introduction.mdx       # Homepage
├── installation.mdx      # Installation guide
├── core-concepts/         # Core concepts
│   ├── index.mdx          # Overview hub
│   ├── sessions-and-specs.mdx
│   └── worktrees-and-terminals.mdx
├── guides/                # User guides
│   ├── using-schaltwerk.mdx
│   ├── pull-requests.mdx
│   ├── agent-setup.mdx
│   └── keyboard-shortcuts.mdx
└── mcp/                   # MCP integration
    ├── integration.mdx
    └── prompting.mdx

  5. Secure merge and session cancellation workflow

    main

    Session protection is critical. Follow these security protocols to prevent data loss:

    Merge Protocol

    1. Resolve Conflicts: Always merge main into the session branch before attempting to merge the session back into main.
    2. Validate Diffs: When merging main, files appearing as "removed" are often just files added to main after the session started. Focus on what the session adds or *modifies`.
    3. Test: Run tests after every merge attempt. Only proceed to cancellation if tests pass.

    Cancellation Rules

    • Never cancel or delete sessions without explicit user consent, especially those marked as [REVIEWED].
    • Only cancel reviewed sessions after a successful merge to main and passing tests.
    • Preserve Git state: If a merge fails, do not delete the session. Uncommitted changes in worktrees are permanently lost, but commits in the Git database can be recovered.
    • Use schaltwerk_pause instead of schaltwerk_cancel if you are uncertain about the session state.

  6. Orchestrator Limitations

    main

    Users should be aware of the following constraints when using the Orchestrator:

    • No Worktree: The Orchestrator runs on the main branch and does not operate in an isolated worktree.
    • Resource Usage: Each active session consumes system resources (3 processes).
    • Concurrent Agents: Running too many agents simultaneously can impact performance.
    • Manual Merge: While agents perform the work, merging sessions still requires manual review and approval by the user.

  7. Use the dual-terminal setup for agent/human collaboration

    main

    Every Schaltwerk session provides a pair of PTY (Pseudo-Terminal) terminals to allow agents and humans to work side-by-side within the same worktree.

    • Top Terminal (Agent): Runs the configured agent process inside the session's worktree automatically after setup.
    • Bottom Terminal (You): Spawns a regular shell rooted in the same worktree. Use this for manual testing, linting, or quick edits.

    Important Behaviors

    • Persistence: Switching sessions keeps terminals alive; commands continue running in the background.
    • Orchestrator Tab: Unlike sessions, the orchestrator tab uses your repository root (not a worktree), so commands executed there modify your primary branch directly.

  8. Understand Worktree Isolation in Schaltwerk

    main

    Schaltwerk uses dedicated git worktrees located under .schaltwerk/worktrees/ for every session. This provides a sandboxed environment where agents can perform autonomous tasks without affecting your main branch.

    Key Benefits

    • Autonomous execution: Agents can run dependency installs (bun install, pip install, cargo, etc.), migrations, or custom binaries per session without conflicts.
    • Safe experimentation: If a session fails, you can convert it back to a spec (⌘S) or cancel it (⌘D). Both actions delete the session's worktree and branch, ensuring no leftover mess in your primary repository.
    • Parallelism: Multiple agents or humans can work in isolated worktrees simultaneously.
    TIP

    Cleanup regularly: Each worktree is a full copy of the repo. Cancel abandoned sessions to reclaim disk space.

  9. Key Features of Schaltwerk

    main

    Schaltwerk provides several core capabilities for AI-driven development:

    • Isolated Git Worktrees: Every session is assigned a unique branch and worktree.
    • Dual Terminals: Provides an agent terminal on top and your own shell below.
    • Spec-Driven Development: Allows you to plan tasks in markdown before execution.
    • Orchestrator: Enables coordination of multiple sessions from a primary branch (like main or a feature hub).
    • Web Preview: Automatically detects localhost dev servers and allows direct viewing and element inspection within the app.
    • MCP API: Provides a REST API to automate session management.

  10. Data processing and privacy in the Schaltwerk app

    main

    Schaltwerk is designed as a local desktop application. All git operations and session management are performed locally on your device. The application does not collect or transmit any personal data to external servers.

    Note: If you integrate the application with external services (such as GitHub or GitLab), those services' respective privacy policies will apply to the data exchanged with them.

  11. Understand Schaltwerk security and permissions

    main

    Schaltwerk is distributed without official code signing certificates (Apple Developer or EV certificates) to remain free and open-source. It uses ad-hoc signing for basic code integrity.

    Required Permissions:

    • File System Access: Required to read and write session files.
    • Process Spawning: Required to create terminal sessions (PTY).
    • Network Access: Required for the local API server running on port 8547.

    Security Profile:

    • All code is open source and auditable.
    • No external network connections are made; it only communicates via localhost.
    • No telemetry or data collection is performed.
    • Builds are signed via GitHub Actions for transparency.

  12. Use MCP tools to automate session management

    main

    Once the MCP server is connected, AI agents can perform the following tasks via tools:

    • Create Sessions: Create new specs or sessions directly.
    • Update Specs: Modify existing spec content.
    • Start Work: Convert specs into running sessions with worktrees.
    • Check Status: Query all sessions and their current state.
    • Open PR Modal: Request the Create PR dialog (requires user confirmation in the UI).
    • Setup Scripts: Read, inspect, and update worktree setup scripts (e.g., handling .env files).