Forgeo Software Factory
Schedules backlog work, runs a coding agent, and commits the result.
- Source repo
- lucaGazzola/forgeo
- Stars
- ★ 35
- Last updated
- 7d ago
- License
- MIT
- Primary language
- Python
- FA score
- 64/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo maintainer with a small Git project can feed JSON tasks to Codex, Claude Code, or another CLI and have completed changes committed automatically.
- Not a fit if
- Teams that require human review before every merge
- Users who cannot supply and configure their own agent CLI
- Teams wanting a hosted cloud service instead of a self-run daemon
- Source review
- 64/100 · Some gaps
What does this agent do, and when should you use it?
Forgeo is a scheduled software factory that selects backlog tasks, invokes a coding-agent CLI, and commits the resulting repository changes. It supports a plain JSON backlog as well as GitHub, GitLab, Jira, and HTTP providers, with progress exposed through files and a web dashboard. Its execution interface is provider-neutral: any CLI that reads FORGEO_TASK can participate, and the supplied material explicitly names Claude Code, Codex, aider, and custom scripts. By default, it runs one dependency-ready or scheduled task at a time and performs a refactoring pass when no backlog work remains. Tasks can move through COMPLETED, REVIEW, BLOCKED, and FAILED paths, backed by retries, file-backlog snapshots, BLOCKER.md, and Telegram or webhook notifications. It is a self-hosted repository automation tool that requires a terminal, a Git repository, and an independently supplied agent CLI.
Forgeo reads forgeo.yaml and the configured backlog provider, then selects the oldest runnable OPEN task whose dependencies are COMPLETED or whose run_at schedule is due. It passes that task to the configured agent CLI through FORGEO_TASK, lets the agent modify the current repository, and commits and, where configured, pushes the result. The normal path targets the main line; with review_mode: branch, it commits to a branch such as forgeo/review/TASK-001, marks the task REVIEW, pushes it, and waits for a human merge before completion. An empty backlog triggers a refactoring pass. Failed work can follow a retry policy, while work requiring a decision becomes BLOCKED and uses BLOCKER.md; file backlogs are snapshotted to backlog.json.bak before a run and restored if corrupted. forgeo web supplies a multi-instance dashboard and HTTP API, while forgeo status, once, run, start, stop, and restart control execution.
- A solo maintainer with a small Git project can feed JSON tasks to Codex, Claude Code, or another CLI and have completed changes committed automatically.
- A team with overnight or time-based maintenance work can combine
run_atscheduling with the background daemon. - A team that requires approval before integration can enable
review_mode: branchand hold completed agent work in REVIEW until a human merges it. - A developer maintaining several repositories can give each one independent backlog, log, and lock state, then manage them through the instance registry and aggregate dashboard.
- A security-conscious operator can place the agent in a Docker sandbox with no network by default and selected credential directories mounted read-only.
- A team already tracking work in GitHub, GitLab, or Jira can use those issues as the backlog and monitor blocked, failed, and retry states from the dashboard.
How do you install or deploy this agent?
Provide a terminal, a Git repository, and an installed agent CLI. Choose one documented installation route: brew install lucaGazzola/forgeo/forgeo; curl -fsSL https://forgeo.org/install.sh | bash; or, with Python 3.11 or newer, pipx install forgeo-cli. From the project root, run forgeo init; the wizard creates forgeo.yaml and .forgeo/, then asks for a file, github, gitlab, jira, or http backlog provider and the agent command. Issue providers require either a PAT or OAuth authentication through forgeo auth login, with tokens stored under ~/.config/forgeo/tokens/. GitHub repository detection is automatic when possible; Jira additionally asks for its URL and JQL.
How do you use this agent?
For the file provider, populate .forgeo/backlog.json; for another provider, configure it in forgeo.yaml. Run forgeo validate first to check configuration, repository state, backlog, agent, and locks. Use forgeo once for a foreground trial cycle or forgeo start to launch the background daemon. forgeo status reports counts, the next task, daemon state, and the last outcome; forgeo run --task TASK-012 immediately runs a specified OPEN task. Start the dashboard with forgeo web at http://0.0.0.0:8790; on a shared host, use forgeo web --token for bearer authentication. Control the daemon with forgeo stop and forgeo restart.
What are this agent's strengths and limitations?
- The agent contract is limited to reading FORGEO_TASK, allowing Claude Code, Codex, aider, or a custom CLI instead of locking execution to one model provider.
- Its auditable workflow covers one-at-a-time selection, dependency checks, schedules, task states, and Git commits.
- It offers both direct integration and an optional REVIEW-branch path, so teams can choose between unattended throughput and human approval.
- BLOCKED and FAILED states, retries, BLOCKER.md, and file-backlog recovery address several common unattended-run failure modes.
- Multiple backlog providers, independently configured repositories, an aggregate dashboard, and optional Docker isolation broaden deployment choices.
- Adoption means granting an agent CLI permission to change a Git worktree and create commits; the default main-line workflow raises the cost of weak agent output or overly broad repository permissions.
- Users must obtain, install, and configure their own coding-agent CLI; Forgeo does not supply a model service or document the agent's usage cost.
- GitHub, GitLab, Jira, and remote HTTP backlogs add network, credential, and external-service configuration requirements.
- In branch review mode, dependants remain blocked until a human merges the reviewed task, which can pause autonomous throughput.
- Docker isolation requires an image containing both the agent CLI and
sh; agents that need internet access also require changing the default no-network sandbox setting.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Forgeo Software Factory This agent | 64 · Some gaps | CLIFree + model costs | ★ 35 | 7d ago | Python | Codex · Claude Code |
| AGRO Sandbox Runtime | 76 · Good | CLIFree + model costs | ★ 43 | today | TypeScript | Codex · Claude Code |
| Agent of Empires | 79 · Good | CLIFree | ★ 3.9k | today | Rust | Codex · Claude Code |
| Ralph for Claude Code | 79 · Good | CLIFree + model costs | ★ 9.7k | 1d ago | Shell | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The docs and code excerpt show tasks passed through FORGEO_TASK to a configured shell command, which inherits the host environment; the optional Docker sandbox defaults to no network and supports read-only mounts. Permissions still depend on the configured command and host environment, and host execution is the default, so least privilege is only partial (1). Init can overwrite existing configuration, and agent timeouts may be unset; the evidence does not show per-run human approval, so confirmation is thin (1). The task environment variable, repository path, branch, logs, and notification paths are documented, making data flow reasonably clear (2). OAuth/PAT options, token-file permissions, and environment-variable setup are documented, but the agent inherits the full environment and its child processes can read available tokens; sensitive-data handling is partial (1). Runtime dependencies and Python versions are declared, but the supplied materials show no dependency lock or audit evidence (1). Runs can commit and push, send webhooks or Telegram notifications, and default to committing on the main branch; effects are visible and configurable, but confirmation safeguards are limited (1). File backlogs are backed up before runs and can be restored after corruption, with an optional review branch; recovery after commits is not fully described (2). Repository, package metadata, and contributor attribution are visible, but publisher identity and maintenance responsibility are not clearly verified (1).
The README, configuration docs, agent contract, and implementation excerpt generally agree on task selection, exit codes, timeouts, and commits; some provided documentation is truncated, so not every path can be confirmed (2). Homebrew, an install script, and pipx are supported, with Python 3.11+ specified; dependencies have minimum versions, but there is no lock file or evidence guaranteeing availability (2). Missing commands, timeouts, nonzero exit codes, and failed HTTP requests have documented readable error paths, though the evidence is not comprehensive (2).
The product clearly targets developers and covers single-repository task orchestration, remote issue backlogs, multiple repositories, and optional sandboxing (3). The shell-agent contract, exit codes, timeouts, and Docker setup are documented, but host execution, inherited permissions, and agent boundaries largely depend on configuration (2). Tasks are selected by OPEN status, dependencies, and run_at; scheduling is specific, while an empty backlog triggers a refactor pass (2). macOS/Linux and Windows binary release intentions and a Python installation path are shown, and the terminal, Git repository, and agent CLI prerequisites are stated; platform coverage is useful but still entails environmental differences (2).
The README organizes installation, setup, usage, documentation, and development, with links to detailed topic guides (3). Installation and upgrade steps are clear and explain prebuilt binaries and pip fallback; source verification details are limited (2). The product and CLI names are stable, while the Python package is named forgeo-cli, adding a small naming difference (2). Quickstart, configuration, CLI, and workflow examples are provided; no FAQ appears in the supplied material (2). Practical constraints and cautions include host execution by default, optional no-timeout operation, and an open-by-default web console, but there is no complete consolidated limitations list in the supplied evidence (2). An MIT LICENSE is present and consistent with package metadata (3). pyproject declares a version and the CI release process extracts notes from CHANGELOG, but the supplied packet contains no CHANGELOG content to review (1). Contribution guidance and quality gates are mentioned and the release workflow is visible; no named long-term maintainer or maintenance commitment is shown (1).
Task statuses, run records, BLOCKER output, the dashboard, and an editable backlog make results actionable and reviewable (3). Automatic task selection, agent execution, blocker handling, and commits across multiple backlog providers provide clear orchestration value (3). Automation may reduce manual scheduling, but persistent agent runs, host permissions, pushes, and refactor passes have resource and review costs for which the supplied materials show limited controls (2).
The main README claims have corresponding evidence in the supplied agent implementation, CLI/configuration docs, and test samples, though not every product claim is supported by the source excerpts provided (2). Docs, package metadata, CI, and tests corroborate Python support, exit-code behavior, and release steps, but the test excerpts cover only some behavior (2). The materials distinguish declared configuration from implementation evidence; this is a static review and does not claim execution or independent verification, and uncovered paths remain unknown (2).
- The agent runs on the host by default and child processes inherit environment variables; provide credentials only to trusted agent commands, and consider Docker sandboxing with limited mounts.
- The web console listens on 0.0.0.0 by default and runs commit to the configured branch by default; enable bearer-token authentication on shared hosts and assess review-branch mode and push targets.
- The supplied packet does not include all documentation or dependency lock information; do not treat unseen files or unexecuted tests as verified.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/forgeo)<a href="https://followagents.com/en/agents/forgeo"><img src="https://followagents.com/badge/forgeo.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Fixed - GitHub/GitLab backlogs preserve per-task customization when a task is created. - OAuth issue-backlog login supports browser URLs, callback ports, and config-relative tokens. Removed - Unused github.fields/gitlab.fields field mapping (GitHub/GitLab issues have no custom fields).View on GitHub ↗ -
Release notes excerpt
Added - Browser-based OAuth login for GitHub, GitLab, and Jira, with cached tokens and setup guidance. Fixed - Stabilized the CI lint configuration.View on GitHub ↗ -
Release notes excerpt
Added - REVIEW status with feature-branch workflow (review_mode: branch). When enabled, a successful agent run no longer commits directly to main as COMPLETED: the engine creates a feature branch forgeo/review/<TASK_ID> (via review_branch_prefix, default forgeo/review/), commits there, pushes, and marks the task REVIEW. Tasks in REVIEW block dependants (like BLOCKED/FAILED) while independent tasks keep running. …View on GitHub ↗
FAQ
Does Forgeo include a coding model or agent?
Will it write directly to the main branch?
review_mode: branch, which uses a branch such as forgeo/review/TASK-001 and leaves the task in REVIEW until a human merge.What happens when an agent fails or needs a decision?
BLOCKER.md; Telegram and webhook notifications are also supported.Is network access mandatory?
none. Pushes, OAuth login, notifications, and GitHub, GitLab, Jira, or HTTP backlog providers require the relevant network connectivity.Is the web dashboard safe to expose on a shared host by default?
forgeo web listens on 0.0.0.0:8790 by default. The documented shared-host setup is forgeo web --token, which enables bearer authentication.Thanks — we use this to improve the page.