Skip to main content
When Claude Code has MCP access to Schaltwerk, you can manage sessions using natural language.

​
What You Can Ask

You: “Create a Schaltwerk spec to add user authentication with JWT tokens”Claude: Creates a spec with the task description, ready to start when you’re ready
You: “Which Schaltwerk sessions are ready for review?”Claude: Lists all reviewed sessions that need your attention
You: “Start the user-auth spec in Schaltwerk”Claude: Converts the spec to a running session with worktree
You: “What Schaltwerk specs should I prioritize?”Claude: Reviews your specs and suggests what to work on based on dependencies and importance
You: “Merge the user-auth session to main”Claude: Checks the session is reviewed, runs tests, and merges if everything passes

​
Example Workflows

​
1. Creating Multiple Specs

You: “I need to build a complete authentication system. Create Schaltwerk specs for each part.” Claude creates:
  • auth-registration - User signup with validation
  • auth-login - Login with JWT tokens
  • auth-password-reset - Password reset flow
  • auth-session-management - Token refresh and logout

​
2. Starting Work

You: “Which spec should I start first?” Claude: “Start with auth-registration since the other specs depend on it. Shall I start this session for you?” You: “Yes, start it” Claude: Starts the session - now visible in your sidebar

​
3. Reviewing Progress

You: “Show me the status of all auth sessions” Claude:
  • auth-registration - ✅ Reviewed, ready to merge
  • auth-login - 🔄 Running
  • auth-password-reset - 📝 Spec (not started)
  • auth-session-management - 📝 Spec (not started)

​
4. Browsing Specs Before Starting

You: “List the specs in this project with their sizes” Claude: Uses schaltwerk_spec_list to return something like:
  • auth-password-reset — 1.2 KB (updated 2 minutes ago)
  • auth-session-management — 3.6 KB (updated yesterday)
You: “Open the full markdown for auth-password-reset” Claude: Calls schaltwerk_spec_read and shows the spec content so you can review it before starting work.

​
5. Merging Work

You: “The auth-registration session looks good. Merge it to main.” Claude:
  1. Checks tests pass
  2. Verifies no conflicts
  3. Merges to main
  4. Cleans up the session

​
Best Prompts

Be Specific

“Create a spec for OAuth login with Google and GitHub”vs ❌ “Add OAuth”

Mention Files

“Fix the validation bug in src/auth/validator.js”vs ❌ “Fix the bug”

Set Context

“Add error handling to all API endpoints in the payment module”vs ❌ “Add error handling”

Ask for Help

“What’s the best way to organize these features into sessions?”Claude can suggest how to structure your work

​
Next Steps

MCP Setup

Set up Claude Code with MCP

Using Schaltwerk

Learn the workflow