Immutable. This exact content is served forever at /api/v1/blob/292432d228ca0bc2.
# Forge repository guidance ## Overview Forge is a local-first, model-agnostic AI coding harness and CLI implemented as a Rust Cargo workspace. One session core serves terminal, headless, remote web, mobile, and desktop surfaces; Model Mesh routes provider work, Store persists the audit trail, and Lattice provides local code intelligence. ## Verified checks Run these from the repository root: ```bash cargo fmt --all -- --check cargo clippy --locked --all-targets --all-features FORGE_DB="$(mktemp -d)/forge.db" cargo test --locked --all --all-features cargo build --release --locked --bin forge ``` `FORGE_DB` on the test command is not optional — see **Never let a dev build touch the real store** below. A handful of tests open the default store when it is unset, and doing so has taken the user's daemon down four times. The first command was verified during setup. The remaining commands are the repository's documented workspace checks in `CONTRIBUTING.md`; CI runs the same checks with `RUSTFLAGS=-D warnings`. The workspace uses the stable Rust toolchain with `rustfmt` and `clippy` components, and requires Rust 1.88 or newer. ## Architecture - `crates/` is the Cargo workspace and modular monolith. `forge-cli` is the binary/composition root; `forge-core` owns the session/agent loop and permission broker. - `forge-types` holds shared domain types; `forge-config` handles layered configuration and secrets; `forge-store` encapsulates SQLite persistence. - `forge-provider` abstracts model providers; `forge-mesh` performs task routing and failover; `forge-tools` owns coding tools; `forge-lsp` supplies live diagnostics; `forge-mcp` integrates MCP. - `forge-tui` renders terminal interactions through presenter adapters. Keep the session core's Interaction interface surface-independent. - `forge-index` implements Lattice code intelligence. Architecture decisions are recorded in `docs/architecture/decisions/`; substantial design changes should add an ADR or RFC. ## Never let a dev build touch the real store The single most damaging recurring failure in this repository, four times so far (2026-07-17, twice on 2026-08-06, 2026-08-07). A binary built from a working tree opens `~/.local/share/forge/forge.db` and runs whatever migrations the checked-out branch carries. The installed release binary then refuses that store — `SchemaTooNew`, which is correct — and `forge serve` cannot start. The last occurrence left the daemon at 632 consecutive failed restarts with Forge Anywhere dark throughout, and recovery needs a hand-written `PRAGMA user_version` write. Rules: - **Tests**: always pass `FORGE_DB` pointing somewhere disposable. Never run the suite bare. - **MCP server entries** pointing at `target/debug/forge` (this repo's own `.mcp.json` and the untracked `.forge/mcp.toml`) must set `FORGE_DB` to a dev store. An agent session started on a feature branch is otherwise enough to migrate production data. - **Anything that spawns a child** which may reach a `forge` binary must scrub `FORGE_DB` from the child's environment unless the child genuinely shares this store — `claude --print` loads the project's `.mcp.json` and can spawn a `forge` grandchild that inherits it. - Deliberately debugging against real data is fine — set `FORGE_DB` explicitly and know why. Prevention lives in the code too: a `debug_assertions` build resolves to `forge-dev.db` rather than the release store, so `cargo run` and `target/debug/forge` are isolated by default. Treat that as a backstop, not a reason to drop the rules above — a release-profile build ignores it. ## Conventions - Keep changes focused and explicit; comments should explain why rather than restate code. - Add or update tests for new behavior and regressions where practical. - Route side effects through the permission broker and keep SQLite access inside Store. - Use branch names `feat/<slug>`, `fix/<slug>`, `refactor/<slug>`, `docs/<slug>`, `chore/<slug>`, `ci/<slug>`, or `perf/<slug>`. - Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `perf:`, `ci:`). - Do not edit generated or unrelated files. Before submitting, run the applicable formatting, lint, test, and build checks above.