Metadata-Version: 2.5
Name: forgeo-cli
Version: 0.7.2
Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
Project-URL: Homepage, https://forgeo.org
Project-URL: Documentation, https://forgeo.org
Project-URL: Repository, https://github.com/lucaGazzola/forgeo
Project-URL: Issues, https://github.com/lucaGazzola/forgeo/issues
Author: Forgeo Contributors
License: MIT License
        
        Copyright (c) 2026 Software Forgeo Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,automation,backlog,orchestration,scheduler
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Description-Content-Type: text/markdown

<div align="center">
  <img src="docs/img/logo.png" alt="Forgeo logo" width="128">
</div>

<div align="center">
  <img src="docs/img/title.svg" alt="Forgeo" width="128">
</div>


[![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<div align="center">
  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
</div>

**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](docs/getting-started.md).

### 1. Install the CLI

Pick any one installer (no root needed; re-running it upgrades Forgeo).

```bash
# Homebrew (macOS / Linux): prebuilt binary, no Python required
brew install lucaGazzola/forgeo/forgeo

# One-liner (Linux / macOS / Windows): prebuilt binary, falls back to pip
curl -fsSL https://forgeo.org/install.sh | bash

# pip (Python 3.11+)
pipx install forgeo-cli
```

### 2. Create your Forgeo

```bash
forgeo init
```

Guided wizard, run from your project root. Writes `forgeo.yaml` (the
config) and a `.forgeo/` folder for the backlog, logs and blocker files.

The base flow is then three steps: fill the backlog, check the
configuration, start the daemon.

### 3. Fill the backlog

```bash
# Either: edit the backlog file by hand — a plain JSON task list (see
# Backlog format), created on first use:
#   .forgeo/backlog.json

# Or: add tasks from the web console once your forgeo is registered
# (first `forgeo start` registers it automatically):
forgeo web      # dashboard at http://0.0.0.0:8790, or keep it on with `forgeo web -d`
```

![Forgeo web console](docs/img/console.png)

### 4. Check the configuration

```bash
forgeo validate
```

Read-only dry run before the first start: verifies `forgeo.yaml`, the git
repo, branch and remote, that the backlog parses (fetching it once when it
is an HTTP endpoint), the agent command, and the lock state. Never invokes
the agent and writes nothing.

### 5. Start the daemon

```bash
forgeo start
```

Starts the daemon **detached in the background** and exits. Every
`interval_minutes` it runs one cycle: pick the oldest `OPEN` task whose
dependencies are all `COMPLETED`, run your coding agent on it, commit the
result. When the backlog is empty, the same agent runs a refactoring pass
over the codebase instead.

### Day-to-day commands

```bash
forgeo status    # Config, backlog counts, next runnable task, daemon running?, last outcome
forgeo once      # Run exactly one cycle in the foreground, no daemon left behind
forgeo run --task SELF-012  # Run one specific OPEN task now (triage)
forgeo stop      # Stop the background daemon
forgeo restart   # Stop and start again (re-reads forgeo.yaml after edits)
forgeo web       # Dashboard: every instance's backlog, run history and logs
```

`forgeo web` defaults to an open dashboard on `http://0.0.0.0:8790`; on a
shared host protect it with `forgeo web --token` (requires
`Authorization: Bearer <token>` on every `/api/*` route — see
[Web console & HTTP API](docs/web-console-api.md)).

### Multiple repositories (instances)

Run several factories at once, one per repository; each config is fully
independent (own backlog, logs, locks). Register each `forgeo.yaml` 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

| Topic | Where |
| --- | --- |
| Install, init, first cycle | [Getting started](docs/getting-started.md) |
| Every `forgeo.yaml` key | [Configuration](docs/configuration.md) |
| Task schema and statuses | [Backlog format](docs/backlog.md) |
| How the agent is invoked (env, exit codes, timeouts) | [Agent contract](docs/agent-contract.md) |
| All CLI commands | [CLI reference](docs/cli-reference.md) |
| Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |

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](docs/backlog.md)). 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

```bash
pip install -e ".[dev]"
pytest
```

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

## License

MIT — see [LICENSE](LICENSE).
