Agent Setup

Configure agent binaries, environment variables, setup scripts, and run mode

Configure each agent from Settings → Agent Configuration before you launch sessions. Open Settings by clicking the gear icon in the top bar.

Commands in this guide use bun. Swap to npm equivalents (npm run …, npm install, etc.) if that’s your default toolchain.

Settings are saved locally in ~/Library/Application Support/schaltwerk/settings.json (plain JSON). Keep this file protected if you store API keys.

Storage Locations

Global Settings

Location: ~/Library/Application Support/schaltwerk/settings.json

Contains:

• Agent binaries
• CLI arguments
• Agent-specific environment variables
• Personal defaults

Project Settings

Location: ~/Library/Application Support/schaltwerk/<project>/database.db

Contains:

• Worktree setup scripts
• Project environment variables
• Run scripts
• Session state

Changes only apply after you click Save in the bottom-right corner of the Settings modal.

Choose the Agent Binary

1. Select agent tab

   Choose from: Claude Code, OpenCode, Codex, Gemini, Qwen, Factory Droid, Amp, or Terminal

2. Pick binary

   • Select a detected binary from the dropdown
   • Or paste an absolute path for custom builds
   • For Terminal mode: No binary required (uses system shell)
3. Verify details

   Schaltwerk shows:

   • Installation method
   • Version number
   • Full path to executable

Terminal-Only Mode

Terminal mode opens a session with just your default system shell - no AI agent is started automatically.

Use Cases:

• Running custom agents manually
• Custom development workflows
• Testing commands in isolated worktrees
• Manual code exploration

How It Works:

• Creates an isolated Git worktree (same as other sessions)
• Opens top terminal with your default shell ($SHELL)
• No agent binary required
• Initial prompt is not pasted automatically
• Environment variables and setup scripts still apply

Configuration:

• Binary: None required (Terminal uses system shell)
• CLI Arguments: Not applicable for Terminal mode
• Environment Variables: Supported - configure in Settings
• Setup Scripts: Supported - runs before terminal opens

Terminal mode is perfect for running agents not yet integrated into Schaltwerk, or for custom development workflows that don’t require AI assistance.

Common Binary Locations

Claude Code (Homebrew)

/opt/homebrew/bin/claude

Schaltwerk auto-detects common installation paths. If your binary isn’t listed, paste the absolute path.

Add Custom CLI Arguments

Use the CLI Arguments field to append extra flags to the launch command.

Argument Parsing

Arguments are parsed with shell-style quoting:

Profile Selection

--profile work

Codex launches are normalized automatically (single-dash long flags are fixed and profiles come before --model).

When Arguments Apply

CLI arguments are appended:

• Every time the top terminal starts
• When you trigger a restart from the session toolbar
• After the setup script completes

Set Agent Environment Variables

Add key/value pairs for the agent terminal (API keys, profile names, feature flags).

Key points:

• Variables are scoped per agent type (Claude Code doesn’t see Codex vars, Factory Droid stays isolated)
• Merged with project-level variables at agent start
• Stored unencrypted - rotate keys on shared machines
• Use Edit variables button for bulk editing

Example Variables:

API Keys

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Project Defaults

Open Settings → Run & Environment to configure shared defaults for every session.

Worktree Setup Script

One-Time Initialization

Runs once when Schaltwerk creates a new worktree. Perfect for dependency installation, environment setup, and project bootstrapping.

Available Environment Variables

Session Variables

$WORKTREE_PATH   # /path/to/repo/.schaltwerk/worktrees/session-name
$REPO_PATH       # /path/to/repo
$SESSION_NAME    # session-name
$BRANCH_NAME     # schaltwerk/session-name

Common Setup Tasks

Copy Environment Files

#!/bin/bash
cp "$REPO_PATH/.env.template" "$WORKTREE_PATH/.env"
echo "SESSION_NAME=$SESSION_NAME" >> "$WORKTREE_PATH/.env"

Execution:

• Runs in top terminal before agent launches
• Creates .schaltwerk/setup.done marker (delete to force re-run)
• Optional - leave empty if not needed

If the setup script fails, the agent won’t start. Check the top terminal for errors.

Project Environment Variables

Added to every agent launch. Perfect for configuration shared by all agents.

Benefits: Set once, available everywhere. Agent vars + Project vars = Final environment.

Example:

Shared API Keys

DATABASE_URL=postgres://localhost/dev
REDIS_URL=redis://localhost:6379

Run Script (⌘E)

Define a command to execute with ⌘E in the bottom terminal.

Configuration: Set command (e.g., bun run dev / npm run dev), optional working directory, optional environment variables.

Features: Real-time output, exit status display, press ⌘E again to stop.

Common examples: bun run dev / npm run dev, bun run test / npm run test, bun run build / npm run build, bun run lint / npm run lint

Recommended Setup Flow

1. Configure project settings

   1. Open Settings → Run & Environment
   2. Add project environment variables
   3. Write worktree setup script
   4. Define run script for ⌘E
2. Configure agents

   1. Open Settings → Agent Configuration
   2. For each agent you use:
      • Select binary path
      • Add CLI arguments
      • Set agent-specific environment variables
3. Test with a session

   1. Create a test spec
   2. Start session (⌘N)
   3. Verify setup script runs successfully
   4. Check agent launches with correct configuration
4. Verify run mode

   1. Press ⌘E in bottom terminal
   2. Confirm run script executes correctly
   3. Check environment variables are present

Once configured, every new session will automatically use these settings!

Troubleshooting

Agent won't start

Check:

• Binary path is correct and executable
• Agent has necessary permissions
• CLI arguments are valid
• Environment variables are set correctly

Debug:

• Look at top terminal output for error messages
• Try running binary manually from command line

Setup script fails

Check:

• Script has execute permissions
• All required dependencies are available
• Environment variables are accessible

Debug:

• Check top terminal for error output
• Run script manually with same environment
• Verify marker file isn’t preventing re-run

Environment variables not visible

Check:

• Clicked Save in Settings modal
• Variables are set in correct section (agent vs project)
• No typos in variable names

Debug:

• Print environment in agent terminal: env | grep VAR_NAME
• Check both agent and project variable sections

Run script doesn't execute

Check:

• Run script is defined in project settings
• Working directory exists
• Command is valid for your project

Debug:

• Check bottom terminal for error messages
• Try running command manually in terminal

Schaltwerk uses old agent version after upgrade

Problem: After upgrading your agent, Schaltwerk still uses the old version

Cause: Multiple installations exist, Schaltwerk points to the old binary

Solution:

1. Find current installation path: which <agent-name>
2. Open Settings → Agent Configuration
3. Select the agent tab (Claude Code, Codex, etc.)
4. Click Refresh Binary to auto-detect new version
5. Or manually select the correct binary path
6. Return to active sessions and restart the agent

Note: Binary paths are cached per agent. Always refresh after system upgrades.

Security Best Practices

Settings are stored unencrypted. Follow these guidelines to protect sensitive data:

Rotate Keys

Regularly rotate API keys and tokens

Use OS Keychain

Store sensitive values in system keychain when possible

Restrict Permissions

Limit file permissions on settings.json

Shared Machines

Don’t store API keys on shared/public machines

Next Steps

Start Using Schaltwerk

Learn the day-to-day workflow

Keyboard Shortcuts

Master the keyboard shortcuts