ForgeFlow CLI: coordinating coding agents with file scopes and checkpoints

Ravan Sariyev — Mon, 09 Nov 2026 10:11:22 +0000

A long coding task can involve understanding a repository, planning a change, editing files, inspecting a UI, and recovering after an interruption. Adding parallel workers introduces another problem: conflicting edits.

ForgeFlow CLI is an open-source Node.js terminal tool that organizes this workflow around scoped tasks and persistent checkpoints. It is currently an early preview.

Plan before scheduling

ForgeFlow requests a structured task plan and validates file scopes and dependencies. A task waits for its prerequisites. Overlapping writable scopes are rejected, so independent workers are not deliberately assigned the same file.

This is a coordination rule, not proof of correctness. A plan can misunderstand a feature, and completed work can still need review.

Make progress recoverable

Each run records its plan and task statuses locally. Completed tasks are checkpointed. When a run resumes, unfinished tasks return to the queue while completed tasks remain complete.

forgeflow status --dir ./my-app
forgeflow resume --run-id <run-id> --dir ./my-app

The state and event logs help investigate provider errors, process interruptions, and task failures. Remove secrets and private project content before sharing logs.

Keep browser data compact

Optional Playwright tools give each worker an isolated Chromium context. The model receives semantic snapshots of headings, links, buttons, and fields, then acts on references from a recent snapshot.

Screenshots can be saved locally. They are not included as base64 image input in provider requests. That avoids large image payloads, with a clear tradeoff: this path does not give the model screenshot-based visual understanding.

Put boundaries around long runs

The CLI limits retained context, tool output length, estimated total tokens, API calls, and concurrency. Provider usage is recorded when available; other token accounting uses character-based estimates.

These are engineering limits, not exact tokenizer measurements, a currency spending cap, or a benchmark about savings.

Start with a small task

You need Node.js 20+ and an authorized API key from a compatible provider.

git clone https://github.com/rvnsre/forgeflow-cli.git
cd forgeflow-cli
node ./bin/forgeflow.mjs doctor
node ./bin/forgeflow.mjs --help

Set OPENAI_API_KEY in your shell, then start with a disposable project copy and low concurrency:

node ./bin/forgeflow.mjs run --dir ./my-app --agents 2 "Inspect the README and improve the setup instructions to match the existing project."

Shell execution and browser tools are opt-in. Shell commands run with your operating-system permissions; this is not a container sandbox. Read the README before enabling them.

What needs validation next

Syntax checks and installation diagnostics have been run. Live provider workflows, browser interactions, recovery edge cases, and platform compatibility still need reproducible validation.

Up to 256 task slots are configurable, but that is a capacity setting, not a throughput benchmark. Four workers are the default. Practical throughput depends on provider limits, your machine, and task dependencies.

The next priorities are small end-to-end examples, targeted reliability coverage, and clearer diagnostics. Feedback is most useful with a minimal reproduction, exact environment, and redacted logs.

Source, setup, contribution guide, and roadmap

If you try it, which matters most in your workflow: file scope coordination, checkpoint recovery, or compact browser inspection?

Disclosure: This article and the project illustrations were prepared with AI assistance. Illustrations are conceptual artwork, not application screenshots.