Workflow

Best practices for using Schaltwerk effectively

Here are our recommendations for how to get the most out of Schaltwerk.

Core Principles

One Session Per Feature

Create a dedicated session for each feature or bugfix. Keep work isolated and manageable.

Review Before Merge

Always review changes with ⌘G and test before merging. Agents make mistakes.

Clean Up After Merge

Cancel sessions with ⌘D after successful merge to keep your workspace tidy.

Use the Orchestrator

Plan and coordinate work in the orchestrator (⌘1) before creating sessions.

Recommended Workflow

1. Plan in the Orchestrator

Press ⌘1 to switch to the orchestrator—a special session that stays on your main branch.

1. Create a spec

   Press ⌘⇧N to create a planning document:

   • Break down the feature into tasks

   • List requirements and constraints

   • Document the architecture

     
2. Ask the orchestrator

   Use the orchestrator’s agent terminal to:

   • Get implementation suggestions
   • Generate task breakdowns
   • Plan the overall approach
3. Convert to sessions

   Once you have a plan, create individual sessions for each task

   

2. Create Sessions

For each feature or task:

1. Press ⌘N

   Open the New Session dialog

2. Name it descriptively

   Use names like:

   • feature-auth not session1
   • fix-typescript-errors not fixes
   • refactor-api-layer not refactor
3. Write a clear prompt

   Be specific about what you want:

   Good:

   “Add JWT-based authentication with login, logout, and token refresh endpoints. Use bcrypt for password hashing.”

   Bad:

   “Add auth”

4. Select the right agent

   • Complex refactoring? Use Claude Code
   • Quick fixes? Use Codex
   • Experimenting? Try different agents

3. Monitor Progress

Agent Terminal (⌘T)

Watch the agent work in real-time:

• See which files it’s reading
• Understand its reasoning
• Spot issues early

Tip: You can interact with the agent while it works. Just type in the terminal.

4. Review Changes

Before marking as reviewed:

1. Open the diff (⌘G)

   Review every change the agent made:

   • Check for unintended modifications
   • Look for commented-out code
   • Verify no secrets were added
2. Run tests

   In the bottom terminal or with ⌘E:

   Swap bun for npm if you’re using npm scripts.

   bun run test    # or: npm run test
   bun run lint    # or: npm run lint
   bun run build   # or: npm run build
   

3. Test manually

   Actually use the feature:

   • Start the dev server
   • Test the happy path
   • Try edge cases
   • Check error handling

5. Mark as Reviewed

When you’re confident:

1. Press ⌘R

   Marks the session as reviewed

2. Session moves to Reviewed filter

   Use ⌘←/→ to switch between All/Specs/Running/Reviewed

6. Merge or PR

Solo Developer

Press ⌘⇧M to merge directly to main:

• Fast and simple
• No PR overhead
• Good for personal projects

Make sure you reviewed and tested first!

7. Clean Up

After successful merge:

1. Press ⌘D

   Cancel the session and remove the worktree

2. Confirm deletion

   Schaltwerk asks for confirmation to prevent accidents

3. Worktree is removed

   The isolated git worktree and branch are deleted

Want orchestration playbooks and multi-agent patterns? Jump to the Advanced Workflows guide.

Navigation Tips

Quick Session Switching

• ⌘1 - Orchestrator
• ⌘2-9 - Sessions 1-8
• ⌘↑/↓ - Cycle through sessions in current filter

Filter Views

• ⌘←/→ - Switch between All/Specs/Running/Reviewed
• See exactly what you need when you need it

Multi-Project Workflows

• ⌘⇧←/→ - Switch between project tabs
• Perfect for frontend ↔ backend workflows
• See the multi-project guide for full tips

Terminal Focus

• ⌘T - Focus agent terminal
• ⌘/ - Focus your shell
• ⌘E - Run configured script

Common Patterns

Feature Development

1. ⌘1 (Orchestrator) → Plan the feature
2. ⌘⇧N → Create spec with requirements
3. ⌘N → Start session with detailed prompt
4. ⌘T → Monitor agent progress
5. ⌘G → Review changes
6. ⌘E → Run tests
7. ⌘R → Mark as reviewed
8. ⌘⇧P → Create PR
9. [After merge] ⌘D → Clean up

Bug Fix

1. ⌘N → Create session: "Fix bug in X"
2. ⌘/ → Reproduce the bug manually
3. ⌘T → Let agent investigate and fix
4. ⌘/ → Verify the fix works
5. ⌘G → Review the changes
6. ⌘R → Mark reviewed
7. ⌘⇧M → Merge directly (if solo)
8. ⌘D → Clean up

Refactoring

1. ⌘1 → Discuss approach with orchestrator
2. ⌘⇧N → Create spec documenting the refactor plan
3. ⌘N → Start session with clear constraints
4. ⌘T → Watch agent work
5. ⌘E → Run test suite frequently
6. ⌘G → Carefully review all changes
7. ⌘/ → Run tests again manually
8. ⌘R → Mark reviewed
9. ⌘⇧P → Create PR for team review
10. [After approval + merge] ⌘D → Clean up

Things to Avoid

Don’t:

• Merge without reviewing (⌘G first!)
• Cancel sessions before merging (use ⌘S to recycle the spec—this deletes the session worktree/branch and loses uncommitted changes)
• Create vague prompts like “fix it”
• Forget to run tests before marking reviewed
• Let sessions pile up—clean up after merging
• Work directly in the orchestrator for features (create sessions instead)

Next Steps

Keyboard Shortcuts

Master all keyboard shortcuts

Agent Setup

Configure agents and environment

Core Concepts

Understand the architecture

Troubleshooting

Fix common issues