npm package: @say828/gito
Description: Git Auto Multi-Agent Orchestration CLI - Automate your development workflow from prompt to PR
Latest version: 2.1.0

# Gito

Git Auto Multi-Agent Orchestration CLI - Automate your development workflow from prompt to PR.

## What's New in v2.0

### Tool Use System
- **Native Tool Use API**: Agents can now read, write, and patch files directly using Claude's Tool Use
- **Intelligent File Operations**: Fuzzy matching for patch operations (80%+ similarity)
- **Git Integration**: Built-in git diff, status, and log tools

### Ping-Pong Review Loop
- **Iterative Refinement**: Implementation and Review agents iterate until code passes
- **Structured Feedback**: Severity levels (blocker, major, minor, suggestion) with categories
- **Configurable Thresholds**: Set max rounds, auto-approve minor issues

### Context Management
- **Repository Mapping**: Automatic symbol extraction and import graph analysis
- **PageRank-based Relevance**: Intelligent file selection based on dependencies
- **Token Budget Management**: Optimal context window utilization

### Meta Learning
- **Execution History**: SQLite-based storage for learning from past executions
- **Pre-execution Advice**: Warnings and recommendations based on similar tasks
- **Pattern Recognition**: Automatic failure pattern detection and prevention

## Features

- **Multi-Agent Pipeline**: Planning → Design → Implementation → Code Review → PR Creation
- **Interactive REPL Mode**: Manage multiple tasks in parallel with a terminal UI
- **Direct Command Mode**: Use CLI commands for quick operations
- **Command Autocomplete**: Type `/` to see available commands with ↑↓ navigation
- **Configurable Code Review**: Deterministic checks (lint, test, coverage, security) + LLM-based review
- **GitHub Integration**: Automatic branch creation, PR creation, and status tracking
- **Multiple LLM Providers**: Anthropic Claude, OpenAI, Ollama, LiteLLM (100+ models)
- **GitHub Enterprise Support**: Custom API endpoints for enterprise deployments

## Installation

```bash
npm install -g @say828/gito
```

## Quick Start

```bash
# 1. Start interactive mode
gito

# 2. Use /set to add a repository (interactive wizard)
/set

# 3. Type a prompt to create a task
Add user authentication with JWT
```

Or use CLI commands directly:

```bash
# Authenticate with GitHub
gito auth login

# Add a repository
gito repo add https://github.com/user/repo

# Run a development task
gito run "Add user authentication with JWT"
```

## Usage

### Interactive REPL Mode

Start with `gito` (no arguments):

```
╭──────────────────────────────────────────────────────────╮
│  ⎇ gito v2.0.0  my-project, #1                           │
╰──────────────────────────────────────────────────────────╯

┌─ Tasks ──────────────────────────────────────────────────┐
│  ● Add user authentication                               │
│    ├ Planning complete, implementing... (3/5 files)      │
│                                                          │
│  ◐ Fix login validation bug                              │
│    ├ Awaiting approval (press Enter to review)           │
│                                                          │
│  ✓ Add logout button                                     │
│    ├ PR #42 merged                                       │
└──────────────────────────────────────────────────────────┘

Provider: anthropic | Model: claude-sonnet-4-20250514

┌──────────────────────────────────────────────────────────┐
│ > /set                                                   │
└──────────────────────────────────────────────────────────┘
↑↓ to select, Enter to confirm:
> /set           Setup a new repository (interactive)
  /repo list     List repositories
  /repo add      Add a repository
```

#### Header Display

- Shows current repository name and active task number: `my-project, #1`
- Provider status displayed above input with warning if API key is missing

#### Navigation

| Key | Action |
|-----|--------|
| `/` | Show command autocomplete |
| `↑↓` | Navigate commands or tasks |
| `Enter` | Submit prompt or select |
| `ESC` | Go back |
| `Ctrl+C` | Exit |

#### Slash Commands

| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/set` | Setup a new repository (interactive wizard) |
| `/provider` | Configure LLM provider (interactive wizard) |
| `/repo list` | List repositories |
| `/repo add <url>` | Add repository |
| `/repo select` | Select active repository |
| `/repo remove` | Remove repository |
| `/auth status` | Show auth status |
| `/auth login` | Login to GitHub |
| `/auth logout` | Logout from GitHub |
| `/config get [key]` | Get config value |
| `/config set <k> <v>` | Set config value |
| `/config list` | List config keys |
| `/clear` | Clear screen |
| `/quit` | Exit gito |

### Direct Command Mode

```bash
# Authentication
gito auth login      # Login with GitHub PAT
gito auth logout     # Logout
gito auth status     # Show auth status

# Repository Management
gito repo add <url>              # Add repository (clones to ~/.gito/repos/)
gito repo add <url> --path <dir> # Add with custom path
gito repo list                   # List repositories
gito repo select                 # Select active repository
gito repo remove                 # Remove repository

# Development Workflow
gito run "<prompt>"   # Start development workflow
gito status           # Show workflow status
gito resume           # Resume pending workflows

# Configuration
gito config get [key]       # Get config value
gito config set <key> <val> # Set config value
gito config list            # List config keys
```

### Task States

| Icon | State | Description |
|------|-------|-------------|
| `◐` | pending | Awaiting user approval |
| `●` | running | Agent working |
| `✓` | completed | PR merged |
| `✗` | failed | Max retries exceeded |
| `⟳` | retrying | Reworking after review failure |

## Configuration

Configuration is stored in `~/.gito/config.json`.

### LLM Provider

Use the interactive `/provider` command in REPL mode for easy configuration:

```bash
gito
/provider
# Follow the wizard to select provider and enter credentials
```

Or use CLI commands directly:

```bash
# Use Anthropic Claude (default)
gito config set llm.provider anthropic
gito config set llm.model claude-sonnet-4-20250514
export ANTHROPIC_API_KEY=your-key

# Use OpenAI
gito config set llm.provider openai
gito config set llm.model gpt-4o
export OPENAI_API_KEY=your-key

# Use local Ollama (no API key needed)
gito config set llm.provider ollama
gito config set llm.model llama3
gito config set llm.ollamaBaseUrl http://localhost:11434

# Use LiteLLM (100+ models)
gito config set llm.provider litellm
gito config set llm.litellmBaseUrl http://localhost:4000
gito config set llm.model gemini/gemini-1.5-pro
# Set API token if required by your LiteLLM proxy
gito config set llm.litellmApiKey your-token
```

### GitHub Enterprise

```bash
gito config set github.baseUrl https://github.mycompany.com/api/v3
gito config set github.graphqlUrl https://github.mycompany.com/api/graphql
```

### Review Rules

Configure in `~/.gito/config.json` or use CLI:

```bash
gito config set reviewRules.passingScore 85
gito config set reviewRules.maxRetries 5
```

Full review configuration:

```json
{
  "reviewRules": {
    "passingScore": 90,
    "checks": {
      "lint": { "weight": 15, "maxErrors": 0, "enabled": true },
      "tests": { "weight": 20, "passRate": 100, "enabled": true },
      "coverage": { "weight": 10, "threshold": 80, "enabled": true },
      "security": { "weight": 10, "maxCritical": 0, "enabled": true },
      "complexity": { "weight": 5, "maxCyclomatic": 10, "enabled": true }
    },
    "llmChecks": {
      "codeQuality": { "weight": 15, "enabled": true },
      "architectureAdherence": { "weight": 15, "enabled": true },
      "bestPractices": { "weight": 5, "enabled": true },
      "documentation": { "weight": 5, "enabled": true }
    },
    "requiredChecks": ["lint", "tests", "security"],
    "maxBlockers": 0,
    "maxWarnings": 5,
    "maxRetries": 3
  }
}
```

## Architecture

### Agent Pipeline (v2.0)

```
User Prompt
     ↓
[Planning Agent] → User Approval Gate
     ↓
[Design Agent]
     ↓
┌─────────────────────────────────────────────┐
│             Ping-Pong Loop                  │
│  ┌─────────────────────────────────────┐    │
│  │ [Implementation Agent V2]           │    │
│  │  - Uses Tool Use API                │    │
│  │  - read_file, write_file, patch     │    │
│  │  - git_diff, git_status             │    │
│  └─────────────────────────────────────┘    │
│                    ↓                        │
│  ┌─────────────────────────────────────┐    │
│  │ [Review Agent V2]                   │    │
│  │  - Structured feedback              │    │
│  │  - Severity: blocker/major/minor    │    │
│  │  - Score: 0-100                     │    │
│  └─────────────────────────────────────┘    │
│                    ↓                        │
│        Pass? ──┬── Yes → Exit Loop          │
│                └── No  → Iterate            │
└─────────────────────────────────────────────┘
     ↓
[PR Agent] → Done
```

### Core Components

| Component | Description |
|-----------|-------------|
| **Tool Registry** | Manages available tools (file system, git) |
| **Tool Executor** | Executes tools with approval system and timeout |
| **Context Manager** | Builds optimized context from repository |
| **Meta Store** | Persists execution history for learning |
| **Ping-Pong Orchestrator** | Manages implementation/review iterations |

### Available Tools

| Tool | Category | Description |
|------|----------|-------------|
| `read_file` | file | Read file contents with line numbers |
| `write_file` | file | Create or overwrite files |
| `patch_file` | file | Search/replace with fuzzy matching |
| `list_files` | file | List directory contents |
| `git_diff` | git | Show changes |
| `git_status` | git | Show repository status |
| `git_log` | git | Show commit history |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | Anthropic API key (required for anthropic provider) |
| `OPENAI_API_KEY` | OpenAI API key (required for openai provider) |
| `OLLAMA_BASE_URL` | Ollama server URL (optional, default: localhost:11434) |
| `LITELLM_BASE_URL` | LiteLLM proxy URL (required for litellm provider) |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Run tests
npm test

# Lint
npm run lint
```

## License

MIT