Your First Session

Create and run your first AI agent in Schaltwerk

Once you’ve installed Schaltwerk, it’s time to create your first session.

Open Your Repository

1. Launch Schaltwerk

   Open the app from your applications menu, or via terminal:

   macOS:

   open -a Schaltwerk
   

   Windows: Launch from Start menu or double-click the desktop shortcut

   Linux:

   schaltwerk
   

   Prefer the CLI? Running schaltwerk always lands on the Home screen first. Pick a repository manually every time—no project is auto-selected on startup.

2. Open a project

   On the Home screen, click Open Repository and select your Git repository.

   Schaltwerk verifies that the folder is a valid Git repository before opening it.
3. Recent Projects

   The project is added to Recent Projects for quick access next time

Alternative: Click New Project to create a new empty Git repository

Create a Session

Sessions are where AI agents work. Each session runs in its own isolated git worktree with its own branch.

1. Press ⌘N

   This opens the New Session dialog

   
2. Enter a task description

   Choose your prompt source:

   • Custom prompt — Write your own task description

   • GitHub issue — Import an issue with its description, labels, and comments

   • GitHub PR — Import a PR with its context and discussion

     

   GitHub import requires the gh CLI to be installed and authenticated. The issue/PR content becomes the agent’s initial prompt.

3. Select your agent

   Choose which agent to use:

   • GitHub Copilot - Great for iterative tasks; requires npm install -g @github/copilot and trusting the worktree once

   • Claude Code - Best for complex refactoring and understanding large codebases

   • OpenCode - Open-source option

   • Codex - Fast, efficient, great for smaller tasks

   • Gemini - Alternative AI assistant

   • Kilo Code - Powerful CLI with architect and autonomous modes

   • Qwen - Alibaba’s advanced AI coding assistant

   • Factory Droid - Specialized agent for code generation and automation

   • Amp - Advanced coding agent with powerful tools

   • Terminal Only - Manual work without AI agents, opens only a usable terminal

     For AI agents, make sure you’ve configured them in Settings. See Agent Setup for details. Terminal Only mode doesn’t require configuration.
4. Choose base branch

   Select which branch the session should start from (usually main or develop)

5. Press ⌘Enter to start

   Schaltwerk will:

   1. Create a new git branch named schaltwerk/<session-name>

   2. Create an isolated git worktree at .schaltwerk/worktrees/<session-name>/

   3. Spawn two terminals (agent terminal on top, your shell below)

   4. Start the agent with your task description

      

Watch Your Agent Work

The agent appears in the sidebar and starts working immediately.

Top Terminal (Agent)

Shows the AI agent’s output in real-time. Watch as it:

• Reads and understands your codebase
• Makes edits across multiple files
• Runs tests and validates changes

Press ⌘T to focus this terminal

Bottom Terminal (Your Shell)

Your personal shell in the session’s worktree. Use it to:

• Run tests manually
• Inspect changes with git diff
• Execute build commands

Press ⌘/ to focus this terminal

Run Mode

Configure a run script in Settings → Run & Environment → Run Script, then press ⌘E to execute it in the bottom terminal.

Perfect for starting dev servers, running test suites, or building the project.

Review Changes

Once the agent is done (or you want to check progress):

1. Open the diff

   Press ⌘G to view all changes the agent made. The Changes tab shows all modified files with line counts:

   

   Toggle Open diffs inline to review directly in the sidebar, or leave it off to open a full-screen modal.

2. Review inline

   Click a file to open its diff. With inline mode enabled, the diff opens right in the sidebar—no context switching. Click Back to List to return to the file list.

   
3. Add review comments

   Select lines in the diff (click the + icons on the left) to add comments:

   • Type your feedback in the comment form
   • Click Submit to add the comment
   • Click Finish Review (or ⌘Enter) to send all comments to the agent terminal

   The agent receives your formatted feedback and can address each issue.

4. Test the changes

   Use the bottom terminal (⌘/) or Run Mode (⌘E) to:

   • Run your test suite
   • Start the dev server
   • Verify the changes work as expected

Mark as Reviewed

When you’re satisfied with the changes:

1. Press ⌘R

   This marks the session as Reviewed

   The session moves to the “Reviewed” filter in the sidebar

   
2. Session is ready for merge

   You can now:

   • Merge to main with ⌘⇧M
   • Create a PR with ⌘⇧P
   • Continue working on it (edit files, run more commands)

Merge or Create PR

Merge to Main

Press ⌘⇧M to merge directly to your base branch.

Schaltwerk will:

1. Switch to the base branch
2. Merge the session branch
3. Push changes (if configured)

Only use direct merge if you’re working solo or on trusted changes

Create Pull Request

Press ⌘⇧P to create a GitHub PR.

Requirements:

• GitHub CLI (gh) installed and authenticated

• Connected project + push access to origin

  

Schaltwerk opens a PR dialog where you can choose a strategy (Squash changes vs Use existing commits), adjust the title/body, pick a base branch, and optionally push to a custom PR branch name.

See the full PR guide (including linking PRs and fetching review comments): Pull Requests

Clean Up

After merging, clean up the session:

1. Press ⌘D

   Cancels the session and removes the worktree

   This is destructive! Only cancel after successfully merging.
2. Confirm deletion

   Schaltwerk will ask for confirmation before removing the worktree

Want to keep the plan but scrap the current run? Press ⌘S to convert the session back to a spec—this deletes the session worktree and branch (uncommitted changes are lost) while preserving the markdown so you can relaunch later.

Next Steps

Workflow Guide

Learn best practices for daily use

Keyboard Shortcuts

Master the keyboard-driven workflow

Agent Setup

Configure agents, environment variables, and run mode

Core Concepts

Understand sessions, specs, and the orchestrator