KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

autosteer

★ 67 Open GitHub ↗

Desktop app for multi-workspace Claude Code management

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AutoSteer

[![Release](https://img.shields.io/github/v/release/notch-ai/autosteer)](https://github.com/notch-ai/autosteer/releases)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/notch-ai/autosteer/main/LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20(WSL)-lightgrey)](https://github.com/notch-ai/autosteer/releases)
[![Node Version](https://img.shields.io/badge/node-%3E%3D20.0.0-green)](https://nodejs.org)

AutoSteer is a desktop application that enhances your Claude Code experience with multi-workspace management. Built with Electron, it works across macOS, Linux, and Windows (via WSL), allowing you to manage multiple isolated workspaces with persistent sessions and seamless context switching.

## Demo

https://github.com/user-attachments/assets/9c86ef28-7167-41c9-b4e6-7d50ba586ca2

> [!NOTE]
> This project is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC. This is an independent project using Claude.

## Features

- Worktree-First Architecture - Organize projects in isolated workspaces with independent file systems and contexts
- Persistent Sessions - Save and resume conversations per worktree, maintaining full context across work sessions
- Multi-Project Management - Switch seamlessly between different projects without losing state or context
- Per-Project Tab Management - Session tabs scoped to projects with auto-select behavior and persistent state
- Cross-Platform - Native support for macOS, Linux, and Windows (via WSL)
- Context Preservation - Automatically saves conversation state, allowing you to pick up exactly where you left off
- Fast Context Switching - Instantly switch between worktrees and tabs
- Token Usage Tracking - Monitor token usage and costs per message and per worktree
- Status Panel - View session information, manage MCP servers, and handle MCP authentication
- Protocol Trace Viewer - Inspect detailed protocol messages for debugging and understanding agent behavior
- Custom Slash Commands - Extend Claude Code functionality with custom command patterns (file:src/commons/utils/slashCommandUtils.ts)

## 📦 Installation

**Prerequisite:** [Claude Code](https://docs.claude.com/en/docs/claude-code/quickstart) must be installed first.

### Quick Install

Download the latest version for your platform from the [Releases](https://github.com/notch-ai/autosteer/releases) page:

- **macOS**: Download `.zip` file and extract to Applications
- **Linux**: Download `.deb` (Debian/Ubuntu) or `.rpm` (Fedora/RHEL)
- **Windows**: Install via WSL2

### Platform-Specific Instructions

For detailed installation instructions including WSL2 setup for Windows, see [INSTALLATION.md](INSTALLATION.md)

## 🚀 Getting Started

```bash
# Launch AutoSteer
autosteer

# Launch with debug logging
autosteer --debug
```

After launching, configure your preferences in Settings and start using Claude Code with AutoSteer!

AutoSteer stores configuration in `~/.autosteer/` on all platforms.

## 🛠️ Development

### Prerequisites

- [Node.js](https://nodejs.org/) (v20 or higher)
- [pnpm](https://pnpm.io/) (v9 or higher)
- [Git](https://git-scm.com/)
- Platform-specific build tools:
  - **macOS**: Xcode Command Line Tools
  - **Linux**: `build-essential` package
  - **Windows**: Use WSL with Linux build tools

### Building from Source

```bash
# Clone the repository
git clone https://github.com/notch-ai/autosteer.git
cd autosteer

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Build application
pnpm compile

# Package for distribution
pnpm make
```

### Development Scripts

```bash
# Start development server
pnpm dev

# Run unit tests
pnpm test:unit

# Run integration tests
pnpm test:integration

# Run all tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

# Type check
pnpm typecheck

# Compile application (TypeScript + Webpack)
pnpm compile

# Package application for current platform
pnpm package

# Create distributable installers
pnpm make
```

### Project Structure

```text
autosteer/
├── src/
│   ├── main/                           # Electron main process
│   │   └── ipc/                        # Inter-process communication layer
│   │       ├── handlers/               # 4 consolidated domain handlers
│   │       │   ├── claude.handlers.ts  # Agent, MCP, SlashCommand operations
│   │       │   ├── project.handlers.ts # File, Resource management
│   │       │   ├── git.handlers.ts     # Git operations
│   │       │   └── system.handlers.ts  # Terminal, Badge, Config, Log, Store, Update
│   │       ├── utils/handlerFactory.ts # Reusable error handling, logging, validation
│   │       └── IpcRegistrar.ts         # Centralized handler registration
│   ├── features/                       # Domain-based feature organization
│   │   ├── chat/                       # Chat feature domain (15 components)
│   │   ├── monitoring/                 # Monitoring feature domain (10 components)
│   │   ├── settings/                   # Settings feature domain (4 components)
│   │   └── shared/                     # Shared components across features (48 components)
│   │       └── components/             # Organized by subdomain
│   │           ├── agent/
│   │           ├── git/
│   │           ├── layout/
│   │           ├── projects/
│   │           ├── session/
│   │           ├── tasks/
│   │           ├── terminal/
│   │           └── ui/
│   ├── components/                     # Common UI layer (shadcn/ui primitives)
│   ├── services/                       # Application services
│   ├── stores/                         # State management (Zustand)
│   ├── hooks/                          # React hooks
│   │   └── useSessionTabs.ts           # Tab management hook 
│   ├── commons/
│   │   ├── utils/                      # Utility functions
│   │   │   └── slash-commands/         # Slash command utilities
│   │   ├── contexts/                   # React contexts
│   │   ├── constants/                  # Constants and config
│   │   │   └── tabs.ts                 # Tab constants (MAX_TABS, system tab IDs)
│   │   └── config/                     # Theme and styling
│   ├── entities/                       # Data models (Lite Clean Architecture)
│   ├── types/                          # TypeScript types
│   │   └── ui.types.ts                 # Tab type definitions (SessionTab, MaximizeTab, TabState)
│   └── docs/                           # Documentation
│       └── tab-management.md           # Tab management guide
├── assets/                             # App icons and images
├── tests/
│   ├── unit/                           # Unit tests (80% coverage target)
│   ├── integration/                    # Integration tests
│   ├── component/                      # Playwright component tests
│   └── factories/                      # Test data factories
├── scripts/                            # Build and release scripts
└── playwright-component.config.ts      # Component testing config
```

**Import Pattern**: `@/features/[domain]/components/[Component]`

### Tab Management

AutoSteer provides robust tab management with per-project isolation. See `docs/tab-management.md` for detailed documentation.

**Key Features**:
- Per-project tab isolation: Only tabs for the selected project are visible
- Auto-select behavior: Automatically switches to another tab when closing
- Persistent state: Tab selection survives application restarts
- System tabs: Terminal and Changes tabs always present
- Maximize tabs: Dynamic tabs for maximize view

**Configuration**:
```json
{
  "settings": {
    "confirmSessionTabDeletion": true
  }
}
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information.

### Quick Start for Contributors

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/autosteer.git
cd autosteer

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests before committing
pnpm test
pnpm lint
pnpm typecheck
```

## 🧪 Testing

### Running Tests

We use Jest for unit/integration tests and Playwright for component/visual tests:

```bash
# Run all tests
pnpm test

# Run unit tests only
pnpm test:unit

# Run integration tests only
pnpm test:integration

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage report
pnpm test:coverage
```

### Test Coverage

Key test files covering critical functionality:

- **Utilities**: `tests/unit/commons/utils/slash-commands/slash_command_utils.test.ts` - Custom slash command formatting
- **Hooks**: `tests/unit/hooks/useTerminalPool.test.ts` - Terminal pool management
- **IPC Handlers**: `tests/unit/main/ipc/handlers/` - Consolidated domain handlers 
- **Services**: `tests/unit/services/ClaudeCodeService.test.ts` - Core Claude Code integration
- **Store**: `tests/unit/stores/core.test.ts` - State management
- **Types**: `tests/unit/types/terminal.types.test.ts` - Terminal type safety
- **Entities**: `tests/unit/entities/SessionBlock.test.ts` - Data model validation

## 🔍 Trace File Format

AutoSteer creates trace files for debugging SDK message flow. These files are stored in `~/.autosteer/traces/` and use JSONL format (one JSON object per line).

### Trace File Location

```
~/.autosteer/traces/{sessionId}.trace.jsonl
```

### Trace Entry Format

Each trace entry is a JSON object with the following structure:

```typescript
{
  "timestamp": "2025-11-09T18:51:35.123Z",    // ISO 8601 timestamp
  "sessionId": "session-abc123",              // Session identifier
  "direction": "to-claude" | "from-claude",   // Message direction
  "rawMessage": { /* SDK message object */ }, // Complete SDK message
  "sdkVersion": "^0.1.0",                     // SDK version
  "correlationId": "550e8400-e29b-41d4",      // Request/response correlation
  "sequenceNumber": 42                         // Monotonic sequence per session
}
```

### Trace File Lifecycle

- **Creation**: Trace files are created automatically when SDK messages are logged
- **Rotation**: Files are rotated when they exceed 100MB, with timestamp suffixes
- **Cleanup**: Trace files are automatically deleted when their project is deleted
- **Manual Cleanup**: Delete files in `~/.autosteer/traces/` to free disk space

### Using Trace Files

Trace files are useful for:
- **Debugging**: Inspect exact SDK messages sent and received
- **Performance Analysis**: Track message timing and sequence
- **Error Investigation**: Review message flow leading to errors
- **SDK Updates**: Verify message format changes across SDK versions

### Example Trace Entry

```json
{
  "timestamp": "2025-11-09T18:51:35.123Z",
  "sessionId": "session-abc123",
  "direction": "from-claude",
  "rawMessage": {
    "type": "assistant",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "session_id": "session-abc123",
    "message": {
      "role": "assistant",
      "content": [{ "type": "text", "text": "Hello!" }]
    }
  },
  "sdkVersion": "^0.1.0",
  "correlationId": "550e8400-e29b-41d4",
  "sequenceNumber": 42,
  "messageType": "assistant",
  "messageSubtype": null
}
```

## 🔄 SDK Migration Guide

### Overview

This guide helps developers handle Anthropic Claude SDK updates and Pydantic model changes without breaking existing message validation.

### SDK Version Updates

When updating `@anthropic-ai/claude-agent-sdk`:

1. **Check for Breaking Changes**
   - Review SDK release notes for breaking changes
   - Test validation with new SDK types
   - Update Pydantic models if needed

2. **Update Zod Schemas**
   - Location: `src/services/MessageValidator.ts`
   - Match schemas to new SDK types
   - Maintain backward compatibility with relaxed validation

3. **Test Validation**
   ```bash
   pnpm test:unit -- MessageValidator.test.ts
   ```

4. **Update Trace Documentation**
   - Document new message types in README

### Pydantic Model Changes

#### Adding New Message Types

1. **Update Python Models**
   - Follow existing BaseModel pattern
   - Add to `SDKMessage` union type

2. **Update TypeScript Schemas**
   - Add corresponding Zod schema in `MessageValidator.ts`
   - Add to discriminated union
   - Update type guards

3. **Add Tests**
   - Add test cases for new message type
   - Test strict and relaxed validation
   - Test partial extraction

Example:
```typescript
// Add to MessageValidator.ts
const NewMessageTypeSchema = z.object({
  type: z.literal('new_type'),
  uuid: z.string().uuid(),
  session_id: z.string(),
  // ... other fields
});
```

#### Handling Breaking SDK Changes

If an SDK update breaks validation:

1. **Identify Breaking Change**
   - Check validation test failures
   - Review trace logs for error patterns
   - Compare old vs new message structure

2. **Update Schemas Gradually**
   ```typescript
   // Old field (deprecated but still supported)
   old_field: z.string().optional(),

// New field (preferred)
   new_field: z.string().optional(),
   ```

3. **Add Migration Logic**
   - Handle both old and new formats
   - Log warnings for deprecated fields
   - Gradually phase out old format

4. **Version Compatibility**
   - Track SDK version in trace logs
   - Add version checks if needed
   - Document version requirements

### Testing Migration

```bash
# Run all validation tests
pnpm test:unit -- MessageValidator

# Test with fixtures
pnpm test:integration -- message-validation

# Check type coverage
pnpm typecheck
```

### Rollback Strategy

If validation breaks in production:

1. **Immediate**: Revert to previous SDK version
2. **Short-term**: Deploy hotfix with relaxed validation
3. **Long-term**: Fix schemas and redeploy

### Best Practices

- **Always test with real message fixtures** before deploying
- **Maintain backward compatibility** for at least 2 SDK versions
- **Document breaking changes** in PR descriptions
- **Use relaxed validation** as fallback to prevent crashes
- **Monitor trace logs** for validation failures after updates

## 🔒 Security

1. **Process Isolation**: Agents run in separate processes
2. **Local Storage**: All data stays on your machine
3. **No Telemetry**: No data collection or tracking

## 🔧 Troubleshooting

### Getting Help

- Report bugs via [GitHub Issues](https://github.com/notch-ai/autosteer/issues)
- Request features via [Discussions](https://github.com/notch-ai/autosteer/discussions)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

autosteer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README