autosteer

AutoSteer is an Electron-based desktop application designed to manage multiple Claude Code workspaces with persistent sessions and context switching. As an MCP-enabled server, it exposes tools for multi-workspace management, per-project tab handling, and protocol tracing to help you monitor interactions with Claude Code. The server brings together session persistence, per-project isolation, and a visual status panel so you can monitor MCP authentication, session states, and token usage across workspaces. Use the MCP interface to start, stop, or configure AutoSteer-enabled sessions, inspect protocol messages, and manage authentication and settings for each worktree.

To use its tools, start the MCP-enabled server via your preferred method (for example, using npx to run the package). Once running, you can leverage per-project tab management to organize multiple projects, switch between them seamlessly, and view contextual session information in the Status Panel. The Protocol Trace Viewer helps you debug and understand agent interactions by inspecting the raw protocol messages. For developers, the project structure outlines where the main Electron process, IPC handlers, and domain-specific features live, enabling you to extend slash commands, git operations, or session management as needed.

Prerequisites:

• Node.js 20.x or higher
• pnpm (optional but recommended for development)
• Git
• Claude Code is referenced as a prerequisite for AutoSteer workflows (see installation notes in the README)

Quick Install (via npx):

1. Ensure Node.js is installed (v20+).

2. Run the MCP server using the package name:

   npm -g clean-install && npx -y notch-ai/autosteer

If you prefer a local clone and development workflow:

1. Clone the repository: git clone https://github.com/notch-ai/autosteer.git
2. Navigate to the project folder: cd autosteer
3. Install dependencies (recommended with pnpm): pnpm install
4. Run in development mode: pnpm dev
5. Build and package for distribution as per the repository's development scripts: pnpm compile pnpm make

Notes:

• For Windows, follow the WSL2-based setup described in INSTALLATION.md if you encounter Windows-specific build issues.
• The application relies on Claude Code; ensure Claude Code is installed prior to using AutoSteer features.

Tips and common issues:

• Environment variables: You can enable detailed debugging by setting DEBUG=true for verbose logs during MCP server runs.
• File paths: AutoSteer stores its configuration under ~/.autosteer/ on all platforms. If you customize paths, ensure the app has access to those directories.
• Platform specifics: Building Electron apps may require platform-specific build tools (Xcode CLT on macOS, build-essential on Linux, and appropriate toolchains on Windows via WSL).
• If you encounter MCP authentication issues, verify that the Status Panel in AutoSteer is able to reach the authentication endpoints and that your network allows the necessary connections.
• Slash commands and custom extensions: The project includes a Slash Command utility for extending Claude Code, which can be customized under src/commons/utils/slashCommandUtils.ts.
• For developers contributing: use the provided pnpm scripts (dev, test, compile, package, make) to reproduce CI-like steps locally.