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

# 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

<Steps>
  <Step title="Open orchestrator">
    Press `⌘1` or click **orchestrator** in sidebar
  </Step>

  <Step title="Create spec">
    Press `⌘⇧N` and describe what you want the agent to build
  </Step>

  <Step title="Start session">
    Press `⌘N` to create worktree, branch, and terminals
  </Step>

  <Step title="Monitor agent">
    Top terminal shows agent progress automatically
  </Step>

  <Step title="Test and review">
    Run tests in bottom terminal, then press `⌘R` to mark as reviewed
  </Step>
</Steps>

## Learn the Layout

<CardGroup cols={3}>
  <Card title="Top Bar" icon="bars">
    * 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)
  </Card>

  <Card title="Sidebar" icon="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+\`
  </Card>

  <Card title="Center" icon="window">
    * Terminals and diff/review panels
    * Grouped per session
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Select orchestrator">
    Press `⌘1` to work on the main repo branch
  </Step>

  <Step title="Create new spec">
    Click **Create Spec** in sidebar footer or press `⌘⇧N`
  </Step>

  <Step title="Write requirements">
    Fill out the markdown prompt with:

    * Requirements
    * Test expectations
    * Acceptance criteria
  </Step>

  <Step title="Save for later">
    Specs stay in the orchestrator until you promote them

    * Edit anytime
    * Duplicate for variations
  </Step>
</Steps>

<Tip>
  Keep specs focused so agents work on small, testable changes.
</Tip>

## Start a Session

<Steps>
  <Step title="Select spec">
    Highlight the spec in the sidebar
  </Step>

  <Step title="Start agent">
    Click **Start Agent** or press `⌘N`
  </Step>

  <Step title="Worktree created">
    Schaltwerk creates:

    * New git worktree in `.schaltwerk/worktrees/<session-name>/`
    * Dedicated branch with project's branch prefix
    * Two PTY terminals
  </Step>

  <Step title="Setup runs">
    * Configured worktree setup script runs once
    * When complete, top terminal launches your agent
    * Agent receives the spec content as initial prompt
  </Step>
</Steps>

<Info>
  The session moves to the **Running** filter and opens two terminals the first time you view it.
</Info>

## Run Your Agent

<Tabs>
  <Tab title="Top Terminal">
    <Card icon="robot" color="#ec4899">
      **Agent Process**

      * Streams the agent process automatically
      * Use **Restart** action to reload with new prompt/config
      * Agent receives spec content as initial instructions
    </Card>
  </Tab>

  <Tab title="Bottom Terminal">
    <Card icon="terminal" color="#22c55e">
      **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
    </Card>
  </Tab>
</Tabs>

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

<img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/run-terminal-view.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=0c60b022a4f0780f6b27728930a7b4d2" alt="Run tab showing command execution with Stop button" width="1784" height="570" data-path="images/run-terminal-view.png" />

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

### 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](/guides/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.

<Info>
  See the full [Web Preview guide](/guides/web-preview) for URL formats, zoom controls, and element picker details.
</Info>

## Review the Work

<CardGroup cols={2}>
  <Card title="Switch Sessions" icon="arrows-rotate">
    * `⌘1–9` to jump to specific session
    * `⌘↑/⌘↓` to cycle through sessions
    * Terminals stay alive when you change focus
  </Card>

  <Card title="Inspect Changes" icon="code-compare">
    * Press `⌘G` to open the diff viewer
    * Toggle **Open diffs inline** to review in sidebar
    * Add comments and send to agent with `⌘Enter`
  </Card>

  <Card title="Run Tests" icon="flask">
    * Execute test suite in bottom terminal
    * Or use Run Mode (`⌘E`)
    * Verify before marking as reviewed
  </Card>

  <Card title="External Editor" icon="code">
    * 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
  </Card>
</CardGroup>

### Inline Diff Review

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

<img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/inline-sidebar-diff.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=36ad9ff45b01a2794ad52c20817f2812" alt="Changes tab showing file list with inline checkbox and line counts" width="1024" height="710" data-path="images/inline-sidebar-diff.png" />

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:

<img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/inline-sidebar-comment.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=e427414416ab0bb028e5b3da0071a527" alt="Inline diff with review comment form" width="1390" height="1134" data-path="images/inline-sidebar-comment.png" />

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

<img src="https://mintcdn.com/schaltwerk/f6q1RM8xeBMiAfLz/images/copy-content-split-bar.png?fit=max&auto=format&n=f6q1RM8xeBMiAfLz&q=85&s=5726524de47f91c3fd101f95647283c0" alt="Copy Context bar showing Spec and Diff toggles, file count, token estimate, and Copy Context button" width="924" height="148" data-path="images/copy-content-split-bar.png" />

* **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.

<Steps>
  <Step title="Verify tests pass">
    Run your project's test suite in the bottom terminal
  </Step>

  <Step title="Mark reviewed">
    Press `⌘R` or click the checkmark action
  </Step>

  <Step title="Session moves to Reviewed">
    Session badge turns green and appears in **Reviewed** filter
  </Step>

  <Step title="Choose next action">
    From session header actions:

    * Create GitHub pull request (`⌘⇧P`)
    * Merge directly (`⌘⇧M`)
    * Continue editing in external editor
  </Step>
</Steps>

## Convert Back to a Spec

Need to scrap a run but keep the notes?

<CodeGroup>
  ```bash Keyboard Shortcut theme={null}
  ⌘S
  ```
</CodeGroup>

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

<Tip>
  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.
</Tip>

<Info>
  Perfect for deferring work or archiving exploratory sessions.
</Info>

## Merge and Clean Up

<Steps>
  <Step title="Merge the branch">
    Press `⌘⇧M` to merge directly or `⌘⇧P` to create a PR. Works from both running and reviewed sessions.
  </Step>

  <Step title="Cancel session">
    Press `⌘D` or click **Cancel Session** (or enable **Auto-cancel after merge**)
  </Step>

  <Step title="Cleanup happens">
    * Worktree is removed from `.schaltwerk/worktrees/`
    * Terminals are closed
    * Session disappears from sidebar
  </Step>

  <Step title="Recreate if needed">
    You can always recreate from:

    * The spec (if preserved)
    * Git history (if branch still exists)
  </Step>
</Steps>

<Check>
  Schaltwerk never cancels sessions automatically, so it's safe to keep a branch around while you validate changes.
</Check>

<Tip>
  Need the complete PR workflow (PR context import, PR linking, review-comment tools, branch conflict rules)? See [Pull Requests](/guides/pull-requests).
</Tip>

<Tip>
  Master the keyboard shortcuts to speed up your workflow. See the complete [Keyboard Shortcuts](/guides/keyboard-shortcuts) reference.
</Tip>

## Tips for Smooth Sessions

<CardGroup cols={2}>
  <Card title="Small Changes" icon="arrows-split-up-and-left">
    Keep specs focused on small, testable changes that agents can complete confidently
  </Card>

  <Card title="Parallel Work" icon="bars-staggered">
    Use separate sessions for competing implementations and pick the best result
  </Card>

  <Card title="Orchestrator Power" icon="tower-control">
    The orchestrator can coordinate multiple agents in parallel while you monitor progress
  </Card>

  <Card title="Iterate Settings" icon="gear">
    Visit [Agent Setup](/guides/agent-setup) to tweak binaries, environment variables, or project setup scripts
  </Card>
</CardGroup>

## Common Workflows

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

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

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

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