Open Agents

AI coding agent framework powered by open-weight models via Ollama.

A multi-turn agentic tool-calling loop that iteratively reads code, makes changes, runs tests, and fixes failures until the task is complete — modeled after how Claude Code operates, but running entirely on local open-weight models.

How It Works

You: oa "fix the null check in auth.ts"

Agent: [Turn 1] file_read(src/auth.ts)
       [Turn 2] grep_search(pattern="null", path="src/auth.ts")
       [Turn 3] file_edit(old_string="if (user)", new_string="if (user != null)")
       [Turn 4] shell(command="npm test")
       [Turn 5] task_complete(summary="Fixed null check — all tests pass")

The agent has 11 tools and uses them autonomously in a loop, reading errors, fixing code, and re-running validation until the task succeeds or the turn limit is reached.

Quick Start

# 1. Install Ollama (https://ollama.com)
curl -fsSL https://ollama.com/install.sh | sh

# 2. Pull the model
ollama pull qwen3.5:122b

# 3. Clone and install
git clone https://github.com/robit-man/open-agents.git && cd open-agents
./scripts/install.sh

# 4. Use it
oa "add pagination to the users endpoint"
open-agents "refactor the auth module into separate files"

Installation

Prerequisites

• Node.js >= 20
• pnpm (npm install -g pnpm)
• Ollama (ollama.com) with a model that supports tool calling

Install System-Wide

# Install to ~/.local/bin (no sudo needed)
./scripts/install.sh

# Install to /usr/local/bin
sudo ./scripts/install.sh --global

# Custom prefix
./scripts/install.sh --prefix ~/bin

# Uninstall
./scripts/install.sh --uninstall

The installer will:

1. Check Node.js and pnpm versions
2. Install workspace dependencies
3. Build all packages
4. Create open-agents and oa symlinks
5. Configure an optimized Ollama model (auto-detects RAM for context window sizing)

Manual Build

pnpm install
pnpm -r build
pnpm -r test   # 911 tests across 77 files

Tools

The agent has access to 11 tools that it calls autonomously:

Self-Learning

When the agent encounters an unfamiliar API or language feature, it automatically:

1. Searches the web for documentation
2. Fetches the relevant page (w3schools.com, MDN, official docs)
3. Stores the learned pattern in persistent memory
4. Applies the knowledge to the current task

Error Recovery

The agent follows an iterative fix loop:

1. Run validation (tests/build/lint)
2. Read the full error output
3. Identify the exact file, line, and failure
4. Fix with file_edit
5. Re-run validation
6. Repeat until passing

Commands

Flags

-m, --model <name>         Model name (default: qwen3.5:122b)
-b, --backend-url <url>    Backend URL (default: http://localhost:11434)
    --backend <type>       Backend type: ollama (default), vllm, fake
-r, --repo <path>          Repository root (default: cwd)
    --dry-run              Show what would happen without writing files
    --offline              Skip backend health check
-v, --verbose              Show model responses and debug info
    --timeout-ms <ms>      Per-request timeout (default: 300000)
-h, --help                 Show help
-V, --version              Show version

Configuration

Config priority: CLI flags > environment variables > ~/.open-agents/config.json > defaults.

# Set defaults
open-agents config set model qwen3.5:122b
open-agents config set backendUrl http://localhost:11434
open-agents config set backendType ollama

# Environment variables
export OPEN_AGENTS_MODEL=qwen3.5:122b
export OPEN_AGENTS_BACKEND_URL=http://localhost:11434
export OPEN_AGENTS_BACKEND_TYPE=ollama

Model Support

Primary target: Qwen3.5-122B-A10B via Ollama (MoE, runs on 48GB+ VRAM)

The setup-model.sh script auto-configures the context window based on available RAM:

Other Models

Any model that supports tool calling via Ollama or an OpenAI-compatible API works:

# Use a different Ollama model
oa --model qwen2.5-coder:32b "fix the bug"

# Use vLLM backend
oa --backend vllm --backend-url http://localhost:8000/v1 "add tests"

# Use any OpenAI-compatible API
oa --backend-url http://10.0.0.5:11434 "refactor auth"

Architecture

Agentic Loop

The core is AgenticRunner — a multi-turn tool-calling loop:

User task
    ↓
System prompt + tools → LLM
    ↓
LLM returns tool_calls → Execute tools → Feed results back → LLM
    ↓  (repeat until task_complete or max turns)
Result: completed/incomplete, turns, tool calls, duration

Key design decisions:

• Tool-first: The model explores via tools rather than pre-stuffed context
• Iterative: Tests, sees failures, fixes them — no need for perfect one-shot output
• Context compaction: Long conversations are compressed, preserving only recent context
• Bounded: Maximum turns, timeout, and output limits prevent runaway loops
• Observable: Every tool call and result is emitted as a real-time event

Package Structure

packages/
  orchestrator/   - AgenticRunner, OllamaAgenticBackend, RALPH loop
  execution/      - 11 tools (file, shell, grep, web, memory), validation pipeline
  schemas/        - Zod schemas and TypeScript types
  backend-vllm/   - Ollama + vLLM backend clients (OpenAI-compatible)
  memory/         - SQLite-backed persistent memory stores
  indexer/        - Codebase scanning and symbol extraction
  retrieval/      - Multi-stage retrieval (lexical + semantic + graph)
  prompts/        - Prompt contracts for each agent role
  cli/            - CLI entry point, commands, config, UI

apps/
  api/            - Express API server
  worker/         - Background task processor

eval/             - 8 evaluation tasks with agentic runner
scripts/          - install.sh, setup-model.sh, bootstrap.sh

Evaluation

The framework includes 8 evaluation tasks that test the agent's ability to autonomously resolve coding problems:

# Run all 8 tasks with agentic tool-calling loop
node eval/run-agentic.mjs

# Single task
node eval/run-agentic.mjs 04-add-test

# Different model
node eval/run-agentic.mjs --model qwen2.5-coder:32b

Results (Qwen3.5-122B)

TASK                 RESULT   TIME       TURNS    TOOLS
01-fix-typo          PASS     39.1s      4        7
02-add-function      PASS     24.5s      4        5
03-fix-bug           PASS     26.9s      4        5
04-add-test          PASS     198.1s     6        8
05-refactor          PASS     73.1s      4        5
06-type-error        PASS     143.2s     5        7
07-add-endpoint      PASS     40.0s      4        5
08-multi-file        PASS     75.5s      8        13

Pass rate: 100% (8/8)
Total: 39 turns, 55 tool calls, ~10 minutes

Task Descriptions

Test Suite

Package          Tests
─────────────────────────
schemas          216
backend-vllm     162
execution        136
indexer            94
cli                72
orchestrator       70
retrieval          66
memory             58
prompts            34
apps/api            1
apps/worker         2
─────────────────────────
Total             911 passing

Development

pnpm install          # Install dependencies
pnpm -r build         # Build all packages
pnpm -r test          # Run all 911 tests
pnpm -r dev           # Watch mode

License

MIT