forge

Important

Forge is deprecated and in maintenance mode. It served as an incubator for agent workflow patterns that now live in focused successor repositories. See the deprecation plan.

Migrate away from Forge

Update to the final migration release, then preview the cleanup:

forge self update --json
forge cleanup --json

Install the successor repositories you need from the commands in the preview. Then apply the cleanup:

forge cleanup --apply --json

Cleanup backs up Forge-managed state under ~/.config/forge/deprecation-backups/, preserves diverged Codex files for manual review, and prints the final command for removing the Forge binary.

Forge retains its Rust compatibility CLI, release machinery, and small Codex configuration adapter for existing users. New workflow development belongs in the successor repositories.

Forge is not the general home for portable skills or engineering-domain knowledge. Use iancleary/skills for portable workflow skills and iancleary/rfstack for RF engineering skills. Forge does not manage general dotfiles, application preferences, operating-system settings, global packages, language toolchains, or external skill repositories. See docs/scope.md.

Existing installations

New users should install the relevant successor repositories instead. Existing users can use install.md for recovery or compatibility installs.

Nix and Home Manager are the preferred ownership layer for macOS, WSL Arch Linux, and NixOS systems. The initial Nix packaging and Home Manager module are follow-up work. Until they exist, install a release with the portable installer:

curl -fsSL https://raw.githubusercontent.com/iancleary/forge/main/scripts/install-forge-release.sh | sh

Native Windows x64 uses PowerShell:

irm https://raw.githubusercontent.com/iancleary/forge/main/scripts/install-forge-release.ps1 | iex

Forge publishes only aarch64-apple-darwin, x86_64-unknown-linux-gnu, and x86_64-pc-windows-msvc. WSL uses the Linux installer. Windows ARM and 32-bit Windows are not supported.

The installer:

• resolves the latest published release by default
• downloads the platform archive and checksum manifest from one release tag
• verifies the archive SHA-256 before extraction
• validates the complete archive before replacement
• replaces the complete binary set atomically
• fails without installing if no matching binary artifact is available
• installs Forge-managed skills under ~/.agents/skills
• installs the Forge-managed Codex baseline under ~/.codex

Pin a release when deterministic recovery is required:

curl -fsSL https://raw.githubusercontent.com/iancleary/forge/20260802.0.0/scripts/install-forge-release.sh | sh -s -- --tag 20260802.0.0

Use --skip-codex to install binaries and skills without changing the Codex baseline. Use --build-from-source only for an explicit development or recovery build. The default deployment path never installs or requires a Rust toolchain.

Use --verify-attestation for explicit GitHub provenance verification. It requires gh and fails closed if verification is unavailable or fails. The POSIX destination is ~/.cargo/bin. The Windows destination is %LOCALAPPDATA%\Forge\bin; neither installer changes PATH automatically.

Managed AI surfaces

Forge retains:

• the forge-tools and forge-cli compatibility skills
• Codex user policy and targeted configuration fragments

Install portable skills and domain packs through their own repository contracts. Nix or Home Manager may pin those sources for managed machines. Forge does not proxy their installation.

Common commands

forge cleanup
forge doctor
forge version
forge self update-check
forge skills status
forge skills validate --all
forge codex diff

forge self update is the portable non-Nix update path. A future Nix package must leave binary and package updates to Nix while retaining Forge's read, render, diff, validation, and asset contracts.

Development

Read the relevant spec under docs/ before changing a command. Then run:

cargo check
cargo test
just install-list-check

Install a development checkout with:

cargo run -p forge -- dev install --repo-path "$(pwd)"
forge skills install --all --source repo --repo-path "$(pwd)"

Workspace binaries

• forge: managed AI assets, releases, diagnostics, and skill-backed helpers

Successor repositories

Release workflows live in iancleary/release-skills. Mermaid and bytefield tooling lives in iancleary/structured-diagrams. Slack tooling lives in iancleary/slack-skills. Codex session retrieval lives in iancleary/codex-threads. The retired Linear tooling remains discoverable in iancleary/linear-skills.

All read-oriented CLI surfaces should provide stable compact JSON for agents and useful human output by default.