Arbiter

Autonomous GitHub Issue Solver - A local-first automation system that uses AI to solve GitHub issues automatically.

Arbiter is an intelligent automation system that watches your GitHub repositories, finds labeled issues, and uses AI workers (Claude Code, Ollama, or LM Studio) to implement solutions automatically. It creates branches, writes code, runs tests, and opens pull requests—all while running locally on your machine.

What It Does

1. 🔍 Monitors GitHub - Scans your repos for issues with specific labels (e.g., agent-ok)
2. 🏗️ Creates Workspaces - Clones the repo and creates an isolated feature branch
3. 🤖 Solves Issues - Uses AI workers to implement the solution
4. ✅ Validates - Runs tests and checks to verify the changes
5. 📝 Opens PRs - Creates pull requests with the implemented solution
6. 🔄 Iterates - Resumes work if the AI hits turn limits
7. 👀 Monitors - Web dashboard shows real-time progress

All processing happens locally - your code never leaves your machine.

Installation

npm install -g @git-arbiter/arbiter

Requirements:

• Node.js 18+
• Git installed and configured
• GitHub Personal Access Token
• One of the supported AI workers:
  • Claude Code (recommended) - Anthropic's official CLI
  • Ollama - Local, free models
  • LM Studio - Local, free models

Quick Start

1. Initialize Configuration

arbiter init

This creates ~/.arbiter/config.yaml with default settings.

2. Configure Your Setup

Edit the config file:

nano ~/.arbiter/config.yaml

Set at minimum:

• github.token - Your GitHub PAT
• github.repos - List of repos to monitor (e.g., ["owner/repo"])
• worker.type - AI worker to use (claude-code, ollama, or lmstudio)

3. Verify Setup

arbiter doctor

This checks:

• GitHub token validity
• AI worker availability
• Repo access permissions
• Configuration validity

4. Label an Issue

Add the agent-ok label (or your custom label) to any GitHub issue.

5. Run Arbiter

Option A: Run once (CLI)

arbiter run

Option B: Start the web dashboard

arbiter ui

Then open http://127.0.0.1:3927

Commands

# Initialize config file
arbiter init

# Check system health
arbiter doctor

# Run once (find issue, solve it, create PR)
arbiter run

# Start web dashboard
arbiter ui [--port 3927]

# Manual workflow commands:
arbiter validate <workspace>    # Validate changes
arbiter commit <workspace>      # Commit changes
arbiter push <workspace>        # Push branch
arbiter pr <workspace>          # Open pull request

Web Dashboard

The web UI provides:

• 📊 Real-Time Monitoring - Watch runs in progress with live logs
• ⚙️ Configuration - Edit all settings via UI
• 📁 Repository Management - Configure per-repo policies
• ⏰ Auto-Run Scheduler - Set interval-based execution
• 📜 Log Viewer - Query logs from PostgreSQL or Elasticsearch
• 🎓 Self-Learning - Review and approve AI-extracted learnings
• 🔔 Notifications - Desktop and browser notifications

Start the UI:

arbiter ui

Then open http://127.0.0.1:3927

How It Works

The Workflow

1. Fetches Issues - Queries GitHub for issues with your required label
2. Prioritizes - Ranks by labels, age, and custom rules
3. Prepares Workspace - Clones repo and creates branch: arbiter/issue-{number}-{slug}
4. Invokes AI Worker - Launches Claude Code/Ollama with task instructions
5. Monitors Progress - Streams output and tracks completion
6. Validates Changes - Checks diff size, forbidden paths, runs tests
7. Creates PR - Opens pull request with the solution
8. Handles Continuations - Resumes if AI hits turn/budget limits

AI Workers

Claude Code (Recommended)

worker:
  type: claude-code
  model: sonnet
  maxTurns: 50
  maxBudgetUsd: 5.0

• Highest quality results
• Best tool-calling support
• API costs apply

Ollama (Local, Free)

worker:
  type: ollama
  url: http://localhost:11434
  model: llama3.1:8b-instruct-q8_0
  maxTurns: 30

• No API costs
• Requires local GPU
• Good for simple tasks

LM Studio (Local, Free)

worker:
  type: lmstudio
  url: http://localhost:1234
  model: model-name
  maxTurns: 30

• No API costs
• GUI for model management
• Good for experimentation

Key Features

🔒 Security & Safety

• Local-First - Code never leaves your machine
• Diff Validation - Enforces limits on changed files/lines
• Forbidden Paths - Blocks changes to sensitive files
• Command Allowlisting - Only approved commands can run
• Draft PRs - PRs open as drafts for human review
• AI Code Review - Optional second AI reviews PRs

🔄 Smart Continuation

• Resumes work if AI hits turn or budget limits
• Preserves workspace and branch
• Tracks attempt count
• Adds continuation notes to prompt

🎓 Self-Learning Mode

• Extracts learnings from successful PRs
• Builds knowledge about your codebase
• Consolidates learnings into context documents
• Improves quality over time

📊 Advanced Monitoring

• PostgreSQL or Elasticsearch logging
• Full-text search across logs
• Run history and metrics
• Real-time log streaming in UI

🔔 Notifications

• Desktop notifications (macOS/Linux/Windows)
• Browser notifications (UI only)
• Configurable per event type

Configuration

Arbiter is highly configurable. Edit ~/.arbiter/config.yaml to control:

• GitHub Settings - Tokens, repos, labels, clone method
• Repository Policies - Push permissions, PR settings, reviewers
• Worker Settings - AI provider, model, limits
• Safety Limits - Max files/lines changed, forbidden paths
• Checks - Commands to run before committing
• Logging - PostgreSQL, Elasticsearch, or in-memory
• Notifications - Desktop and browser alerts

See the full documentation at git-arbiter.com/docs.html

Alternative Installation Methods

Homebrew (macOS)

brew install arbiter/tap/arbiter

Docker

docker pull gitarbiter/arbiter:latest

See git-arbiter.com/docs.html for Docker setup instructions.

Docker Installation

For easy setup with all dependencies:

# Clone repo (requires access)
git clone <repo-url>
cd arbiter

# Start with Docker Compose
docker-compose up -d

# Initialize config
docker-compose exec arbiter arbiter init

# Edit config (set GitHub token & repos)
docker cp arbiter:/home/arbiter/.arbiter/config.yaml ./config.yaml
# Edit config.yaml...
docker cp ./config.yaml arbiter:/home/arbiter/.arbiter/config.yaml
docker-compose restart arbiter

# Open UI
open http://localhost:3927

Trial & Licensing

Arbiter includes a 7-day free trial with full features.

• Runtime validation - License checked when you run Arbiter
• Machine-based - License tied to your development machine
• Offline-friendly - Validation cached locally

Purchase a license at git-arbiter.com

Troubleshooting

Command Not Found

Ensure npm's global bin is in your PATH:

# Check where npm installs global packages
npm bin -g

# Add to PATH
export PATH="$(npm bin -g):$PATH"

Permission Errors (macOS/Linux)

Fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

npm install -g @git-arbiter/arbiter

Binary Won't Execute

Make the binary executable:

# Check binary exists
ls -la ~/.arbiter/bin/

# Make executable (macOS/Linux)
chmod +x ~/.arbiter/bin/arbiter

# Reinstall if needed
npm uninstall -g @git-arbiter/arbiter
npm install -g @git-arbiter/arbiter

AI Worker Not Found

Claude Code:

• Install: Follow instructions at code.anthropic.com
• Verify: claude --version

Ollama:

• Install: curl -fsSL https://ollama.com/install.sh | sh
• Pull model: ollama pull llama3.1:8b-instruct-q8_0
• Start server: ollama serve

LM Studio:

• Download from lmstudio.ai
• Load a model with function-calling support
• Start local server (Developer → Local Server)

More Information

• Website: git-arbiter.com
• Documentation: git-arbiter.com/docs.html
• Changelog: git-arbiter.com/changelog.html
• GitHub: github.com/Git-Arbiter

License

Proprietary software. See Terms of Service for details.

Made with ❤️ by the Git-Arbiter team