Option 2: Manual MCP Setup (Alternative)

If you prefer manual control or are testing local changes:

1. Clone and build the devsolo repository:

   git clone https://github.com/slamb2k/devsolo.git
   cd devsolo
   npm install
   npm run build
   

2. Configure Claude Code to load the MCP server: Add to your Claude Code MCP configuration file:

   {
     "mcpServers": {
       "devsolo": {
         "command": "node",
         "args": ["/path/to/devsolo/dist/mcp/devsolo-mcp-server.js"]
       }
     }
   }
   

3. Restart Claude Code to load the MCP tools

4. Initialize in your project using natural language:

   "Initialize devsolo in this project"
   

   Claude will invoke the devsolo_init tool automatically.

For detailed installation instructions, see the Installation Guide.

Quick Start

New to devsolo? Follow these steps to get started with Claude Code.

Two Ways to Use devsolo

devsolo provides both native slash commands and direct MCP tool calls for maximum flexibility:

Option 1: Slash Commands (Recommended) 🎯

/devsolo:init       - Initialize devsolo
/devsolo:launch     - Start a new feature
/devsolo:commit     - Commit changes
/devsolo:ship       - Ship your changes (full workflow)
/devsolo:status     - Check current status

Option 2: Natural Language (Direct MCP Tool Calls)

"Use devsolo_init to initialize devsolo in this project"
"Use devsolo_launch to start a new feature for authentication"
"Use devsolo_ship to commit, push, create PR, and merge"

Slash commands provide better integration, auto-completion, and coordinated workflows via specialized sub-agents (git-droid, docs-droid)!

1. Initialize devsolo in your project

Using slash command:

/devsolo:init

Or using natural language:

Use devsolo_init to initialize devsolo in this project

This creates a .devsolo directory with configuration and session storage.

2. (Optional) Set up GitHub authentication

# Option A: GitHub CLI (easiest)
gh auth login

# Option B: Personal access token
export GITHUB_TOKEN=ghp_your_token_here

3. Start a new feature workflow

Using slash command:

/devsolo:launch

Or using natural language:

Use devsolo_launch to start a new feature for [your feature description]

This creates a new feature branch and starts tracking your workflow.

4. Make your changes

Work on your feature as normal. devsolo tracks your session automatically.

Check status:

/devsolo:status

5. Ship your changes (One Command! 🚀)

Using slash command:

/devsolo:ship

Or using natural language:

Use devsolo_ship to commit, push, create PR, and merge this feature

That's it! This single MCP tool call:

• ✅ Commits your changes
• ✅ Pushes to remote
• ✅ Creates or updates PR
• ✅ Waits for CI checks
• ✅ Auto-merges when ready
• ✅ Syncs main branch
• ✅ Deletes feature branches
• ✅ Completes session

Ready for your next feature! 🎉

Enable Status Line (Optional)

For always-visible workflow status in Claude Code:

/devsolo:status-line

Slash Commands

devsolo provides native Claude Code slash commands for all functionality. Type /devsolo in Claude Code to see the full list.

Available Commands

How Slash Commands Work

When you use a slash command like /devsolo:launch, Claude Code:

1. Displays the unique ASCII art banner for immediate visual feedback
2. Orchestrates the workflow using specialized sub-agents (git-droid, docs-droid)
3. Invokes the appropriate MCP tools for execution
4. Returns structured results with pre/post-flight checks

Benefits of slash commands:

• 🎯 Discoverable - Shows up in / menu with auto-completion
• ⚡ Fast - Quick access to commands with visual feedback
• 📝 Guided - Parameter hints and descriptions built-in
• 🤖 Smart - Coordinated by specialized sub-agents for intelligent workflows
• 🔄 Flexible - Can still use natural language for direct MCP tool calls

Architecture

devsolo uses a plugin architecture with clear separation of concerns:

User → Slash Command → Sub-Agent → MCP Tools → Git/GitHub
         ↓              ↓            ↓
    Orchestration   Coordination   Execution

Sub-Agents

devsolo includes specialized sub-agents for intelligent coordination:

• git-droid 🤖 - Git workflow coordination and automation

  • Manages branch creation and cleanup
  • Coordinates multi-step git operations
  • Provides intelligent defaults for git workflows
  • Handles state transitions and safety checks

• docs-droid 📚 - Documentation management and validation

  • Enforces documentation structure and naming conventions
  • Automatically places docs in correct locations
  • Maintains README.md indexes
  • Archives outdated documentation

How It Works

1. Slash commands provide the user interface and high-level orchestration
2. Sub-agents coordinate operations with git-aware intelligence
3. MCP tools execute focused, single-purpose operations
4. Services provide core functionality (git operations, GitHub API, etc.)

This architecture ensures maintainability, testability, and a great user experience.

Core MCP Tools

All devsolo functionality is exposed through MCP tools that Claude Code can invoke.

devsolo_init

Initialize devsolo in your project. Creates configuration and session storage.

Input:

• scope (optional): Installation scope - "project" or "user" (default: "project")
• force (optional): Force reinitialization (default: false)

Returns: Structured result with success status and initialization details

devsolo_launch

Start a new feature workflow with automatic branch creation.

Input:

• branchName (optional): Specify branch name (auto-generated if omitted)
• description (optional): Add description for the feature
• force (optional): Launch even with uncommitted changes
• stashRef (optional): Git stash reference to restore after branch creation
• popStash (optional): Whether to pop the stash (default: true if stashRef provided)

Returns: SessionToolResult with pre/post-flight check results

devsolo_commit

Commit changes to the current feature branch.

Input:

• message (optional): Commit message (generated if omitted)
• stagedOnly (optional): If true, only commit staged files (default: false)

Returns: SessionToolResult with commit details

devsolo_ship

COMPLETE WORKFLOW: Complete the entire workflow automatically in a single command!

Ship handles everything: push → PR → CI wait → merge → cleanup

What it does:

1. Pushes to remote
2. Creates or updates GitHub PR
3. Waits for CI checks to pass (20 minute timeout)
4. Auto-merges PR with squash
5. Syncs local main branch
6. Deletes feature branches (local & remote)
7. Marks session as complete

Input:

• prDescription (optional): PR description (required for new PRs)
• push (optional): Push to remote (default: true)
• createPR (optional): Create pull request (default: true)
• merge (optional): Merge PR after CI passes (default: true)
• force (optional): Override safety checks
• yes (optional): Skip confirmations
• stagedOnly (optional): Only commit staged files when committing changes

Returns: GitHubToolResult with PR number, URL, and merge status

devsolo_sessions

List and manage active workflow sessions.

Input:

• all (optional): Show all sessions including completed
• verbose (optional): Detailed session information
• cleanup (optional): Remove expired sessions

Returns: QueryToolResult with session list

devsolo_swap

Switch between active workflow sessions.

Input:

• branchName: Branch to swap to (required)
• force (optional): Force swap with uncommitted changes
• stash (optional): Stash changes before swapping

Returns: SessionToolResult with swap details

devsolo_abort

Cancel an active workflow session.

Input:

• branchName (optional): Specify branch to abort (current if omitted)
• deleteBranch (optional): Delete the branch after aborting
• force (optional): Force abort
• yes (optional): Skip confirmation

Returns: SessionToolResult with abort details

devsolo_status

Show current workflow status and session information.

Input: None required

Returns: QueryToolResult with current status

devsolo_status_line

Manage Claude Code status line display.

Input:

• action: Action to perform - "enable", "disable", "update", or "show" (required)
• format (optional): Custom format string (e.g., "{icon} {branch} {state}")
• showBranchInfo (optional): Show branch name in status line
• showSessionInfo (optional): Show session ID in status line
• showStateInfo (optional): Show workflow state in status line

Returns: QueryToolResult with status line configuration

devsolo_hotfix

Create emergency hotfix workflow.

Input:

• issue (optional): Issue number or description
• severity (optional): Severity level - "critical", "high", or "medium"
• force (optional): Force operations
• skipTests (optional): Skip running tests
• skipReview (optional): Skip code review
• autoMerge (optional): Automatically merge when checks pass
• yes (optional): Skip confirmations

Returns: SessionToolResult with hotfix details

Structured Results

All MCP tools return structured JSON results for programmatic handling by Claude Code:

SessionToolResult

{
  success: boolean;
  branchName?: string;
  state?: string;
  preFlightChecks?: CheckResult[];
  postFlightVerifications?: CheckResult[];
  errors?: string[];
  warnings?: string[];
  nextSteps?: string[];
}

GitHubToolResult

{
  success: boolean;
  prNumber?: number;
  prUrl?: string;
  merged?: boolean;
  preFlightChecks?: CheckResult[];
  postFlightVerifications?: CheckResult[];
  errors?: string[];
  warnings?: string[];
}

QueryToolResult

{
  success: boolean;
  data: Record<string, unknown>;
  message?: string;
  errors?: string[];
  warnings?: string[];
}

Pre-Flight and Post-Flight Checks

Every MCP tool includes comprehensive validation with structured results:

Pre-Flight Checks (before execution):

• Validates prerequisites are met
• Returns structured check results
• Provides actionable error messages
• Can be overridden with force flag

Post-Flight Verifications (after execution):

• Confirms expected state was achieved
• Verifies all operations completed
• Identifies any issues that occurred
• Returns detailed verification results

Check Result Structure:

{
  name: string;
  passed: boolean;
  message: string;
  severity: 'error' | 'warning' | 'info';
  details?: {
    expected?: any;
    actual?: any;
    suggestion?: string;
  };
}

See docs/guides/validation.md for complete documentation.

Workflow States

devsolo uses a deterministic state machine to manage workflows:

INIT → BRANCH_READY → CHANGES_COMMITTED → PUSHED →
PR_CREATED → WAITING_APPROVAL → MERGED → COMPLETE

Each state has specific allowed transitions and validations to ensure workflow integrity.

GitHub Integration

devsolo integrates with GitHub API for automated PR management.

Setup

Option 1: Use GitHub CLI (Recommended for local development)

gh auth login

Option 2: Set environment variable (For CI/CD)

export GITHUB_TOKEN=your_github_token
# or
export GH_TOKEN=your_github_token

devsolo automatically detects and uses gh CLI authentication if available.

Features

• Automatic PR creation with generated descriptions
• CI check monitoring with configurable timeout
• Review status tracking
• Squash merge support
• Automatic branch cleanup

Status Line Integration

The status line provides at-a-glance workflow information directly in Claude Code:

[devsolo] 💻 0c2a20a7 | feature/my-feature | BRANCH_READY

Status Line Components:

• Session ID: Short identifier for current session
• Branch Name: Current feature branch
• State: Workflow state (BRANCH_READY, PUSHED, etc.)

Managing the Status Line:

Use devsolo_status_line with action "enable"
Use devsolo_status_line with action "disable"
Use devsolo_status_line with action "show"
Use devsolo_status_line with action "update" and showBranchInfo true

Session Management

Sessions are stored in .devsolo/sessions/ with automatic persistence:

• Each workflow creates a unique session ID
• Sessions track state history and transitions
• Automatic lock management prevents conflicts
• Sessions expire after 30 days of inactivity

Configuration

Configuration is stored in .devsolo/config.yaml:

initialized: true
scope: project
gitPlatform:
  type: github
  owner: your-org
  repo: your-repo
preferences:
  defaultBranchPrefix: feature/
  autoCleanup: true
  prTemplate:
    footer: "🤖 Generated with devsolo"

Architecture

devsolo follows a pure MCP architecture:

┌─────────────────────────────────┐
│         Claude Code             │
│    (MCP Client - AI Agent)      │
└─────────────────────────────────┘
                ↓ JSON-RPC
┌─────────────────────────────────┐
│       MCP Server                │
│    (DevSoloMCPServer)           │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│       MCP Tools Layer           │
│  (LaunchTool, ShipTool, etc.)   │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│  Validation Services Layer      │
│  (Pre/Post-Flight Checks)       │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│     Core Services Layer         │
│ (Git, GitHub, Sessions, Config) │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│    Persistence Layer            │
│  (File System & Git Repo)       │
└─────────────────────────────────┘

Development

Building from Source

# Clone the repository
git clone https://github.com/slamb2k/devsolo.git
cd devsolo

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

Testing the MCP Server

# Build MCP server
npm run build:mcp

# Start MCP server for testing
npm run mcp:start

# Run MCP tests
npm run test:mcp

Testing

devsolo includes comprehensive tests for all components:

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# MCP server tests only
npm run test:mcp

Documentation

Getting Started

• docs/guides/quickstart.md - Get up and running in 5 minutes
• docs/guides/installation.md - Detailed installation instructions
• docs/guides/usage.md - Practical examples and real-world scenarios

Reference

• docs/guides/mcp-tools-reference.md - Complete MCP tool reference
• docs/dev/system/configuration.md - Configuration options
• docs/dev/system/pre-flight-checks.md - Pre/post-flight checks documentation

Advanced

• docs/dev/system/mcp-architecture.md - MCP architecture overview
• docs/dev/system/mcp-tools.md - MCP tools implementation details
• docs/dev/plans/phase3-pure-mcp-architecture.md - MCP-only design philosophy

Migration

• docs/guides/migration-from-cli.md - Migrating from CLI-based versions (v1.x)

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Start a new workflow (Use devsolo_launch via Claude Code)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linting
6. Ship your changes (Use devsolo_ship via Claude Code)
7. Create a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Built with TypeScript
• MCP integration via @modelcontextprotocol/sdk
• GitHub API via @octokit/rest
• Git operations via simple-git

devsolo v2.0 - AI-native Git workflow automation for Claude Code 🤖