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

# Sessions & Specs

> Learn how sessions, specs, and lifecycle states work together

Schaltwerk revolves around isolated git worktrees and the lifecycle of each AI-driven session. This page covers how sessions and specs move between states, how the orchestrator supports planning, and how to reuse specs as a backlog.

## Sessions

<Card title="What is a Session?" icon="laptop-code">
  Every running session is a dedicated git worktree branching from your repository. Two terminals come with each session so agents and humans can work side-by-side.
</Card>

<CardGroup cols={2}>
  <Card title="Isolated Worktrees" icon="git-alt">
    Each session gets its own git worktree and branch
  </Card>

  <Card title="Dual Terminals" icon="terminal">
    Top terminal for the agent, bottom terminal for manual commands
  </Card>

  <Card title="Instant Switching" icon="arrows-rotate">
    Switch between sessions instantly—terminals stay alive in the background
  </Card>

  <Card title="Sidebar Organization" icon="list">
    Sessions appear in the left sidebar under **Agents**
  </Card>
</CardGroup>

<Tip>
  Every worktree is its own copy of the repository on disk. Keep sessions short-lived and clean up finished work so the `.schaltwerk/worktrees/` folder doesn't grow without bound.
</Tip>

### Renaming Sessions

Double-click on a session name in the sidebar to rename it. The git branch will be updated to match the new name.

### Session Filters

Use the tabs at the top of the session list to filter what you see:

<Tabs>
  <Tab title="All">
    Shows all sessions regardless of state
  </Tab>

  <Tab title="Specs">
    Shows only draft specs (amber badge)
  </Tab>

  <Tab title="Running">
    Shows active sessions with worktrees
  </Tab>

  <Tab title="Reviewed">
    Shows sessions marked as ready for merge
  </Tab>
</Tabs>

## Specs

<img src="https://mintcdn.com/schaltwerk/OBiABllJ_V8SyWeQ/logo/specs-workflow.svg?fit=max&auto=format&n=OBiABllJ_V8SyWeQ&q=85&s=8114f806bd53fe4f33bfb533077153a9" alt="Specs workflow" className="w-full max-w-4xl mx-auto my-8" width="720" height="220" data-path="logo/specs-workflow.svg" />

<CardGroup cols={2}>
  <Card title="Markdown Planning" icon="file-lines">
    Specs are markdown documents that live in the orchestrator
  </Card>

  <Card title="Capture Intent" icon="lightbulb">
    Capture the desired outcome before any code is written
  </Card>

  <Card title="Agent Prompts" icon="message">
    When started, the spec becomes the agent's first prompt
  </Card>

  <Card title="Amber Badge" icon="bookmark">
    Specs carry an amber badge until you start them
  </Card>
</CardGroup>

<Info>
  Think of specs as reusable backlog cards. Start them when you're ready, and if a session isn't working out, press `⌘S` to discard the worktree, keep the spec intact, and retry later with new instructions.
</Info>

### Spec Lifecycle

<Steps>
  <Step title="Draft the spec">
    Write a markdown document describing the desired outcome
  </Step>

  <Step title="Start the session">
    Convert the spec into a running session with worktree and terminals
  </Step>

  <Step title="Agent receives prompt">
    The spec content becomes the agent's initial instructions
  </Step>
</Steps>

## Orchestrator

<Card title="The Control Panel" icon="tower-control" color="#22d3ee">
  The orchestrator runs directly on your primary branch—typically `main`, but it can be a long-lived feature branch too—giving you a stable workspace for planning and coordination.
</Card>

### Orchestrator Features

<AccordionGroup>
  <Accordion title="Spec Creation">
    Draft multiple specs before launching sessions. Perfect for planning parallel work streams.
  </Accordion>

  <Accordion title="MCP REST API">
    The orchestrator powers automation through the MCP REST API, enabling external tools to create and manage sessions.
  </Accordion>

  <Accordion title="Dual Terminals">
    Like regular sessions, the orchestrator has an agent terminal on top and your shell below.
  </Accordion>
</AccordionGroup>

<Warning>
  Because the orchestrator operates inside your primary branch (no separate worktree), any commands you run there change that branch immediately. Use specs and sessions when you need isolation.
</Warning>

### Accessing the Orchestrator

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

  ```plaintext Sidebar theme={null}
  Click "Repository (Orchestrator)" at the top of the sidebar
  ```
</CodeGroup>

## Session States

<Steps>
  <Step title="Spec" icon="file-pen">
    **Drafting the work.** No worktree yet.

    * Markdown document in the orchestrator
    * Amber badge in sidebar
    * Can be edited or deleted without affecting git
  </Step>

  <Step title="Running" icon="play">
    **Active session.** The session owns a worktree and active terminals.

    * Git worktree created under `.schaltwerk/worktrees/`
    * Two PTY terminals spawned
    * Agent process can run in top terminal
    * Magenta badge in sidebar
  </Step>

  <Step title="Reviewed" icon="check">
    **Ready for merge.** The worktree is ready for integration.

    * Code has been tested locally
    * Green badge in sidebar
    * Can still make manual edits in worktree
    * Integration options:
      * `⌘⇧M` - Direct merge to main
      * `⌘⇧P` - Create GitHub pull request
  </Step>
</Steps>

### State Transitions

<Info>
  Transitions are explicit and user-controlled. The app never automatically changes session states.
</Info>

<Tabs>
  <Tab title="Spec → Running">
    **Keyboard:** `⌘N`

    **Action:** Start Agent

    **Result:** Creates worktree, branch, and terminals
  </Tab>

  <Tab title="Running → Reviewed">
    **Keyboard:** `⌘R`

    **Action:** Mark as Reviewed

    **Result:** Flags session as ready for merge
  </Tab>

  <Tab title="Running → Spec">
    **Action:** Convert to Spec

    **Result:** Removes worktree but keeps spec content for later
  </Tab>
</Tabs>

### Lifecycle Scenarios

<img src="https://mintcdn.com/schaltwerk/AdXE2rE9dSXuzidH/images/spec_to_integration.png?fit=max&auto=format&n=AdXE2rE9dSXuzidH&q=85&s=6694eee32f10424dc2418dbf908656ca" alt="Lifecycle diagram showing three scenarios: green flow for a successful PDF Generation spec moving from Specs → Running → Reviewed → Merged; blue flow for a Fix Bug spec that returns to Specs; red flow for an Implement Email experiment that is archived with recovery available from settings." width="3200" height="1528" data-path="images/spec_to_integration.png" />

<Steps>
  <Step title="Ship it (green)">
    PDF Generation represents the happy path: draft the spec, run the session, review the work, then merge via PR or `⌘⇧M`.
  </Step>

  <Step title="Retry later (blue)">
    Fix Bug shows how to convert a running session back into a spec when the change is deferred—the worktree and session branch are deleted (uncommitted work is lost) but the plan stays in the backlog for another attempt.
  </Step>

  <Step title="Archive experiments (red)">
    Implement Email demonstrates cancelling a session you no longer need. The worktree is removed and the session moves to the archive, which you can recover from **Settings → Archive** if you change your mind.
  </Step>
</Steps>

***

Next: [Worktrees & Terminals](/core-concepts/worktrees-and-terminals)