Resolve Solo

A local-first on-call assistant for individual developers. Natural language investigation support with timeline analysis, incident recall, and reporting—powered by demo data, ready for Claude Code integration.

Three Ways to Use Resolve Solo

1. Claude Code Integration (Recommended)

Talk naturally to Claude Code, and it automatically invokes resolve-solo when you need incident investigation:

# One-time setup
npm install -g resolve-solo
resolveai setup

# Then in Claude Code, just talk naturally:
"investigate timeout issues in payment service"
"what changed in the last hour?"
"show me similar past incidents"

How it works: Resolve Solo exposes MCP (Model Context Protocol) tools that Claude Code automatically discovers and uses when you ask incident-related questions.

👉 See CLAUDE_CODE_INTEGRATION.md for detailed setup

2. Interactive REPL Mode

Type commands without the resolveai prefix in an interactive session:

# Start interactive mode
resolveai

# Now you're in the REPL
resolve-ai> investigate database errors
resolve-ai [abc12345]> show details for item 1
resolve-ai [abc12345]> note found connection pool leak
resolve-ai [abc12345]> close fixed by increasing pool size
resolve-ai> exit

Benefits: Session-aware prompts, command history, no need to type resolveai every time.

3. Single-Command CLI Mode

Traditional CLI mode for one-off commands or scripts:

resolveai demo
resolveai investigate timeouts
resolveai show details for item 3
resolveai help

Benefits: Perfect for scripts, automation, or if you prefer traditional CLI workflows.

Quick Start

Install

npm install -g resolve-solo

Option A: Setup for Claude Code

resolveai setup
# ✓ Configured Claude Code integration
# ✓ Restart Claude Code and start investigating!

Then in Claude Code:

User: "investigate timeout issues in payment service"
Claude: [Automatically calls resolve-solo investigation tool]

Option B: Try the Demo (CLI or REPL)

CLI mode:

resolveai demo

REPL mode:

resolveai
resolve-ai> demo

This will:

• Seed realistic demo data (incidents, deploys, logs, services)
• Run an automated investigation
• Show you what Resolve Solo can do

Installation Options

Option 1: Install globally from npm (Recommended)

npm install -g resolve-solo

Then use the short resolveai command in any of the three modes.

Option 2: Run directly via npx (No install)

Try it without installing:

npx resolve-solo demo
npx resolve-solo investigate timeouts

Note: npx doesn't support REPL or Claude Code modes. For those, install globally.

Option 3: Install from GitHub (Enterprise)

For development or enterprise GitHub:

npm install -g git+https://github.cbhq.net/srinath-sinha/resolve-solo
resolveai demo

Commands

Resolve Solo uses natural language commands—no flags needed.

Common Commands

# See what Resolve Solo can do
resolveai demo

# Get help
resolveai help

# Configure Claude Code integration
resolveai setup

# Investigate an issue (demo mode)
resolveai investigate timeouts in payment service
resolveai investigate database connection errors

# Show details for a timeline item
resolveai show details for item 3

# Add a note to your investigation
resolveai note checking database connection pool

# Close an investigation
resolveai close fixed connection pool size

# Generate demo data
resolveai demo seed
resolveai demo reset

# Generate weekly report
resolveai report weekly

# Check system health
resolveai doctor

# Uninstall
resolveai uninstall
resolveai uninstall --keep-data

What You'll See

When you run resolveai demo or use the investigate tool from Claude Code:

A) What changed recently - Timeline of deploys, errors, and past incidents B) Where to look next - Investigation paths with confidence levels C) Similar past incidents - What worked before, what didn't D) What I'm missing - Gaps in observability

All demo data is clearly labeled with (demo) so you know it's synthetic.

Data Storage

Resolve Solo stores all data locally in ./.resolveai/:

.resolveai/
├── demo-data/       # Demo dataset (services, deploys, logs, incidents)
└── memory.sqlite    # Investigation sessions and incident recall

The data is local-first and portable:

# See storage location
ls -la .resolveai/

# Copy data elsewhere
cp -r .resolveai ~/my-backup/

# Reset demo data
resolveai demo reset

Architecture

Mode Detection

resolveai --mcp          → MCP Server (Claude Code integration)
resolveai                → Interactive REPL
resolveai <command>      → Single-command CLI

Shared Handler Architecture

All three modes call the same business logic handlers, ensuring consistent behavior:

CLI Mode    →
REPL Mode   → Shared Handlers → Database/Storage
MCP Mode    →

Technology Stack

• Language: TypeScript (compiled to ESM JavaScript)
• Test Framework: Vitest
• MCP Integration: @modelcontextprotocol/sdk
• CLI: Natural language parser (no flag dependencies)
• Data: Deterministic mock generation + SQLite persistence
• Storage: JSON files + SQLite

Requirements

• Node.js 18+ (uses ES modules)
• Runs on macOS, Linux, Windows
• Claude Code (optional, for MCP integration)

Development

Want to contribute or modify Resolve Solo?

# Clone the repository
git clone https://github.com/srinathsinha/resolve-solo.git
cd resolve-solo

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for distribution
npm run build

# Type-check
npm run typecheck

Current Status

Version: 1.0.0 (stable release) Milestones Complete: M1-M12 (12/12) ✅

Completed Features (v1.0.0)

• ✅ M1-M4: Foundation, CLI, Demo Data, First-Time Demo
• ✅ M5-M6: Investigation Core, Session Persistence
• ✅ M7: Dual-Mode UX (REPL + MCP Server)
• ✅ M8: Weekly Reports (IT/Security stakeholder reporting)
• ✅ M9: Uninstall Experience (clean removal)
• ✅ M10: Doctor Command (system health check)
• ✅ M11: Polish & Testing (production-ready)
• ✅ M12: Distribution & Publishing

Features

• ✅ Three interaction modes: CLI, Interactive REPL, Claude Code MCP integration
• ✅ Complete investigation workflow: investigate → details → notes → close
• ✅ Session persistence: SQLite storage with incident recall
• ✅ Weekly reporting: Markdown + JSON reports for stakeholders
• ✅ System health check: Doctor command for troubleshooting
• ✅ Clean uninstall: Remove package, data, and integrations
• ✅ Timeline analysis: Relevance filtering and event correlation
• ✅ Automatic setup: One-command Claude Code configuration

This is a demo release - all investigations use mock data. Real integrations with observability tools (Datadog, Sentry, PagerDuty, etc.) are planned for future releases.

Claude Code Integration

The MCP server exposes 7 tools to Claude Code:

1. investigate - Start investigation for an incident
2. get_details - Show timeline item details
3. add_note - Add note to investigation
4. close_incident - Close investigation with resolution
5. generate_report - Weekly incident report
6. doctor - System health check
7. uninstall - Uninstall instructions

When properly configured, Claude Code automatically calls these tools when you ask incident-related questions in natural language.

See CLAUDE_CODE_INTEGRATION.md for:

• How tool discovery works
• Setup instructions (automatic + manual)
• Troubleshooting guide
• Examples of what triggers the tools

Uninstall

Resolve Solo provides a simple uninstall command that removes everything:

# Complete removal (package, data, Claude Code integration)
resolveai uninstall

# Keep your investigation data
resolveai uninstall --keep-data

# Skip confirmation prompt
resolveai uninstall --yes

What Gets Removed

The uninstall command removes:

• ✓ resolve-solo npm package (global or local)
• ✓ Local investigation data (.resolveai/ directory)
• ✓ Claude Code MCP integration (config + agent file)

Options

• --keep-data - Preserve investigation data in .resolveai/
• --yes or -y - Skip confirmation prompt (useful for scripts)

Manual Uninstall

If the uninstall command doesn't work:

# Remove package
npm uninstall -g resolve-solo

# Remove local data
rm -rf .resolveai

# Remove Claude Code integration
rm ~/.claude/agents/incident-investigator.md
# Manually edit ~/.claude/config.json to remove "resolve-solo" MCP server

Documentation

• CLAUDE_CODE_INTEGRATION.md - Complete MCP integration guide
• SPEC.md - Requirements specification
• PLAN.md - Implementation milestones
• DECISIONS.md - Key technical decisions
• CHANGELOG.md - Progress log
• STATUS.md - Current status
• CONTEXT.md - Cross-session context

License

MIT

Credits

Built by Resolve.ai - On-call assistant for engineers.