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
• Keep-awake button (coffee icon) to prevent sleep during long sessions—gray (disabled), green (active), amber (auto-paused when idle)

Sidebar

• Orchestrator entry
• Session filters (Specs/Running/Reviewed)
• Quick actions for starting agents or creating specs
• Collapse/expand: click the toggle button or press ⌘\ / Ctrl+\

Center

• Terminals and diff/review panels
• Grouped per session

Collapse the sidebar to a compact rail for more terminal space or when using the inline diff viewer. Click the toggle button or press ⌘\.

The keep-awake button (coffee icon in top bar) prevents your machine from sleeping during long-running agent tasks. It shows amber when auto-paused because all sessions are idle.

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

Bottom Terminal

Your Shell

• Regular shell rooted in session worktree
• Use for tests, formatting, helper scripts
• Shows Run button when project run script configured
• Press ⌘E to execute run script

Run Mode

Configure a run script via Settings → Run & Environment → Run Script (e.g., bun run dev or npm run dev). Then press ⌘E to launch it—no retyping needed. This lets you quickly verify each agent’s changes: ⌘E → manually test → ⌘E to stop → switch sessions → repeat.

If your app uses fixed ports, consider dynamic port allocation (e.g., PORT=0) so multiple sessions can run dev servers simultaneously without conflicts.

Web Preview

When your run script starts a dev server, click the localhost URL in the terminal to open Schaltwerk’s built-in Web Preview. The preview panel displays your site directly in the app—no browser switching needed. Use the element picker to inspect UI and send HTML snippets to the agent for feedback.

See the full Web Preview guide for URL formats, zoom controls, and element picker details.

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

• Press ⌘G to open the diff viewer
• Toggle Open diffs inline to review in sidebar
• Add comments and send to agent with ⌘Enter

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

Inline Diff Review

Enable Open diffs inline in the Changes tab to review without leaving your terminals:

Click a file to view its diff inline. Select lines to add review comments, then click Finish Review to send all feedback to the agent:

Copy Context for External AI

Use the Copy Context bar to bundle session content for pasting into external AI tools—useful for code reviews, debugging tricky problems with web-based research agents, or leveraging models not available via CLI.

• Spec — include the session’s spec/prompt
• Diff — include unified diffs of changed files
• Files — include full file contents

Select what to include, check the token estimate, and click Copy Context to copy to clipboard.

Mark as Reviewed (Optional)

Marking as reviewed is optional—you can merge or create PRs directly from running sessions.

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 (⌘⇧P)
   • Merge directly (⌘⇧M)
   • 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

   Press ⌘⇧M to merge directly or ⌘⇧P to create a PR. Works from both running and reviewed sessions.

2. Cancel session

   Press ⌘D or click Cancel Session (or enable Auto-cancel after merge)

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.

Need the complete PR workflow (PR context import, PR linking, review-comment tools, branch conflict rules)? See Pull Requests.

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

New Feature

1. Draft detailed spec with requirements and acceptance criteria
2. Start session with focused scope
3. Agent implements feature in isolated worktree
4. Test locally in bottom terminal
5. Review, adjust, and merge when ready

Refactoring

1. Create spec outlining refactoring goals
2. Start session on dedicated branch
3. Agent performs refactoring
4. Verify tests still pass
5. Review changes carefully before merging

Exploration

1. Create spec for experimental approach
2. Start multiple sessions with different strategies
3. Compare results across sessions
4. Keep the best approach, convert the rest back to specs with ⌘S (discarding their worktrees) or cancel entirely