> ## 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.
# 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
Open the app from your applications menu, or via terminal:
**macOS:**
```bash theme={null}
open -a Schaltwerk
```
**Windows:** Launch from Start menu or double-click the desktop shortcut
**Linux:**
```bash theme={null}
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.
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.
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](https://git-scm.com/docs/git-worktree) with its own branch.
This opens the **New Session** dialog
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.
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](/guides/agent-setup) for details. Terminal Only mode doesn't require configuration.
Select which branch the session should start from (usually `main` or `develop`)
Schaltwerk will:
1. Create a new git branch named `schaltwerk/`
2. Create an isolated [git worktree](https://git-scm.com/docs/git-worktree) at `.schaltwerk/worktrees//`
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.
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
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
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):
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.
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.
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.
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:
This marks the session as **Reviewed**
The session moves to the "Reviewed" filter in the sidebar
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
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
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](/guides/pull-requests)
## Clean Up
After merging, clean up the session:
Cancels the session and removes the worktree
This is destructive! Only cancel after successfully merging.
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
Learn best practices for daily use
Master the keyboard-driven workflow
Configure agents, environment variables, and run mode
Understand sessions, specs, and the orchestrator