Ivan 🤖

Your AI-Powered Development Assistant that automates complex development workflows by breaking down high-level requests into executable tasks, implementing them with AI assistance, and creating pull requests with properly formatted commits and descriptions.

Installation

npm i -g @ariso-ai/ivan

On first run, Ivan will prompt you to configure API keys and preferences. You can reconfigure at any time with ivan reconfigure.

Quick Start

Running Tasks

Execute tasks directly in your repository:

# Interactive mode - Ivan will prompt you for what to build
ivan

# Or provide a task description directly
ivan "Add user authentication with JWT tokens"

# Or branch work off a specific local base branch instead of main
ivan --base-branch learnings-bootstrap "Add user authentication with JWT tokens"

Ivan will:

Break down your request into manageable tasks
Create branches and implement changes using AI
Generate proper commit messages
Create pull requests with detailed descriptions

Addressing PR Comments

Automatically handle review comments on your pull requests:

# Scan all open PRs and address unresolved comments
ivan address

# Address comments on a specific PR
ivan address 123

# Only process comments from specific reviewers
ivan address --from-user username

Ivan will:

Find all unaddressed inline code comments
Implement fixes using AI
Commit changes with co-author attribution
Reply to comments with the fixing commit

Automated GitHub Actions Workflow

Set up Ivan to automatically respond when tagged in GitHub issues:

# Add the Ivan Agent workflow to your repository
ivan add-action

This creates a GitHub Actions workflow that:

Triggers when someone mentions @ivan-agent /build in an issue
Reads the issue description as the task
Creates a PR with the implementation
Waits 15 minutes for reviews
Automatically addresses any review comments

Required GitHub Secrets (set in your repository settings under Settings → Secrets and variables → Actions):

OPEN_AI_KEY: Your OpenAI API key
ANTHROPIC_KEY: Your Anthropic API key
PAT: GitHub Personal Access Token with repo and pull_requests permissions

Understanding Ivan's Drivers

Ivan offers flexibility in how it authenticates and executes tasks through different driver options.

Claude Execution Drivers

Choose how Ivan runs Claude Code to implement your tasks:

SDK Mode (Default - Recommended)

How it works: Uses the Anthropic API directly via TypeScript SDK
Requires: Anthropic API key (sk-ant-...)
Best for: Users with API access, production environments
Advantages: Reliable, works in CI/CD, better error handling

CLI Mode

How it works: Uses the Claude Code CLI installed on your machine
Requires: Claude Code CLI installed locally
Best for: Claude Max subscribers (no API key needed)
Advantages: Real-time streaming output, no API costs for Max subscribers

Switch between modes:

ivan configure-executor

GitHub Authentication Drivers

Choose how Ivan authenticates with GitHub:

GitHub CLI (Default - Recommended)

How it works: Uses gh auth login for authentication
Requires: GitHub CLI installed and authenticated
Best for: Local development, interactive use
Advantages: Easy setup, secure token management

Setup:

gh auth login

Personal Access Token (PAT)

How it works: Uses a manually created GitHub token
Requires: GitHub PAT with repo and pull_requests permissions
Best for: CI/CD environments, GitHub Actions, automated workflows
Advantages: Works in non-interactive environments

Create a PAT: Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token

Configure:

ivan reconfigure  # Select PAT option during setup

Key Features

🧠 Intelligent Task Breakdown: Analyzes your request and automatically breaks it down into manageable, PR-ready tasks
🤖 Flexible Claude Execution: Choose between SDK (API-based) or CLI (Claude Max) execution modes
🔐 Flexible GitHub Auth: Use GitHub CLI or Personal Access Tokens for authentication
🔄 Automated Git Workflow: Creates branches, commits changes, and opens pull requests automatically
📝 Smart Commit Messages: Generates conventional commit messages using OpenAI's GPT-4
💬 PR Comment Handling: Automatically addresses PR review comments with ivan address command
🔍 Smart Review Requests: Generates context-specific review instructions for each PR using AI
🤖 GitHub Actions Integration: Trigger Ivan automatically when tagged in issues
🎯 Repository-Specific Instructions: Set coding guidelines and patterns that are automatically applied to every task
📊 Progress Tracking: SQLite database tracks all jobs, tasks, execution history, and tool calls
🌐 Web Interface: Built-in web server to view and monitor jobs and tasks in your browser
⚡ Interactive Prompting: Automatically prompts for missing configuration instead of failing

Configuration

Ivan automatically prompts for configuration on first use. Configuration is stored in ~/.ivan/config.json and the database in ~/.ivan/db.sqlite.

Reconfigure at Any Time

# Reconfigure all settings
ivan reconfigure

# Configure specific settings
ivan configure-executor        # Change Claude execution mode (SDK vs CLI)
ivan choose-model              # Select Claude model
ivan configure-review-agent    # Set review bot to tag in PRs
ivan show-config              # View current configuration

Configuration Options

GitHub Authentication: GitHub CLI (gh) or Personal Access Token (PAT)
Claude Executor Type: SDK (API-based) or CLI (Claude Max)
OpenAI API Key: For generating commit messages and PR descriptions
Anthropic API Key: For Claude Code execution (SDK mode only)
Claude Model: Choose between Sonnet 4.5, Haiku, or Opus
Repository Instructions: Optional coding guidelines specific to each repository
Tool Permissions: Configure which tools Claude Code can use per repository

Usage Examples

Interactive Mode

# Start Ivan in any git repository
ivan

# Start Ivan and branch work from a specific local base branch
ivan --base-branch learnings-bootstrap

Ivan will prompt you for what to build, then:

Break down your request into individual tasks
Ask if you want to wait for PR reviews
Execute each task using Claude Code
Create pull requests with detailed descriptions
Optionally wait and automatically address comments

Non-Interactive Mode (Headless)

# Provide task description as an argument
ivan "Add user authentication with JWT tokens"

# Provide a task description and branch from a specific local base branch
ivan --base-branch learnings-bootstrap "Add user authentication with JWT tokens"

# Or use a JSON config file
ivan -c config.json

# Or provide inline JSON config
ivan -c '{"tasks": ["Add authentication", "Add tests"], "prStrategy": "single"}'

Perfect for CI/CD pipelines, automated workflows, and scripting.

Task Examples

Here are some example requests you can give Ivan:

"Add user authentication with JWT tokens"
"Refactor the database module to use TypeScript"
"Add comprehensive test coverage for the API endpoints"
"Implement a caching layer with Redis"
"Fix all ESLint warnings and add proper error handling"

CLI Commands Reference

Main Commands

ivan                    # Run Ivan to execute tasks (default command)
ivan --base-branch dev  # Branch work from a specific local base branch
ivan address [PR#]      # Address PR review comments (optionally specify PR number)
ivan reconfigure        # Reconfigure API keys and settings
ivan add-action         # Add Ivan Agent GitHub Action workflow to repository

Configuration Commands

ivan configure-executor       # Choose Claude execution mode (SDK vs CLI)
ivan choose-model            # Select Claude model (Sonnet, Haiku, Opus)
ivan configure-review-agent  # Set review bot to tag in PRs
ivan show-config            # View current configuration

Repository-Specific Configuration

ivan edit-repo-instructions  # Set coding guidelines for this repository
ivan config-tools           # Configure allowed tools for Claude Code
ivan config-blocked-tools   # Configure blocked tools for Claude Code

Web Interface

ivan web [--port <port>]      # Start the web interface
ivan web-stop [--port <port>] # Stop the web interface

Learnings MVP

ivan learnings init --repo /path/to/repo
ivan learnings ingest-pr --repo /path/to/repo --pr 123
ivan learnings install-hooks --repo /path/to/repo
ivan learnings extract --repo /path/to/repo
ivan learnings rebuild --repo /path/to/repo
ivan learnings query --repo /path/to/repo --text "locks await"

This slice stores canonical learnings as committed JSONL files under .ivan/ and rebuilds a derived local .ivan/db.sqlite for query-time retrieval. Queries read only the local derived database; they do not fetch live GitHub data.

ivan learnings install-hooks --repo ... installs the recommended Claude Code retrieval surface into the target repo's .claude/settings.json:

UserPromptSubmit
PostToolUse(Edit|Write|MultiEdit)
Stop

Address Command Options

# Scan all open PRs for unaddressed comments
ivan address

# Address a specific PR
ivan address 123

# Only process comments from specific reviewers
ivan address --from-user username
ivan address --from-user user1 --from-user user2

# Skip confirmation prompts
ivan address --yes

The --from-user flag is useful for:

Working with specific team members
Prioritizing feedback from senior reviewers
Processing comments i

Ivan

Install / Use

README