local-coder

local-coder [setup|configure|reinstall|uninstall|status|models] [options]local-coder verify-contract contract.json [--root path] [--baseline json] [--changed path ...]

local-coder builds a local coding-agent environment on top of Ollama and OpenCode. It reads the machine's memory, GPU, and disk, picks models that fit, and assigns them to seven roles: orchestrator, explorer, planner, researcher, coder, verifier, and reviewer. A single model may fill several roles. The minimal preset uses one model for all seven.The orchestrator is the user-facing OpenCode agent. It is instructed to pick a workflow instead of calling every role every time: coder then verifier for a trivial edit, explorer then coder then verifier for ordinary work, and planner plus reviewer when the change is larger. The researcher is for configured web lookups, not for ordinary repository edits.Setup's probes check more than a model reply. A selected model must emit a real tool call, the coder role must edit a temporary file and reread it, the orchestrator must delegate, the verifier must reject seeded bad evidence, and an end-to-end OpenCode run must leave the expected bytes on disk with a completed coder task and a verifier pass. If those live probes fail and the runtimes are available, setup refuses to write the configuration.The package also installs the command as setup-ai. Both names run this same program. With no subcommand, either name starts setup.The documented install is a clone of the repository, then npm install and npm link inside it (Node.js 20 or newer). That link step puts local-coder and setup-ai on PATH. The prepare script compiles TypeScript during install.

--project [path]

Write <path>/.opencode instead of ~/.config/opencode. With no path, the current directory is used.

One of balanced, quality, fast, or minimal. minimal reuses one compatible model for every role.

Read a compatible versioned model catalogue. The bundled catalog/models.json is the offline fallback.

Accept defaults without the interactive confirmation.

Copy existing generated files aside before replacing them. Interactive setup offers backups on its own. --yes creates them only when this flag is set.

Do not download models. Context variants are created only from models already present.

Skip inference and runtime probes. Setup then warns that the configuration was not validated.

Print the plan and exit. Nothing is written or downloaded.

Print the usage summary. The summary names the command local-coder even when you launched the setup-ai alias.

Global setup writes ~/.config/opencode. --project writes <path>/.opencode instead.A finished setup leaves opencode.json (or merges an existing opencode.jsonc), AGENTS.md, one markdown file per role under agents/, local-coder-state.json, and local-coder-ownership.json. Unrelated providers, MCP servers, plugins, and instructions in an existing config are kept. Invalid existing JSON stops setup before it overwrites anything.Cross-scope model ownership is recorded in ${XDG_DATA_HOME:-~/.local/share}/local-coder/registry.json. Older installs without ownership records are left for manual review rather than deleted on a guess.Ollama traffic from this tool goes to 127.0.0.1. OpenCode sharing stays disabled unless the existing config already says otherwise. Model downloads and npm install still use the network. If the researcher role uses configured web tools, those queries leave the machine.

setup

Default when no command is given. Detect hardware, recommend models, assign roles, write OpenCode configuration, and run capability probes.

Same operation as setup.

Show the recorded setup for the selected global or project destination.

Show catalogue recommendations for this machine.

Rewrite generated configuration and agent files from the last saved selection. It does not download, replace, test, or remove Ollama models.

Restore files that existed before setup, delete files this tool created, and remove models downloaded for that scope when no other local-coder scope still uses them. Pre-existing and shared models stay.

Check file existence, contents, hashes, JSON pointers, changed paths, protected values, and validation results for one task contract. The process exits unsuccessfully when anything disagrees. Validation commands are an executable plus an argument array, run without a shell.

Requires macOS or Linux, Node.js 20+, a running Ollama when models must be downloaded or tested, and OpenCode for the generated environment. The project states that the smallest bundled option needs about 9 GB of usable model memory and 11 GB of free disk, plus a 5 GB reserve after downloads. Git and ripgrep are detected and recommended.Probes show that the chosen models completed a controlled workflow at setup time. Later interactive tasks still depend partly on the generated agent instructions. --skip-validation writes a configuration that has not been checked.verify-contract rejects shell-string validation commands, disallowed operations, and working directories outside the repository. Semantic requirements in a contract still need the verifier agent. The command exits unsuccessfully when the contract and the tree disagree.uninstall keeps timestamped backups, because they may contain user data. It removes a model only when no remaining local-coder scope uses it.

local-coder was published in September 2026 (GitHub repository created 2026-09-16). It is written in TypeScript and released under the MIT License. The npm registry does not host a package by this name; the command is linked from a checkout.

setup-ai(1), opencode(1), ollama(1), node(1), npm(1), rg(1), git(1)

Source code · Documentation