Metadata-Version: 2.5
Name: forgeo-cli
Version: 0.6.0
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)

**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).

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

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

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](docs/web-console-api.md).

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

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

| 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).
