Forge

A local-first AI development environment. A tuned local model sized to your RAM does the high-volume implementation work: forge-coder via Ollama, built on qwen3-coder:30b on 24GB+ machines (qwen3-coder-next at 48GB+) and on qwen2.5-coder 14b or 7b below that. Claude plans and verifies. Zero token cost and full privacy during execution.

Status: Pre-1.0. The full local loop works end-to-end, including forge agents run --apply. Forge ships on PyPI (tolvi-forge); there is no Homebrew formula (see RELEASE.md). See ROADMAP.md.

The workflow

Magellan or Claude Code (plan → tasks.json) → Forge (execute, local, $0) → Claude (verify diff)

Claude is better at thinking; the local model is better at doing at scale. Forge is the execution layer between them. It indexes your codebase, answers questions with that code (and your decisions) in context, drives a tasks.json plan task-by-task, and hands the diff back for review.

Magellan compiles a Bastion-hardened brief into a tasks.json in the repo (docs/superpowers/plans/YYYY-MM-DD-<feature>-tasks.json). Each task names the files it may change, its acceptance criteria, and the context it needs: the vault decisions, code references, and interfaces that bear on it. Forge runs that plan on the local model with forge plan load <tasks.json> --path <repo> and forge agents run --apply --path <repo>. For each task, the model sees the task's files in full plus that context and edits them; the tests Canary selects for the diff must pass, a review agent checks the diff against each acceptance criterion, and each task that clears both is committed on a forge/<feature> branch. A task that fails is rejected with its reason and the tasks that depend on it are skipped, so you or Claude can pick it up. Review the branch with forge verify, then record each task with forge outcome. Claude Code can produce the tasks.json too: the /forge command portions a hardened plan into one, or loads an existing Magellan plan directly.

Tolvi is the substrate

Forge runs standalone. But it runs best with Tolvi, the per-repo engineering-knowledge vault. Tolvi is the engine oil. A local model that knows what the code is makes plausible changes; a model that also knows why the codebase is the way it is (the decisions and rejected alternatives captured in a Tolvi vault) makes changes that respect intent. When a vault/ exists in your repo, Forge feeds it into the model's always-on context.

Already have a Tolvi vault? If your vault lives outside the repo (e.g. a standalone Tolvi setup with a shared ~/vaults/my-project/ directory), point Forge at it with the FORGE_VAULT env var instead of symlinking:

export FORGE_VAULT=~/my-vault/my-project
forge chat -m "how does sign-in work?"

Add it to your shell profile or a per-project .envrc (via direnv) so it's always set when working in that repo.

You may not need it. A solo dev on a greenfield repo, or a team without a decision vault, gets full value from Forge's code retrieval alone. Tolvi is the multiplier, not the dependency.

Install

Install the CLI from PyPI, then bring up the local models:

pipx install tolvi-forge
# or: pip install tolvi-forge

forge detect-hardware   # picks the model tier your RAM can run
forge start             # pulls the Ollama models and builds forge-coder on first run
forge doctor            # diagnose any missing pieces

pipx is recommended over pip for CLI tools: it installs Forge into its own isolated environment rather than your active virtualenv, avoiding dependency conflicts with whatever else you have installed. No Homebrew formula yet; Forge's dependency tree (ChromaDB, tree-sitter, tiktoken) doesn't fit Homebrew's typical vendored-resource packaging model well, so PyPI is the primary distribution channel.

For a fully guided setup (hardware detection, model pulls, and the Continue.dev + MCP editor configs written for you) install from source:

git clone https://github.com/tolvi-labs/forge && cd forge
bash setup/bootstrap.sh

The installer detects your hardware, pulls the right Ollama models, builds the forge-coder model, installs the CLI into a dedicated Python 3.12 venv, writes the Continue.dev + MCP configs, and symlinks forge into ~/.local/bin (adding it to PATH in your shell profile if needed).

forge start is also the command to use after a reboot or in a fresh shell: it starts Ollama in the background and leaves it running. forge stop shuts down that server (only if Forge started it).

VS Code (Continue.dev): optional keystroke assist

Forge's real surface is the batch loop above: a frontier model plans, the local model executes a whole task set, and you review the diff. This section is the other altitude: opt-in, in-editor assistance for when you want a local model at your cursor. It runs entirely on your hardware, so treat it as best-effort: on a laptop, local autocomplete will not match a cloud tool's latency, and that is a hardware reality rather than a defect Forge is hiding. Reach for the batch loop when you want the local model's real strength; reach for this only when you want a quick local completion or edit without leaving the editor.

Bootstrap writes the Continue config to ~/.continue/config.yaml automatically. To finish the setup:

1. Install the Continue extension in VS Code.
2. Open the Continue panel (sidebar). It will pick up ~/.continue/config.yaml on first load.
3. Confirm Ollama is running (ollama list should show forge-coder and qwen2.5-coder:7b).

The config wires four models automatically:

• Chat / Edit / Apply → qwen2.5-coder:7b (fast, best for everyday coding questions)
• Chat (Deep) → forge-coder (the tuned model sized to your RAM, long context, switch to this for architecture or multi-file work)
• Autocomplete → qwen2.5-coder:7b (best-effort; latency tracks your hardware)
• Embeddings → nomic-embed-text

MCP tool integrations (git, github, jira, gcloud, firebase, context7, sequential-thinking, playwright) are configured for Claude Code, not Continue.dev. See mcp/servers.json. Wiring MCP servers into Continue.dev injects tool definitions that cause smaller models to emit tool-call JSON instead of answers.

Quickstart

forge index .                       # index this repo (incremental, respects .gitignore)
forge search "auth token refresh"   # inspect what retrieval returns
forge chat -m "how does sign-in work?"   # ask, with CAG+RAG (and your Tolvi vault) in context

# Claude → Local → Claude
forge plan load tasks.json          # load a Magellan or Claude Code plan (schema-validated)
forge agents run --apply            # the local model implements every task, one commit each on forge/<feature>
forge verify                        # export the diff + manifest for Claude to review

Commands

Measuring the local-model gate

Forge can tell you whether the local model is actually pulling its weight, as a byproduct of the normal plan loop. With --apply, the model's work is already committed per task on the forge/<feature> branch, so review the branch, fix what it got wrong, and record each task's outcome:

forge agents run --apply        # one commit per approved task; rejected tasks are recorded automatically
# ...you review the branch diff and fix anything the model got wrong...
forge outcome task-001          # auto-fills rework churn + local tokens; prompts for accepted/trust/type

Rework is your change on top of the model's last commit, counted on the files each task edited last, so a later task's edits to a shared file never count against an earlier one. Run forge agents run --apply again on the branch to retry rejected or skipped tasks; it resumes rather than starting over. Driving tasks by hand works too: forge plan complete task-001 commits that task's files, and forge outcome must then run before forge plan next touches the same files, because the working-tree delta on the task's files is what it counts as your rework. When you want the picture across a plan, or across every plan and repo, pool it:

forge report          # this plan: acceptance rate, median churn, tokens, mean trust
forge report --all    # pooled across all plans, broken down by task type

Acceptance rate is the "is the local model good enough" number, and rework churn is whether fixing its output eats the token savings.

How it works

• Index: Tree-sitter AST chunking across 9 languages (with a line-based fallback), local embeddings via nomic-embed-text, a ChromaDB store with file-checksum incremental re-indexing.
• Context: a hybrid CAG + RAG window: stable always-on context (manifests, README, the Tolvi vault) plus the top semantically-relevant code chunks (hard-capped to avoid lost-in-the-middle), tuned per stack profile.
• Workflow: tasks.json is the Claude↔Forge handoff contract; Forge validates it, keeps each task's plan context, has the local model edit with SEARCH/REPLACE blocks it applies and checks itself, commits each approved task on its own branch, and exports a verifiable diff. At apply time the model sees each task's files in full, the task's plan context (decisions, code refs, interfaces), and related code from forge index when the repo is indexed, within a budget sized to the smaller of the stack profile's and the hardware's context window, less a reply reserve.
• Editors & tools: Continue.dev (VS Code, primary) and Cursor against the same Ollama backend; a pre-wired, npm-verified MCP layer (git, github, jira, gcloud, firebase, context7, sequential-thinking, playwright) configured for Claude Code.

Everything runs locally. No code leaves the machine during execution. Design decisions live in vault/decisions/.

License

Apache 2.0.