> ## Documentation Index
> Fetch the complete documentation index at: https://schaltwerk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow

> Best practices for using Schaltwerk effectively

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

## Core Principles

<CardGroup cols={2}>
  <Card title="One Session Per Feature" icon="layer-group">
    Create a dedicated session for each feature or bugfix. Keep work isolated and manageable.
  </Card>

  <Card title="Review Before Merge" icon="magnifying-glass">
    Always review changes with `⌘G` and test before merging. Agents make mistakes.
  </Card>

  <Card title="Clean Up After Merge" icon="broom">
    Cancel sessions with `⌘D` after successful merge to keep your workspace tidy.
  </Card>

  <Card title="Use the Orchestrator" icon="chess-queen">
    Plan and coordinate work in the orchestrator (`⌘1`) before creating sessions.
  </Card>
</CardGroup>

## Recommended Workflow

### 1. Plan in the Orchestrator

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

<Steps>
  <Step title="Create a spec">
    Press `⌘⇧N` to create a planning document:

    * Break down the feature into tasks
    * List requirements and constraints
    * Document the architecture

          <img src="https://mintcdn.com/schaltwerk/KG1elAstw6eFgx9E/images/create-spec.png?fit=max&auto=format&n=KG1elAstw6eFgx9E&q=85&s=36675a228cb59d6e8030c9b9049e1c8c" alt="Create new spec dialog with agent name field, 'Create as spec' checkbox checked, spec content textarea with user story, and Create Spec button" width="1502" height="960" data-path="images/create-spec.png" />
  </Step>

  <Step title="Ask the orchestrator">
    Use the orchestrator's agent terminal to:

    * Get implementation suggestions
    * Generate task breakdowns
    * Plan the overall approach
  </Step>

  <Step title="Convert to sessions">
    Once you have a plan, create individual sessions for each task

    <img src="https://mintcdn.com/schaltwerk/KG1elAstw6eFgx9E/images/spec-management.png?fit=max&auto=format&n=KG1elAstw6eFgx9E&q=85&s=353ff96104bf1ea711a706b65db45a21" alt="Spec management view showing multiple specs in sidebar with Run Agent and Copy buttons, markdown editor displaying spec content with goals, context, and requirements" width="2214" height="1066" data-path="images/spec-management.png" />
  </Step>
</Steps>

### 2. Create Sessions

For each feature or task:

<Steps>
  <Step title="Press ⌘N">
    Open the New Session dialog
  </Step>

  <Step title="Name it descriptively">
    Use names like:

    * `feature-auth` not `session1`
    * `fix-typescript-errors` not `fixes`
    * `refactor-api-layer` not `refactor`
  </Step>

  <Step title="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"
  </Step>

  <Step title="Select the right agent">
    * **Complex refactoring?** Use Claude Code
    * **Quick fixes?** Use Codex
    * **Experimenting?** Try different agents
  </Step>
</Steps>

<Tip>
  **Working on a complex feature?** Sessions branch from the orchestrator's current branch by default. To have multiple sessions branch from a feature branch instead of `main`:

  * Switch the orchestrator to your feature branch (e.g., `git checkout feature/auth`), or
  * Select the base branch in the New Session dialog

  All sessions then merge back to that feature branch, keeping your work organized.
</Tip>

### 3. Monitor Progress

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="Your Shell (⌘/)">
    Use the bottom terminal to:

    * Run tests as the agent works
    * Check git status with `git status`
    * Inspect changes with `git diff`
    * Run build commands
  </Tab>

  <Tab title="Run Mode (⌘E)">
    If you've configured a run script:

    * Press `⌘E` to start your dev server or test suite
    * Monitor output in real-time
    * Press `⌘E` again to stop
  </Tab>
</Tabs>

### 4. Review Changes

<Steps>
  <Step title="Open the diff (⌘G)">
    Review every change the agent made. Choose your view:

    * **Inline** — Toggle "Open diffs inline" to review in the sidebar without leaving terminals
    * **Modal** — Full-screen diff for detailed inspection

    Check for unintended modifications, commented-out code, or secrets.
  </Step>

  <Step title="Add comments (optional)">
    Select lines in the diff to add review comments, then click **Finish Review** (`⌘Enter`) to send them to the agent. The agent receives formatted feedback and can address each issue.
  </Step>

  <Step title="Check commit history">
    Use the **History** tab to see the commit graph and navigate between commits:

    <img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/history-git-graph.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=6125042eabbc5d95c4a836883df23b6a" alt="History tab showing git graph with commits, branches, and version tags" width="800" height="528" data-path="images/history-git-graph.png" />

    Press `⌘F` to fuzzy-search commits by message, hash, or author.
  </Step>

  <Step title="Run tests">
    In the bottom terminal or with `⌘E`:

    > Swap `bun` for `npm` if you're using npm scripts.

    ```bash theme={null}
    bun run test    # or: npm run test
    bun run lint    # or: npm run lint
    bun run build   # or: npm run build
    ```
  </Step>

  <Step title="Test manually">
    Actually use the feature:

    * Start the dev server
    * Test the happy path
    * Try edge cases
    * Check error handling
  </Step>
</Steps>

### 5. Mark as Reviewed (Optional)

<Steps>
  <Step title="Press ⌘R">
    Marks the session as reviewed
  </Step>

  <Step title="Session moves to Reviewed filter">
    Use `⌘←/→` to switch between All/Specs/Running/Reviewed
  </Step>
</Steps>

### 6. Merge or PR

You can merge from both **Running** and **Reviewed** sessions.

<Tabs>
  <Tab title="Solo Developer">
    Press **`⌘⇧M`** to merge back to the parent branch. Choose your merge strategy:

    <img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/merge-session-modal-squash.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=ab6f04dae3b11da2dc367e9861fae677" alt="Merge Session modal with Squash & fast-forward selected and commit message field" width="1158" height="862" data-path="images/merge-session-modal-squash.png" />

    * **Squash & fast-forward** — combines all commits into one with your message
    * **Reapply commits** — preserves individual commit history

          <img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/merge-modal-reapply-commits.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=a524d1b1c70d82442c267b97f1f3a06e" alt="Merge Session modal with Reapply commits selected" width="1176" height="738" data-path="images/merge-modal-reapply-commits.png" />

    Enable **Auto-cancel after merge** to automatically clean up the session.
  </Tab>

  <Tab title="Team Environment">
    Press **`⌘⇧P`** to create a GitHub PR:

    * Code review from teammates
    * CI/CD validation
    * Discussion and approval process

    **Requirements:**

    * `gh` CLI installed and authenticated
    * Push access to remote repo

    Schaltwerk opens a PR dialog where you choose **Squash changes** vs **Use existing commits**, set title/body/base branch, and optionally push to a custom PR branch name.

    Learn the full workflow (including PR context import and review comments): [Pull Requests](/guides/pull-requests)
  </Tab>
</Tabs>

### 7. Clean Up

After successful merge:

<Steps>
  <Step title="Press ⌘D">
    Cancel the session and remove the worktree
  </Step>

  <Step title="Confirm deletion">
    Schaltwerk asks for confirmation to prevent accidents
  </Step>

  <Step title="Worktree is removed">
    The isolated git worktree and branch are deleted
  </Step>
</Steps>

<Tip>
  Want orchestration playbooks and multi-agent patterns? Jump to the [Advanced Workflows](/guides/advanced-workflows) guide.
</Tip>

## Navigation Tips

<AccordionGroup>
  <Accordion title="Quick Session Switching" defaultOpen>
    * `⌘1` - Orchestrator
    * `⌘2-9` - Sessions 1-8
    * `⌘↑/↓` - Cycle through sessions in current filter
  </Accordion>

  <Accordion title="Filter Views" defaultOpen>
    * `⌘←/→` - Switch between All/Specs/Running/Reviewed
    * See exactly what you need when you need it
  </Accordion>

  <Accordion title="Multi-Project Workflows" defaultOpen>
    * `⌘⇧←/→` - Switch between project tabs
    * Perfect for frontend ↔ backend workflows
    * See the [multi-project guide](/guides/multi-project) for full tips
  </Accordion>

  <Accordion title="Terminal Focus" defaultOpen>
    * `⌘T` - Focus agent terminal
    * `⌘/` - Focus your shell
    * `⌘E` - Run configured script
  </Accordion>
</AccordionGroup>

## 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

<Warning>
  **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
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Keyboard Shortcuts" icon="keyboard" href="/guides/keyboard-shortcuts">
    Master all keyboard shortcuts
  </Card>

  <Card title="Agent Setup" icon="robot" href="/guides/agent-setup">
    Configure agents and environment
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts">
    Understand the architecture
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Fix common issues
  </Card>
</CardGroup>