AI-powered code analysis that helps developers understand and review changes faster.

Armchair bridges the gap between AI-assisted coding and real developer productivity by breaking down commits into logical chunks and providing intelligent code reviews—all through an interactive dashboard.

• Quick Start
• Features
• LLM Setup
• Performance Tips
• Configuration
• CLI Usage
• API Reference
• Security Model
• Troubleshooting
• Contributing
• License
• Changelog
• Advanced: Manual Docker
• Development

Get Armchair running in under 2 minutes.

• Docker Desktop (version 20.10+) installed and running
• An LLM provider configured — see LLM Setup for options

curl -fsSL https://raw.githubusercontent.com/armchr/armchr/main/scripts/armchair.sh -o armchair.sh
chmod +x armchair.sh
./armchair.sh

The script will:

1. Prompt for your code repositories root directory
2. Pull the latest Docker image
3. Start the dashboard at http://localhost:8686
4. Open your browser automatically for further setup

1. Click the Settings icon (⚙️) in the dashboard

2. Configure your LLM:

   Provider	API Base URL	Model
   Claude	https://api.anthropic.com/v1	claude-sonnet-4-20250514
   OpenAI	https://api.openai.com/v1	gpt-4o
   Ollama	http://host.docker.internal:11434/v1	qwen3:32b

   See LLM Setup for detailed instructions on getting API keys or installing local models.

3. Add your repositories (paths must be under your workspace directory)

4. Start analyzing commits

Breaks down commits into logical, reviewable chunks:

• Identifies code structures and relationships
• Generates structured output for downstream analysis
• Supports multiple programming languages (Python, Go, JS/TS, Java, Rust, C/C++)

Standalone usage: The Splitter Agent can be used independently via CLI. See the Code Splitter Agent README for details.

When you split a large change, Armchair generates a mental model to help reviewers understand the big picture before diving into code:

The mental model includes:

• What This Change Does: High-level summary of the entire changeset
• How Patches Progress: Step-by-step guide through the logical order of patches
• Key Concepts: Important domain concepts and patterns introduced
• Review Tips: Suggestions for what to focus on during review

A single large commit gets split into multiple smaller, logically-grouped patches:

Each patch shows:

• Descriptive title explaining what it does
• Files affected with annotation counts
• Lines changed summary

Interactive web UI at http://localhost:8686:

• Browse branches, commits, and uncommitted changes
• Run splitter and reviewer analysis
• Visualize annotated code explanations

Each code change in a split patch includes AI-generated annotations that explain what the change does:

The annotated diff viewer shows:

• Inline annotations: AI explanations embedded directly in the diff
• Side-by-side diff: Before and after comparison
• Line-level context: Annotations reference specific line ranges

Split and review GitHub PRs directly from the dashboard — no local clone required:

• Browse open PRs across all connected repositories in the Pull Requests tab
• Split a PR into logical patches using the same splitter agent
• Review a PR with the AI reviewer
• Paste any PR URL (e.g., https://github.com/owner/repo/pull/123) to analyze it instantly
• Post Armchair analysis as a comment directly on the PR
• Search and filter PRs by repository, title, author, or number

Requires a GitHub Personal Access Token (PAT) — configure it in Settings.

AI-powered code review:

• Analyzes commits and uncommitted changes
• Provides feedback on code quality and best practices
• Generates detailed suggestions

Backend API available at http://localhost:8787 for programmatic access.

Armchair requires an LLM to power its analysis. You can use proprietary cloud APIs or run open models locally.

Claude models excel at code understanding and review tasks.

Get an API key:

1. Create an account at console.anthropic.com
2. Navigate to API Keys
3. Click "Create Key" and copy it to your Armchair settings

Get an API key:

1. Create an account at platform.openai.com
2. Navigate to API Keys
3. Click "Create new secret key" and copy it to your Armchair settings

Run models locally for privacy and no API costs. Ollama makes it easy to run open-source models.

1. Download from ollama.com/download
2. Install and start Ollama
3. Verify installation: ollama --version

We recommend Qwen3 Coder for code analysis:

# Install Qwen3 Coder (recommended for code tasks)
ollama pull qwen3:32b

# Or for smaller systems
ollama pull qwen3:14b

In the Armchair Settings UI:

Important: Use host.docker.internal instead of localhost so the Docker container can reach your local Ollama instance.

For large repositories, enable commitOnly mode to skip loading unstaged/untracked files:

Via Settings UI: Toggle "Commit Only" when adding a repository

Via config file (~/.armchair_output/.armchair/source.yaml):

source:
  repositories:
    - name: "large-repo"
      path: "/path/to/large-repo"
      commitOnly: true  # Faster loading, commits still available

When enabled:

• All commits and branches remain available
• Dashboard loads significantly faster
• Unstaged/untracked files are hidden

All settings are managed through the dashboard Settings UI (⚙️) or config files.

~/.armchair_output/
├── .armchair/
│   ├── source.yaml         # Repository config
│   └── .armchair.json      # LLM settings
├── commit_*/               # Split patches
└── reviews/                # Code reviews

./armchair.sh [OPTIONS]

Options:
  --port-frontend PORT    Frontend port (default: 8686)
  --port-backend PORT     Backend port (default: 8787)
  --foreground, -f        Run in foreground (show logs)
  --name NAME             Container name (default: armchair-dashboard)
  --local                 Use local image 'explainer:latest'
  --image IMAGE           Use custom Docker image
  --help, -h              Show help

Run the Splitter Agent standalone (without the dashboard) for CI/CD or automation:

./scripts/run_splitter.sh --repo REPO_NAME --api-key YOUR_API_KEY

Note: The --mcp-config flag enables integration with Model Context Protocol servers, allowing the splitter to use additional tools and context sources during analysis.

# Split a specific commit
curl -X POST http://localhost:8787/api/split \
  -H "Content-Type: application/json" \
  -d '{"repoName": "my-repo", "branch": "main", "commitId": "abc1234"}'

# Split uncommitted changes
curl -X POST http://localhost:8787/api/split \
  -H "Content-Type: application/json" \
  -d '{"repoName": "my-repo", "branch": "main"}'

# Check GitHub connection status
curl http://localhost:8787/api/github/status

# List open PRs across connected repos
curl http://localhost:8787/api/github/pulls

# Split a GitHub PR
curl -X POST http://localhost:8787/api/github/split \
  -H "Content-Type: application/json" \
  -d '{"owner": "octocat", "repo": "hello-world", "number": 42}'

# Review a GitHub PR
curl -X POST http://localhost:8787/api/github/review \
  -H "Content-Type: application/json" \
  -d '{"owner": "octocat", "repo": "hello-world", "number": 42}'

# Analyze a PR by URL
curl -X POST http://localhost:8787/api/github/analyze-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo/pull/123"}'

# List repositories and branches
curl http://localhost:8787/api/repositories

# List analyzed commits
curl http://localhost:8787/api/commits

# Get commit diff
curl http://localhost:8787/api/repositories/my-repo/commits/abc1234/diff

# Get uncommitted changes
curl http://localhost:8787/api/repositories/my-repo/branches/main/working-directory/diff

Armchair is designed with security in mind:

What gets sent to the LLM:

• Code diffs you choose to analyze
• File contents within those diffs

What stays local:

• Repository metadata
• Git history
• All files not explicitly analyzed

# View logs
docker logs armchair-dashboard

# Follow logs
docker logs -f armchair-dashboard

# Clean restart
docker stop armchair-dashboard && docker rm armchair-dashboard
./armchair.sh

We welcome contributions! Please:

1. Open an issue to discuss proposed changes
2. Fork the repository
3. Create a feature branch
4. Submit a pull request

Report bugs and request features via GitHub Issues.

MIT License. See LICENSE for details.

See CHANGELOG.md and Releases for version history.

Current Version: v0.2

For manual Docker control without the script:

docker run -d \
  --name armchair-dashboard \
  -p 8686:8686 -p 8787:8787 \
  -v "$HOME:/workspace:ro" \
  -v "$HOME/.armchair_output:/app/output" \
  --entrypoint /bin/bash \
  armchr/explainer:latest \
  -c "cd /app/backend && node server.js --output /app/output --root-map /workspace --root-dir $HOME & cd /app/frontend && serve -s dist -l 8686"

docker logs armchair-dashboard      # View logs
docker logs -f armchair-dashboard   # Follow logs
docker stop armchair-dashboard      # Stop
docker start armchair-dashboard     # Start
docker rm armchair-dashboard        # Remove

Build the Docker image locally and run it using the same pattern as production:

# Build for local platform
make docker-build

# Build for multiple platforms (amd64 + arm64)
make docker-build-multi

# Run locally (defaults: ARMCHAIR_ROOT=$HOME, ARMCHAIR_OUTPUT=~/.armchair_output)
make docker-run

# Run with custom paths
make docker-run ARMCHAIR_ROOT=/Users/me/src ARMCHAIR_OUTPUT=/Users/me/.armchair_output

Run make help to see all available targets and current configuration.

For detailed documentation on individual components, see:

• code_explainer_ui README: Full architecture documentation (React frontend, Express.js backend, AI agents), local development setup, environment variables, API endpoint reference, MCP server mode, and project structure
• Code Splitter Agent README: Standalone splitter usage, pipeline architecture, and language support