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 Applications or via terminal:

   open -a Schaltwerk
   

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

   Describe what you want the agent to build:

   • “Add user authentication”
   • “Fix TypeScript errors”
   • “Refactor the database layer”

   This becomes the initial prompt for your agent

3. Select your agent

   Choose which agent to use:

   • 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

   • 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. Press ⌘G

   Opens the Diff Viewer showing all changes the agent made

   
2. Review the diff

   • See which files were modified
   • Review line-by-line changes
   • Add comments if needed
   • Press ⌘F to search within the diff
3. 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

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