Metadata-Version: 2.4
Name: forgeo-cli
Version: 0.3.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 an autonomous software forgeo for people with ideas, not teams.**
You have a product idea — an app, a website, an internal automation — but no
developers on staff. With Forgeo you don't need any: you write down what needs
to be built as a simple list of tasks, and an AI coding agent works through the
list on its own, writing the code and committing it to your repository. No
branches, no pull requests, no developer to hire.

All you need is basic comfort with a terminal, a git repository, and any coding
agent CLI — Claude Code, aider, opencode, or your own script. Forgeo works with
all of them.

Forgeo decides what to do next on its own: while tasks are left it implements
the oldest one and commits the result, and when the backlog is empty it reviews
the codebase and cleans it up. It only interrupts you when a decision is
genuinely yours to make — everything else happens autonomously.

## Quickstart

Requires a git repository (no Python needed — the one-liner downloads a
prebuilt binary for your OS, or `pipx install forgeo-cli` works too). The full
walkthrough is in [Getting started](docs/getting-started.md).

```bash
# 1. Install
curl -fsSL https://forgeo.org/install.sh | bash

# 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, gitignored for you. Fill the backlog with plain JSON tasks (see
[Backlog format](docs/backlog.md)) — or add them from the web console while
it runs — and Forgeo does the rest. The daemon binds no ports; 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).
