miniforge-ai/miniforge
miniforge-ai/miniforge has 58 GitHub stars and 3 forks. GitHot measured +3 stars in 24 hours. Last checked 2026-11-17 02:11 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- +3
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
miniforge is an autonomous software development system designed to behave like a factory, not a chatbot
AIREADME.md
Original
Miniforge
Write a spec. Get a pull request.
Miniforge is an autonomous software factory. You describe what you want in plain English or structured EDN. Miniforge plans the work, writes the code, runs tests, reviews itself, and opens a PR. No prompt engineering. No copy-paste. Full SDLC.
Before and After
BEFORE AFTER
────── ─────
1. Write a ticket 1. Write a spec
2. Create a branch 2. mf run spec.edn
3. Read the codebase 3. Review the PR
4. Write code 4. Merge
5. Run tests
6. Fix failures
7. Lint
8. Fix lint
9. Commit
10. Push
11. Open PR
12. Write PR description
13. Wait for CI
14. Wait for review
15. Address feedback
16. Re-push
17. Wait for re-review
18. Merge
How It Works
Miniforge runs four nested control loops. A team of agents does the work; a tight inner loop enforces quality at every step. A monitor resolves reviewer feedback after delivery, and meta-agents govern the whole operation.
Team loop — specialized agents collaborate through phases, like a dev team handing off work:
Spec ──► Explore ──► Plan ──► Implement ──► Verify ──► Review ──► Release ──► Observe
│ │ │ │ │ │ │
│ │ │ │ │ │ └─ monitors PR:
│ │ │ │ │ │ polls comments,
│ │ │ │ │ │ fixes feedback,
│ │ │ │ │ │ merges when ready
│ │ │ │ │ │
│ │ │ │ │ └─ creates branch,
│ │ │ │ │ commits, opens PR
│ │ │ │ │
│ │ │ │ └─ self-reviews diff
│ │ │ │ against spec + constraints
│ │ │ │
│ │ │ └─ gates: syntax, lint,
│ │ │ no-secrets, tests-pass
│ │ │
│ │ └─ generates code via LLM agent
│ │
│ └─ decomposes spec into a task DAG
│ with dependencies and parallel execution
│
└─ scans codebase, loads relevant files,
queries knowledge base
Inner loop — inside each phase, the agent generates an artifact, validates it against policy gates, and repairs failures automatically:
generate ──► validate ──► [pass] ──► next phase
│
└─ [fail] ──► repair ──► re-validate
│
└─ [budget exhausted] ──► escalate
Observe loop — after Release creates a PR, the monitor loop runs autonomously for up to 72 hours:
poll PR ──► classify comments ──► route
│ │
├─ change request ──► fix, push, reply
├─ question ──────► answer, reply
├─ approval ──────► attempt merge
└─ noise ─────────► skip
Meta loop — governance meta-agents supervise the entire operation at a semantic level. Any meta-agent can halt the factory floor:
┌─────────────────────────────────────────────────┐
│ Meta-Agent Coordinator │
│ │
│ Progress Monitor ─── stagnation? ──► halt │
│ Test Quality ─────── coverage? ───► halt │
│ Conflict Detector ── diverged? ───► halt │
│ Resource Manager ─── over budget? ► halt │
│ Evidence Collector ── (observe only, no halt) │
│ │
│ Any agent can halt. Decisions are observable. │
└─────────────────────────────────────────────────┘
Policy gates govern every transition. Budget limits (tokens, cost, time) enforce hard stops. All decisions produce evidence bundles for traceability.
Quickstart
Prerequisites
- macOS, Linux, or Windows — see Platform Support for the install path on each. Native Windows is in beta; WSL2 and Git Bash are first-class today.
- Babashka (Mac/Linux:
Homebrew or
bash <(curl …) --static; Windows:scoop install babashka) - An LLM backend: OpenCode CLI, Claude Code CLI, or Codex CLI. Provider API keys for miniforge agent runs are configured through OpenCode.
- An OCI-compatible local container runtime (see below). Podman
is the recommended default; Docker is supported.
Other Docker-CLI hosts (Colima, OrbStack) work as
:runtime-kind :docker. - The GitHub CLI (
gh), signed in withgh auth login. The release phase opens pull requests with it.
Install and Run
The first workflow opens a pull request: miniforge pushes a branch to
origin and runs gh pr create. Fork miniforge-ai/miniforge and clone
your fork, so the push goes to a repository you can write to.
git clone https://github.com/<you>/miniforge.git
cd miniforge
gh repo set-default <you>/miniforge # gh opens the PR on your fork
bb bootstrap # also installs mf to ~/.local/bin
# Configure provider auth for agent runs:
# opencode auth login
# Run your first workflow
mf run examples/workflows/simple-refactor.edn
bb bootstrap installs Java, Clojure CLI, clj-kondo, Polylith, and markdownlint.
It prefetches the coverage tool used by bb ccov, builds the CLI, and installs it as ~/.local/bin/mf.
It reports if that directory is missing from your PATH.
Run bb install:local after pulling to update mf.
On macOS, bootstrap also brew-installs Podman and initializes a default podman machine.
It installs the repo's git hooks only when your git email is @miniforge.ai.
The pre-commit hook rejects other commit emails, including commits made by miniforge's release phase.
Linux users install Podman through their distro package manager, such as apt install podman or dnf install podman.
Docker users can stay on Docker by setting MINIFORGE_RUNTIME=docker or :runtime-kind :docker in config.
To check the resolved runtime: mf doctor (which now reports the
selected runtime + version + override hint) or mf runtime info
(prints the descriptor as data).
See the Quickstart Guide for a detailed walkthrough.
Write a Spec
A spec is a description of what you want. Two fields are required:
{:spec/title "Add input validation to the signup form"
:spec/description
"The signup form accepts any input without validation. Add server-side
validation for email format, password strength (min 8 chars, 1 number),
and username uniqueness. Return structured error messages."
:spec/intent {:type :feature
:scope ["src/auth/signup.clj"]}
:spec/constraints
["No breaking changes to existing API"
"All existing tests must pass"]
:spec/acceptance-criteria
["Email validation rejects malformed addresses"
"Password validation enforces minimum requirements"
"Username uniqueness check queries the database"
"Error messages are structured maps, not strings"]}
Specs can also be written as Markdown with YAML frontmatter. See Writing Specs.
Run the Demo
# Watch miniforge improve itself (dogfooding demo)
bash examples/demo/run-demo.sh
The demo is a Bash script. On native Windows, run it from Git Bash or WSL2 —
or invoke the underlying workflow directly with mf run examples/demo/add-utility-function.edn. See Platform
Support for details.
See Demo Guide for a guided walkthrough.
Workflow Types
| Workflow | Phases | Use For |
|---|---|---|
| Canonical SDLC | explore, plan, implement, verify, review, release, observe | Features, refactors, bug fixes |
| Quick Fix | implement, verify, done | Small, well-understood changes |
A spec runs Canonical SDLC unless it names another workflow:
:spec/workflow-type :quick-fix in an EDN spec, or type: quick-fix in
Markdown frontmatter. Canonical SDLC includes the full observe
loop — the PR monitor will autonomously address reviewer feedback after release.
Configuration
# LLM backend: OpenCode is the default provider/auth wrapper.
opencode auth login
# Pick the backend and the default models
mf config backend opencode
export MINIFORGE_AGENT_THINKING_MODEL=anthropic/claude-opus-4-6 # planner, architect
export MINIFORGE_AGENT_EXECUTION_MODEL=anthropic/claude-sonnet-4-6 # other roles
There is no environment variable for token budgets or retry limits; phase retries are set per phase in the workflow definition.
See Configuration Guide for all options.
Architecture
Miniforge is built on a governed workflow engine with pluggable phases, agents, and policy packs:
┌─────────────────────────────────────────────────────┐
│ CLI / TUI / Web Dashboard │
├─────────────────────────────────────────────────────┤
│ Meta Loop: Governance (can halt at any point) │
│ Progress · Test Quality · Conflicts · Resources │
├─────────────────────────────────────────────────────┤
│ Team Loop: Workflow Engine (phase state machine) │
│ ┌──────┐ ┌──────┐ ┌───────┐ ┌──────┐ ┌─────────┐ │
│ │Explore│ │ Plan │ │Implmnt│ │Verify│ │ Release │ │
│ └──────┘ └──────┘ └───────┘ └──────┘ └─────────┘ │
│ ↕ ↕ ↕ ↕ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Inner Loop: generate → validate → repair │ │
│ └────────────────────────────────────────────────┘ │
│ ↕ ↕ ↕ │
│ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Agents │ │ Gates │ │ Policies │ │Evidence │ │
│ └────────┘ └────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────────────┤
│ Observe Loop: PR Monitor (poll → classify → fix) │
├─────────────────────────────────────────────────────┤
│ DAG Executor: parallel tasks, isolated worktrees │
├─────────────────────────────────────────────────────┤
│ LLM Backends (Claude, GPT, Gemini, Local) │
│ Intelligent model selection · budget enforcement │
└─────────────────────────────────────────────────────┘
- Meta-agents: Progress monitor, test quality enforcer, conflict detector, resource manager — governance agents that supervise execution and can halt the factory floor. Distributed authority, not centralized control.
- Agents: Planner, Implementer, Tester, Reviewer, Releaser — each specialized for its phase.
- Gates: Syntax, lint, no-secrets, tests-pass, coverage — policy enforcement at every transition. Failures trigger repair, not silent progression.
- Policy packs: Pluggable rule bundles that define what "good code" means for your project. The sole extension point for customization.
- Evidence bundles: Every phase produces a provenance chain — what was decided, by which agent, with what inputs, and the result.
- DAG Executor: Plans decompose into task graphs; tasks run in parallel across isolated worktrees with per-task budget limits.
- PR Monitor: After release, autonomously resolves reviewer feedback — classifies comments, pushes fixes, answers questions, attempts merge.
- Budget enforcement: Token, cost, and time limits are hard stops at every level (per-task, per-phase, per-workflow).
See Architecture Overview for details. See Normative Specs for the full specification.
Project Status
Open source and in active use. Miniforge is actively developed and dogfooded daily. The full pipeline (spec → PR → monitor → merge) works end-to-end for Clojure projects, with hundreds of PRs merged using Miniforge on itself.
See SPEC_INDEX.md for normative specification status and ROADMAP.md for delivery priorities.
Documentation
- Quickstart — Run your first workflow
- Writing Specs — How to describe work
- Phases — What the pipeline does
- Configuration — Tuning and backends
- Architecture — How it works
- Roadmap — Spec progress and priorities
- Documentation Index — Full navigation guide
- Contributing — Development setup and guidelines
Contributing
See CONTRIBUTING.md for development setup, Polylith structure, git conventions, and the pre-commit hook.