forgeo-cli 0.6.0

Forgeo is a software factory for your coding-agent. You're already working with an AI coding agent, prompting it task by task or giving it a goal. Forgeo organizes your work in a structured way with a backlog, and it decides what to work on next, runs your agent on it, and commits the result. Progress, pending decisions, and history are tracked in plain files you can inspect at any time, plus a web dashboard. Forgeo only interrupts you when a decision is genuinely yours to make, everything else happens autonomously. Transient failures (a network blip, a flaky test) are retried automatically when the retry policy is enabled, and only a task that keeps failing or genuinely needs a human decision ever reaches you.

All you need is basic comfort with a terminal, a git repository, and any coding agent CLI.

Quickstart

The full walkthrough is in Getting started.

# 1. Install (any one of these)

# Homebrew (macOS / Linux)
brew install lucaGazzola/forgeo/forgeo

# or: the one-liner (prebuilt binary, no Python required)
curl -fsSL https://forgeo.org/install.sh | bash

# or: pipx
pipx install forgeo-cli

# 2. Create your Forgeo (guided wizard, run from your project root)
forgeo init

# 3. Start Forgeo (detached in the background; exits immediately)
forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
forgeo stop    # stop the daemon again

forgeo init writes forgeo.yaml and a .forgeo/ folder for the backlog and logs. Fill the backlog with plain JSON tasks (see Backlog format) or add them from the web console while it runs, Forgeo does the rest. Open the dashboard with forgeo web (default http://0.0.0.0:8790), or keep it always-on with forgeo web -d (stop it with forgeo web stop, check it with forgeo web status):

By default the dashboard is open to anyone who can reach the port. On a shared host, protect it with bearer-token auth: forgeo web --token generates a token (printed once, saved to ~/.config/forgeo/web.toml) and requires Authorization: Bearer <token> on every /api/* route — see Web console & HTTP API.

One-off commands: forgeo once (single cycle), forgeo status (summary), forgeo validate (read-only dry run before starting), forgeo stop, forgeo restart, every command is in the CLI reference.

You can run several factories at once, one per repository, each config is fully independent (own backlog, logs, locks). Register each forgeo.yaml in the instance registry with forgeo instance add NAME --config PATH, manage any of them by name with forgeo start/status/stop --name NAME, list them all with forgeo list, and get one aggregate overview with the central dashboard, forgeo web.

Documentation

Everything is stored in plain files: the backlog, forgeo.log, and BLOCKER.md whenever a decision is pending. The backlog can also live in another application behind an http(s) URL — Forgeo reads the whole task document with GET and writes it back with POST, with optional OAuth2 client-credentials auth (see Backlog format). A file backlog is snapshotted (rotating backlog.json.bak files) before every agent run and on daemon startup, and restored automatically if it is ever found corrupt — a bad write never loses your tasks.

Develop

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the development setup, quality gates (pytest, ruff check, mypy src/forgeo), and the pull-request process.

License

MIT — see LICENSE.