Metadata-Version: 2.4
Name: forgeo-cli
Version: 0.4.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.

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
curl -fsSL https://forgeo.org/install.sh | bash

or

pipx install forgeo-cli

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

# 3. Start Forgeo
forgeo start   # run forever: every interval_minutes, implement the oldest OPEN task
```

`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>):

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

One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
`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.

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