# local-coder

> Turn local AI models into a private, verified team of coding agents by building a hardware-aware multi-agent environment on top of Ollama and OpenCode.

local-coder is an open-source CLI tool that transforms locally-run AI models into a structured, verified team of coding agents. Built on top of Ollama and OpenCode, it detects your machine's hardware, recommends models that fit within memory and disk budgets, assigns them to seven specialist roles, and generates a permission-restricted workflow — all without sending code or prompts to external services.

## What It Is

local-coder sits between raw local inference and a dependable coding-agent setup. Running a model locally via Ollama is straightforward; building a reliable multi-agent workflow around it raises harder questions about model selection, role assignment, tool-call verification, and safe configuration management. local-coder treats those as a single setup problem, producing a validated OpenCode environment from a single command.

## The Seven-Role Agent Team

The generated environment assigns models to seven specialist roles that OpenCode can orchestrate:

- **Orchestrator** — classifies requests, selects workflows, creates task contracts, and manages retries
- **Explorer** — reads files, symbols, and execution flow without editing
- **Planner** — converts repository findings into ordered implementation guidance
- **Researcher** — fetches external documentation via configured web tools when needed
- **Coder** — makes repository changes, rereads diffs, and runs proportionate validation
- **Verifier** — independently inspects repository state and contract outcomes; cannot edit
- **Reviewer** — examines significant verified changes for defects, regressions, and security issues

The orchestrator selects the least costly workflow for each task, ranging from a trivial `Coder → Verifier` path to a full `Explorer + Researcher → Planner → Coder → Verifier → Reviewer` chain for domain-heavy work.

## Verification: Repository State, Not Model Output

The project's core principle is that agent claims are not evidence — repository state determines success. Setup runs four layers of probes before writing any configuration:

1. **Inference** — each context variant returns a valid response and Ollama confirms the required context is loaded
2. **Tool use** — the model emits a structured tool call with the exact argument; JSON returned as plain text does not pass
3. **Role behavior** — the coder must read, modify, and reread a file; the orchestrator must delegate; the verifier must reject seeded failing evidence; the reviewer must catch a seeded path-traversal defect
4. **End-to-end workflow** — OpenCode is launched against a temporary repository, the orchestrator must delegate a precise README edit, the file must match expected bytes on disk, and the event trace must contain a completed coder task followed by verifier `PASS`

Any failed live probe blocks configuration from being written.

## Hardware-Aware Model Selection

local-coder reads total system memory (including unified memory on Apple Silicon), NVIDIA VRAM on Linux, free disk space, and the installed Ollama catalogue to recommend models. The bundled schema-v2 catalogue contains 27 canonical local tags across compact, workstation, and large-memory tiers — from `qwen3:8b` to `qwen3-coder:480b`. Four presets (`balanced`, `quality`, `fast`, `minimal`) cover common hardware profiles; an interactive custom flow lets users assign any compatible Ollama tag to any role. Context variants use 32K, 64K, or 128K token windows based on hardware tier, sharing source model weights to avoid redundant downloads.

## Privacy and Permission Boundaries

All Ollama requests go to `127.0.0.1` only. OpenCode sharing is disabled by default. No prompts, source code, hardware details, or telemetry are uploaded. Role permissions enforce a least-privilege model: only the Coder can edit files, `git push` is denied for all roles, and external-directory access is blocked for every agent. Repository content is treated as untrusted data rather than instructions.

## Safe, Reversible Setup

Before writing anything, local-coder shows the full plan — model downloads, context variants, every file it will create — and requires confirmation. Existing OpenCode configuration is merged rather than replaced. Uninstall restores pre-existing files, removes only models downloaded for that scope, and preserves user edits made after setup. A `--dry-run` flag previews the entire plan without downloading or writing anything.

## Features
- Hardware-aware model selection for Ollama
- Seven specialist coding agent roles
- Adaptive workflow orchestration (Trivial, Standard, Complex, Domain)
- Four-layer capability verification (inference, tool use, role behavior, end-to-end)
- Task contracts with protected values and validation commands
- Permission-restricted role boundaries
- Dry-run preview before any changes
- Safe, reversible installation with timestamped backups
- Global and project-scoped configuration
- 27-model bundled catalogue across compact/workstation/large-memory tiers
- Context variants (32K/64K/128K) sharing source model weights
- Deterministic contract verification via CLI
- Reinstall and uninstall commands
- Custom catalogue support via --catalog flag
- No external telemetry or data upload

## Integrations
Ollama, OpenCode, Node.js, Git, ripgrep, NVIDIA CUDA (VRAM detection), Apple Silicon unified memory

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/gmarland/local-coder
- Documentation: https://github.com/gmarland/local-coder/blob/main/REPO_MAP.md
- Repository: https://github.com/gmarland/local-coder
- EveryDev.ai: https://www.everydev.ai/tools/local-coder