Using Schaltwerk

Day-to-day workflow of running agents, reviewing output, and managing sessions

This guide walks through the daily workflow of creating specs, running agents, reviewing their output, and keeping your repository clean.

First Session Quick Start

1. Open orchestrator

   Press ⌘1 or click orchestrator in sidebar

2. Create spec

   Press ⌘⇧N and describe what you want the agent to build

3. Start session

   Press ⌘N to create worktree, branch, and terminals

4. Monitor agent

   Top terminal shows agent progress automatically

5. Test and review

   Run tests in bottom terminal, then press ⌘R to mark as reviewed

Learn the Layout

Top Bar

• Tabs for each open project
• Gear icon for Settings
• Open button (⌘⇧O) to launch the active worktree or orchestrator branch in your editor/terminal

Sidebar

• Orchestrator entry
• Session filters (All/Specs/Running/Reviewed)
• Quick actions for starting agents or creating specs

Center

• Terminals and diff/review panels
• Grouped per session

Create a Spec

1. Select orchestrator

   Press ⌘1 to work on the main repo branch

2. Create new spec

   Click Create Spec in sidebar footer or press ⌘⇧N

3. Write requirements

   Fill out the markdown prompt with:

   • Requirements
   • Test expectations
   • Acceptance criteria
4. Save for later

   Specs stay in the orchestrator until you promote them

   • Edit anytime
   • Duplicate for variations

Keep specs focused so agents work on small, testable changes.

Start a Session

1. Select spec

   Highlight the spec in the sidebar

2. Start agent

   Click Start Agent or press ⌘N

3. Worktree created

   Schaltwerk creates:

   • New git worktree in .schaltwerk/worktrees/<session-name>/
   • Dedicated branch with project’s branch prefix
   • Two PTY terminals
4. Setup runs

   • Configured worktree setup script runs once
   • When complete, top terminal launches your agent
   • Agent receives the spec content as initial prompt

The session moves to the Running filter and opens two terminals the first time you view it.

Run Your Agent

Top Terminal

Agent Process

• Streams the agent process automatically
• Use Restart action to reload with new prompt/config
• Agent receives spec content as initial instructions

Run Mode

Configure Run Mode via Settings → Run & Environment → Run Script to map ⌘E to a common command:

Use npm run … if you prefer npm instead of bun run … shown below.

Example: Tests

bun run test
# or: npm run test

The bottom terminal shows a status header while the command runs.

Review the Work

Switch Sessions

• ⌘1–9 to jump to specific session
• ⌘↑/⌘↓ to cycle through sessions
• Terminals stay alive when you change focus

Inspect Changes

• View diffs in the right panel
• Leave notes in the spec
• Send instructions through agent terminal

Run Tests

• Execute test suite in bottom terminal
• Or use Run Mode (⌘E)
• Verify before marking as reviewed

External Editor

• Click Open (⌘⇧O) in top bar
• Launches the session worktree (or orchestrator branch) in your chosen app
• Make manual edits or finish tricky changes alongside the agent

Always run tests before marking a session as reviewed!

Mark as Reviewed

1. Verify tests pass

   Run your project’s test suite in the bottom terminal

2. Mark reviewed

   Press ⌘R or click the checkmark action

3. Session moves to Reviewed

   Session badge turns green and appears in Reviewed filter

4. Choose next action

   From session header actions:

   • Create GitHub pull request
   • Merge directly
   • Export branch
   • Continue editing in external editor

Convert Back to a Spec

Need to scrap a run but keep the notes?

Keyboard Shortcut

⌘S

What happens:

• Worktree is removed (all uncommitted changes are lost)
• Session branch is deleted from .schaltwerk/worktrees
• Markdown spec is preserved
• Session returns to Specs filter
• Can be restarted later as a fresh session

Treat the Specs column like a sprint backlog: park exploratory ideas there, restart them with ⌘N, or scrap a run with ⌘S—discarding the worktree while keeping the spec ready for another attempt.

Perfect for deferring work or archiving exploratory sessions.

Merge and Clean Up

1. Merge the branch

   After merging or cherry-picking the reviewed branch:

   • Use GitHub PR flow
   • Or merge directly from command line
2. Cancel session

   Press ⌘D or click Cancel Session

3. Cleanup happens

   • Worktree is removed from .schaltwerk/worktrees/
   • Terminals are closed
   • Session disappears from sidebar
4. Recreate if needed

   You can always recreate from:

   • The spec (if preserved)
   • Git history (if branch still exists)

Schaltwerk never cancels sessions automatically, so it’s safe to keep a branch around while you validate changes.

Master the keyboard shortcuts to speed up your workflow. See the complete Keyboard Shortcuts reference.

Tips for Smooth Sessions

Small Changes

Keep specs focused on small, testable changes that agents can complete confidently

Parallel Work

Use separate sessions for competing implementations and pick the best result

Orchestrator Power

The orchestrator can coordinate multiple agents in parallel while you monitor progress

Iterate Settings

Visit Agent Setup to tweak binaries, environment variables, or project setup scripts

Common Workflows

Bug Fix

1. Create spec describing the bug and expected behavior
2. Start session and let agent investigate
3. Review proposed fix and run tests
4. Mark as reviewed and create PR