Forge

A hierarchical multi-agent coding assistant, run from your terminal against your own repository, powered by the Anthropic API.

Instead of one model doing everything in a single loop, Forge splits the work across four role-specialized agents that hand off to each other, with real validation and a human approval gate in between:

Planner (read-only) → Coder (writes code) → automated lint/type/test
    → Tester (verifies) → Reviewer (read-only) → you approve → git commit

If the Tester or Reviewer isn't satisfied, Forge sends the Coder specific feedback and retries (bounded — it won't loop forever).

Install

git clone https://github.com/octaboomai/forge.git
cd forge
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
export ANTHROPIC_API_KEY=sk-ant-...

Quickstart

cd /path/to/your/project
forge init            # optional: creates .forge/config.json for team guardrails
forge run "add input validation to the login endpoint"

Forge will:

1. Build a compact map of your repo (function/class signatures, not full files)
2. Have the Planner turn your task into concrete steps
3. Let the Coder implement it (asking your approval before running any shell command)
4. Auto-run whatever lint/type-check/test tools it detects in your repo
5. Have the Tester and Reviewer agents sign off (or send it back for a fix)
6. Ask you to approve the final commit

Other commands:

forge map                        # see the repo map Forge builds before planning
forge map -q "auth login"        # see just the files relevant to a query
forge sessions                   # list past runs
forge log <session_id>            # inspect what an agent actually did, step by step

Team guardrails

forge init creates .forge/config.json:

{
  "guardrails": ["Never weaken authentication checks"],
  "forbidden_paths": ["**/migrations/**", "**/*.pem", "**/secrets/**"],
  "approval_required_for": ["shell", "git_push"],
  "model_overrides": {}
}

Commit this file to your repo — every agent gets these guardrails prepended to its instructions, and forbidden_paths is enforced at the file-write layer, not just requested of the model.

Architecture

• forge/agents/ — Planner, Coder, Tester, Reviewer. All four share one generic tool-use loop (agents/base.py); what differs is the system prompt and which tools each role is allowed to touch (Planner and Reviewer are read-only).
• forge/context/repo_map.py — builds a symbol-level map of the repo using tree-sitter where a grammar is available, falling back to a regex heuristic otherwise. Ranks files by relevance to the task before handing them to an agent, so context stays small.
• forge/tools/ — file read/write/patch (path-restricted to the repo, guarded against team-configured forbidden paths), sandboxed shell exec (blocklist + timeout), and git operations.
• forge/validation/runner.py — auto-detects and runs whatever's actually present in your repo (ruff/mypy/pytest/bandit for Python, eslint/tsc/npm test for JS/TS, cargo check/test/clippy for Rust).
• forge/events/store.py — append-only SQLite event log. Every model call, tool call, approval decision, and edit is recorded per session, so a run can be inspected (forge log) or extended to resume after a crash.
• forge/router.py — maps each agent role to a model tier (fast/core/deep) and tracks token usage per session.

What's in this build vs. the original concept

This implements the actual agent pipeline, context engine, validation layer, event store, and guardrail system end-to-end, and it's tested (see tests/test_smoke.py) — not just a scaffold.

Not included, and each would be its own separate project:

• IDE extensions (VS Code / JetBrains / Neovim)
• A web dashboard / team UI
• A REST API for CI/CD integration
• A genuine local-model backend (Ollama/vLLM) — router.py has a clean extension point for this (ModelRouter.complete), but today "fast" vs. "core" vs. "deep" all route to Claude models via the Anthropic API, not to a local/cloud split.
• Semantic embeddings / vector search for context ranking — the current relevance ranking is a fast token-overlap heuristic, which is cheap and dependency-free but cruder than embeddings on a very large repo.

Running the test suite

pip install pytest ruff
pytest -q