aider-factory is a modular, lightweight, YAML-driven automation harness, grounding validator, and RAG/debate engine built on top of Aider.
Designed with a "bolt-on, bolt-off" UNIX philosophy, aider-factory can be run as a complete file-coupled DAG pipeline, or its components can be used as standalone command-line clients in your standard terminal, shell scripts, or CI/CD pipelines.
If you want a simple, lightweight, and repeatable way to automate Aider without the bloat of heavy agent frameworks, aider-factory does this out of the box.
- Fully customizable options through a simple
.env.ymlfile to cater to your specific pipeline or workflow needs. - Easily define phase-based tasks, manage target/editable files, and run test-driven self-healing loops.
You do not have to buy into a monolithic ecosystem. Each component of aider-factory is exposed as a global, standalone command-line client that you can lift and use anywhere:
aider-oracle: A blazing-fast local RAG client.aider-validate: A deterministic fact-checker and quote-sticher for CI/CD.aider-research: A private metasearch CLI.aider-factory: The pipeline orchestrator.
A multi-tiered, deterministic-first validation system that can be used in both code or review paths, and in autonomous or pair programming modes.
- The tags are the state: The LLM cannot award itself a passing grade. Only the deterministic validator promotes tags from
[evidence]to[validated]or[fixed]. - Exact Substring Proof: A quote is either an exact verbatim substring of the source, or it is a tripwire. No fuzzy thresholds.
- Free Ellipsis Auto-Stitching: Automatically splits quotes on
..., matches the fragments in the source, and auto-replaces them with the continuous source span if the gap is small—saving massive token costs with 0 LLM calls. - Unique commands and flags make it a treat to use across different workflows.
Run structured, adversarial debates between the Architect and a specialized, reactive Knowledge Oracle.
- Can be run anywhere, in both autonomous or pair programming modes.
- Persistent Oracle Sessions: Unlike standard RAG which flushes context on every turn, the Oracle session accumulates and persists context across debate turns and rounds, ensuring deep, multi-turn reasoning.
- Deterministic Referee: A simple script reads the
PROPOSAL:andVERDICT:lines to resolve the debate (agreement or deadlock), preventing credit-burning loops.
┌───────────────────────────────────────────────────────────────────────────┐
│ aider-factory (DAG) │
└──────────────┬──────────────────────┬──────────────────────┬──────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ aider-oracle │ │ aider-validate │ │ aider-research │
│ (Local RAG) │ │ (Grounding) │ │ (Private Web) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Automates multi-phase development workflows. It manages file context, coordinates the split Architect/Editor model pattern, captures test suite failures, and drives iterative self-healing loops.
A standalone, terminal-first RAG client. It parses codebases structurally using tree-sitter AST chunking, indexes literature into LanceDB, and answers queries using local or cloud models. It includes a built-in two-party referee debate engine for high-stakes architectural decisions.
A deterministic validator designed for CI/CD. It audits generated text against source documents. It features an exact-substring check and a free, deterministic ellipsis auto-stitcher that repairs split quotes without calling an LLM. It integrates with MiniCheck for sentence-level entailment verification.
A vendor-free metasearch CLI. It auto-provisions a local, rootless SearXNG container via Podman/Docker, aggregates search engines, applies academic filters, and generates clean Markdown research reports.
Ensure you have Python 3.12 and uv installed.
uv tool install --force git+ssh://git@gitlab.com/bryanrod182/aider-factory.gitgit clone git+ssh://git@gitlab.com/bryanrod182/aider-factory.git
cd aider-factory
uv tool install --force --editable .To support private, vendor-free web research, install Podman (or Docker):
sudo apt install -y podmanNavigate to any codebase and initialize the zero-clutter workspace:
cd /path/to/your-project
aider-factoryThis bootstraps .aiderignore and a default configuration template at .aider_factory/.env.yml.
Export your API keys (globally in your shell profile or locally in a .env file):
export GEMINI_API_KEY=\"AIzaSy...\"
export OPENAI_API_KEY=\"sk-proj...\"Open .aider_factory/.env.yml, configure your target files, and run:
aider-factoryaider-research search \"negative income tax labor supply\" --academic --top 5# Ingest a web page or PDF into your active collection
aider-oracle --add-web https://example.com/api-docs.html --collection my_project
# Query the Oracle
aider-oracle \"What is the rate limit for the API?\"aider-oracle --debate code \"Should we migrate from SQLite to PostgreSQL?\"aider-validate --file review.md --source source_ocr.md --report report.md --autofixgraph TD
A[Start Phase] --> B{toggles.run_ocr_rag}
B -- True --> C[Ingest Docs/Code to LanceDB]
B -- False --> D[Skip Ingestion]
C --> E[Initialize Aider Session]
D --> E
E --> F[Architect Model: Plan & Diagnose]
F --> G[Editor Model: Apply Minimal-Delta Edits]
G --> H{toggles.iterate_test}
H -- True --> I[Run Test Runner / Validator]
I --> J{Tests Pass?}
J -- Yes --> K[Promote/Finalize State]
J -- No --> L{Retries Exhausted?}
L -- No --> F
L -- Yes --> M{debate_loops > 0?}
M -- Yes --> N[Two-Party Debate Escalation]
M -- No --> O[Soft Fail / Hold for Human]
N --> P[Apply Agreed Verdict]
P --> K
H -- False --> K
This project is licensed under the MIT License - see the LICENSE file for details.
aider-factory is an independent, community-driven open-source project. It is not affiliated with, sponsored by, endorsed by, or associated with Paul Gauthier, the official Aider project, or Oracle Corporation.