Forgeo is a software factory for coding agents. Its core idea is: you provide a backlog and an agent CLI, and Forgeo is responsible for picking the next runnable task, running the agent, and committing the result. Progress is recorded as plain files, and a web dashboard is provided, interrupting you only when a human decision is needed.
Purpose and Positioning Forgeo is used to connect coding agents to a schedulable, trackable automated workflow. It is suitable for scenarios where you want agents to continuously process development tasks according to a checklist and automatically commit to the main branch. It explicitly adopts a "no branches, no PRs" model, with the result of each task committed directly to main.
Main Capabilities
- Task scheduling: process one task at a time, selecting the oldest OPEN task whose dependencies are COMPLETED, or executing according to the run_at schedule. REVIEW status blocks its dependent tasks, but does not block independent tasks.
- Agent-agnostic: any CLI that reads the FORGEO_TASK environment variable can be used (for example aider, Claude, custom scripts).
- Idle refactoring: when the backlog is empty, run a refactoring process once.
- Failure handling: mark as BLOCKED when human input is needed (via BLOCKER.md); mark as FAILED according to the retry policy on failure; provide snapshots for file-based backlogs; support Telegram/webhook notifications.
- Optional review: when review_mode: branch, commit to the forgeo/review/TASK-001 branch, mark as REVIEW, push and wait for manual merge before becoming Complete.
Usage Prerequisites: a terminal, a git repository, and an agent CLI. Installation: provides a rootless installation method that can be run repeatedly to upgrade. Initialization: run the wizard in the project root directory to create forgeo.yaml and .forgeo/ (containing backlog, logs, blockers). The wizard will prompt you to choose a backlog provider (file / github / gitlab / jira / http) and an agent command. For issue providers, you can choose PAT or OAuth login (forgeo auth login → ~/.config/forgeo/tokens/); GitHub repository detection is done automatically when possible, while Jira requires providing its URL and JQL. After filling in the backlog, each cycle executes: select a task → run the agent → commit/push (or push to the REVIEW branch when review_mode: branch). When the backlog is empty, the refactoring process is executed. Web console: forgeo web is exposed by default at 0.0.0.0:8790. On a shared host, forgeo web --token can be used to enable bearer authentication. Run the agent in isolation: the repository is bind-mounted at the same path, and the task is passed in via FORGEO_TASK. Multiple instances: one configuration per repository, fully independent (each with its own backlog, logs, and locks). An instance registry can be used.
Backlog providers and dashboard Providers include: file, HTTP, Jira, GitHub, GitLab. file/HTTP exchange the full document; Jira/GitHub/GitLab synchronize issues one by one. File-based backlogs generate a snapshot before each run (backlog.json.bak), and restore it if corrupted. Dashboard: forgeo web aggregates all instances. For file/http, it is the primary editor; for jira/github/gitlab, it is a mostly read-only mirror (linking to the native issues, showing BLOCKED/FAILED reasons and retry status).
Use cases Suitable for development workflows that want coding agents to automatically execute tasks according to a JSON backlog and commit directly to the main branch; suitable for automated development scenarios that require scheduled execution, failure retries, manual blocking prompts, and Web progress viewing.
Limitations and notes Requires a terminal, a git repository, and an agent CLI. It uses a branchless, PR-less mode, with results committed directly to main (unless review_mode: branch is enabled). The quality gates mentioned in the contribution guidelines include pytest, ruff check, mypy src/forgeo. The license is MIT.
