@entelligentsia/forgecli

v0.9.4

Published

37 minutes ago

Forge SDLC ported onto @earendil-works/pi-coding-agent — production launcher with three bin aliases (forge/forgecli/4ge). Bundles a curated fork of pi-coding-agent vendored under earendil-works names.

0High
0Medium
0Low

entelligentsia

engineering software — a coding harness for agents. Three aliases: forge · forgecli · 4ge.

forge-cli generates a project-specific engineering knowledge base, sprint workflows, agent personas, and an SDLC pipeline — then drives them from your terminal on the pi-coding-agent runtime. Model-agnostic. No editor lock-in.

Why

Structured SDLC, in any terminal. Plan → implement → review → validate → commit chains, gated by your own personas and audience rules.
Project memory that compounds. Every sprint sharpens the knowledge base; the next one starts smarter.
Bring your own model. Anthropic, OpenAI, ollama, openrouter — anything pi resolves.

Install

curl -fsSL https://4ge.sh | sh

Or via npm directly:

npm install -g @entelligentsia/forgecli

Node 20 or higher. The curl installer checks prerequisites, runs the npm install, and verifies forge is on your PATH.

Quick start

cd your-project
forge                  # launch (forge, forgecli, and 4ge are the same binary)
> /forge:init          # 4 phases, ~45s, idempotent

That's it. Your .forge/ is populated and your first sprint is ready.

Try it on the playground

Don't want to point forge-cli at your real codebase first? Clone the testbench and run a full SDLC cycle on a sample project in ~15 min:

git clone https://github.com/Entelligentsia/forge-testbench
cd forge-testbench/hello   # smallest project — Python · Click · 21 lines
forge
> /forge:init

Three more stacks live in the testbench — TypeScript (cartographer), Go (emberglow), Python+NumPy (spectral). Walkthrough on the testbench README.

What `/forge:init` does

①  collect      5 parallel discovery scans         → .forge/config.json
②  discover     KB docs + project-context          → .forge/project-context.json
③  materialize  substitute placeholders            → .forge/{personas,workflows,…}
④  register     manifest + cache + store entries   → .forge/store/, .forge/cache/

Idempotent and resumable. Re-running picks up at the last checkpoint via .forge/init-progress.json.

Commands

SETUP    /forge:init          Bootstrap Forge SDLC into the project
         /forge:regenerate    Refresh generated workflows + KB
         /forge:update        Check for + apply forge-cli updates
         /forge:remove        Tear down the Forge install

RUN      /forge:run-task      Execute one task pipeline end-to-end
         /forge:run-sprint    Orchestrate every task in a sprint
         /forge:fix-bug       Triage + fix flow

CHAIN    /forge:plan          plan
         /forge:implement     implement
         /forge:review-plan   review the plan
         /forge:review-code   review the code
         /forge:approve       architect approval
         /forge:validate      8-gate validator
         /forge:commit        commit

ASK      /forge:health        KB freshness + store integrity
         /forge:status        Sprint + task status
         /forge:ask <q>       Ask the Tomoshibi concierge
         /forge:config        Set up AI models for your workflow

→ Full reference · Non-interactive mode · Hook safety net · Custom tools · Publishing

Model setup

Forge routes each step of your pipeline — plan, review, implement, validate, approve, writeback, commit — to a specific AI model via a persona. Out of the box, every step inherits whatever model pi is currently running. The /forge:config screen lets you assign models in about 30 seconds.

The three-knob setup

Forge groups its nine personas into three workload tiers:

| Tier | Personas | What this model does | |------|----------|---------------------| | Heavy | 🗻 architect · 🌿 supervisor | Review, sign-off, gates | | Standard | 🌱 engineer · 🐛 bug-fixer · 🍵 qa-engineer · 📋 product-manager | Planning, implementation, validation | | Light | 🍃 collator · 📚 librarian · 🌊 orchestrator | Writeback, indexing, task flow |

Pick one model per tier and you're done — all nine personas are configured.

Step by step

1. Open the config screen

/forge:config

You'll see three tier rows — Heavy, Standard, Light — each showing "not set":

forge config
────────────────────────────────────────────────────────────
Active right now
────────────────
Heavy        not set — falls back to pi current (ollama:qwen2.5:0.5b)
Standard     not set — falls back to pi current (ollama:qwen2.5:0.5b)
Light        not set — falls back to pi current (ollama:qwen2.5:0.5b)
Scope        ▸ project ( ~/src/hello )    global

Choose models for your AI workflow
──────────────────────────────────
▸ Heavy      (review, sign-off)             not set
  Standard   (planning, implementation)     not set
  Light      (writeback, indexing)          not set

  Show what runs at each step
  Advanced — per-persona / per-step overrides

  enter pick model   tab toggle scope   q quit

2. Pick a model for each tier

Press enter on Heavy (or press 1), pick a provider, then a model:

forge config › Heavy › pick provider
────────────────────────────────────
This will run for: 🗻 architect, 🌿 supervisor

▸ anthropic   ✓ authenticated   12 models
  ollama      ✓ authenticated   24 models
  openai      ✓ authenticated   18 models

  ↑↓ select   enter advance   esc back

forge config › Heavy › pick model    (provider: anthropic)
──────────────────────────────────────────────────────────
This will run for: 🗻 architect, 🌿 supervisor

▸ claude-opus-4-5-20250514
  claude-sonnet-4-20250514
  claude-haiku-4-20250514

  ↑↓ select   enter save   esc back

Pressing enter on a model commits it immediately — both personas in that tier are now configured. Repeat for Standard and Light.

3. Done

After all three tiers are set, the landing screen shows your assignments:

Active right now
────────────────
Heavy        anthropic:claude-opus-4-5-20250514         (project)
Standard     anthropic:claude-sonnet-4-20250514           (project)
Light        ollama:qwen2.5:0.5b                         (project)
Scope        project    ▸ global

Choose models for your AI workflow
──────────────────────────────────
▸ Heavy      (review, sign-off)             anthropic:claude-opus-4-5-20250514
  Standard   (planning, implementation)     anthropic:claude-sonnet-4-20250514
  Light      (writeback, indexing)          ollama:qwen2.5:0.5b

  Show what runs at each step
  Advanced — per-persona / per-step overrides

No separate save step — each tier pick writes through instantly.

Scope: project vs global

Press tab to toggle scope before picking a tier:

project — writes to .pi/forge-cli/config.json in the current project. Different projects can use different models.
global — writes to ~/.pi/agent/forge-cli/config.json. Applies to every project that doesn't have a project-level override.

Verify your setup

Select "Show what runs at each step" (or press s) to see which model runs each pipeline step:

forge config › current setup
────────────────────────────
Step           Persona          Model                     Source
─────          ─────────        ──────                    ──────
plan           🌱 engineer       anthropic:claude-sonnet…   Standard tier (project)
review-plan    🌿 supervisor     anthropic:claude-opus-…   Heavy tier (project)
implement      🌱 engineer       anthropic:claude-sonnet…   Standard tier (project)
review-code    🌿 supervisor     anthropic:claude-opus-…   Heavy tier (project)
validate       🍵 qa-engineer    anthropic:claude-sonnet…   Standard tier (project)
approve        🗻 architect      anthropic:claude-opus-…   Heavy tier (project)
writeback      🍃 collator       ollama:qwen2.5:0.5b       Light tier (project)
commit         🌱 engineer       anthropic:claude-sonnet…   Standard tier (project)

How models get picked
─────────────────────
Each step's persona looks for an override at four levels (most specific wins):
 1. A model set just for this step             (Step override)
 2. A model set just for this persona          (Per-persona override)
 3. The tier baseline you set above            (Heavy / Standard / Light)
 4. Whatever model pi is currently running on  (falls back automatically)

Advanced overrides

Select "Advanced" (or press a) for fine-grained control:

Override one persona's model — change the model for a single persona without affecting the rest of its tier.
Override one step's model — change the model for a single pipeline step (e.g. always use a specific model for the commit step).
Edit raw persona-models entries — direct editor for the full persona list.

Most users never need these — the three tier knobs cover the 80% path.

Non-interactive model setup

Use the CLI directly (no TUI required):

# Print the resolved routing table
forge config show --resolved

# Per-phase dispatch trace (no LLM call)
forge config dispatch

# Validate all resolved models are authenticated
forge config show --strict-models

Where to go next

docs/ — CLI flags, non-interactive mode, hook dispatcher, custom tools, publishing
CHANGELOG.md — release history
Playground — try on four sample projects

Roadmap

| Up next | Status | |----------------------------------------------------|---------------------| | Per-persona model routing + tiered config TUI | Shipped (0.9.0) | | 4ge brand wordmark in CLI banner + 3 themes | Shipped (0.7.7) | | Slim README + docs/ split | Shipped (0.7.7) | | Subagent audience relaxed to advisory | Shipped (0.7.6) | | Bundled plugin command markdowns | Shipped (0.7.6) | | /forge:run-task, run-sprint, fix-bug | Shipped (0.7.5) | | Atomic chain shims (/forge:plan … commit) ×6 | Shipped (0.7.5) | | Port admin commands (migrate, calibrate, …) | Roadmap |

→ Full roadmap + history: CHANGELOG.md

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Why