aiagentflow

A local-first CLI that orchestrates multi-agent AI workflows for software development. Give it a task — or feed it your specs, PRDs, and guidelines — and it coordinates specialized agents to architect, code, review, test, and ship automatically.

No cloud dependency. Bring your own API keys. Your code stays on your machine.

---

How It Works

Task → Architect → Coder → Reviewer → Tester → Fixer → Ship

Each stage uses a specialized AI agent with tuned prompts and parameters. The loop repeats until quality thresholds pass — like a small AI engineering team running on your machine.

---

Install

npm install -g @aiagentflow/cli

Or with pnpm:

pnpm add -g @aiagentflow/cli

---

Quick Start

# 1. Initialize in your project
cd /path/to/your/project
aiagentflow init

# 2. Run a task
aiagentflow run "Add a login form with email/password validation"

# 3. Or run autonomously (no approval prompts)
aiagentflow run "Refactor the auth module" --auto

# 4. Feed context docs to agents
aiagentflow run "Add auth" --context docs/api-spec.md docs/security.md

# 5. Generate a task list from specs, then batch-run
aiagentflow plan docs/prd.md -o tasks.txt
aiagentflow run --batch tasks.txt --auto

The init wizard walks you through:

1. Auto-detect your project (language, framework, test framework, package manager)
2. Select your LLM providers (Anthropic, OpenAI, Gemini, Ollama)
3. Enter API keys
4. Assign models per agent role
5. Choose a workflow mode (fast, balanced, strict)
6. Import existing docs (specs, requirements, guidelines) for auto-loading

Configuration is saved locally in .aiagentflow/config.json.

---

Features

• Multi-agent pipeline — 6 specialized agents, each with a distinct role
• Context-aware — feed specs, PRDs, architecture docs, and guidelines to every agent
• Plan from docs — generate batch-ready task lists from your existing documentation
• Local-first — runs entirely on your machine, no code leaves your system
• Provider-agnostic — Anthropic (Claude), OpenAI (GPT), Google Gemini, Ollama (local/free)
• Workflow modes — fast, balanced, or strict presets for iterations, approval, and temperatures
• Smart detection — auto-detects language, framework, test runner, and package manager
• Configurable — tune models, temperature, and iteration limits per agent
• Git-native — auto-creates branches, auto-commits on QA pass
• Human-in-the-loop — approve or override at any stage, or go full auto
• QA policies — configurable quality gates (max critical issues, test requirements)
• Batch mode — process multiple tasks from a file
• Session persistence — crash recovery with automatic session saving
• Token tracking — monitor LLM usage per agent and per run
• Customizable prompts — edit agent prompts in .aiagentflow/prompts/

---

CLI Commands

Command	Description
aiagentflow init	Interactive setup wizard
aiagentflow config	View current configuration
aiagentflow doctor	Health check — verify providers and setup
aiagentflow run	Run a workflow for a task
aiagentflow run --auto	Autonomous mode (no approval prompts)
aiagentflow run --context	Run with reference documents
aiagentflow run --batch tasks.txt	Process multiple tasks from a file
aiagentflow plan	Generate a task list from documentation
aiagentflow plan -o tasks.txt	Write task list to file (batch-ready)

---

Agent Roles

Agent	Role	What it does
🧠 Architect	Plan	Analyzes the task and creates an implementation plan
💻 Coder	Implement	Writes production-ready code based on the plan
🔍 Reviewer	Review	Reviews code for bugs, security, and quality
🧪 Tester	Test	Generates tests and runs them
🐛 Fixer	Fix	Addresses review comments and test failures
✅ Judge	QA	Final quality gate — pass or fail

---

Supported Providers

Provider	Type	Default Model	Setup
Anthropic	Cloud API	claude-sonnet-4-20250514	Requires API key
OpenAI	Cloud API	gpt-4o-mini	Requires API key
Google Gemini	Cloud API	gemini-2.0-flash	Requires API key
Ollama	Local	llama3.2:latest	Requires Ollama running locally

You can mix providers — use cloud APIs for reasoning agents (architect, reviewer, judge) and local models for generation agents (coder, tester, fixer).

Using with Ollama (free, local)

# Install and start Ollama
ollama serve

# Pull a model
ollama pull llama3.2

# Initialize aiagentflow with Ollama
aiagentflow init
# → Select "ollama" as provider
# → Enter model name: llama3.2

---

Configuration

After aiagentflow init, your project has:

.aiagentflow/
├── config.json              # Main configuration
├── prompts/                 # Customizable agent prompts
│   ├── architect.md
│   ├── coder.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── fixer.md
│   └── judge.md
├── policies/                # Quality standards
│   └── coding-standards.md
├── context/                 # Reference docs (auto-loaded into every run)
│   ├── api-spec.md          # Example: your API specification
│   └── requirements.md      # Example: your PRD or requirements
└── sessions/                # Saved workflow sessions

Edit the prompt files to customize how each agent behaves. Edit coding-standards.md to set project-specific rules that all agents follow. Drop .md or .txt files into context/ and they'll be automatically included as reference material for all agents.

---

Context Documents

Agents work best when they understand your project's requirements, API contracts, and standards. There are three ways to provide reference documents:

1. Auto-loaded (recommended) — Drop files into .aiagentflow/context/:

cp docs/api-spec.md .aiagentflow/context/
cp docs/security-guidelines.md .aiagentflow/context/
aiagentflow run "Implement user registration"
# Both docs are automatically included in every agent's context

2. Per-run via --context flag:

aiagentflow run "Add OAuth support" --context docs/oauth-spec.md docs/auth-arch.md

3. During init — The setup wizard asks if you have existing docs and copies them for you.

What to include

Document type	Example	Why it helps
API specs	api-spec.md	Agents generate correct endpoints and contracts
Requirements / PRDs	requirements.md	Architect plans match your actual requirements
Security guidelines	security.md	Reviewer catches violations against your policies
Architecture docs	architecture.md	Coder follows your patterns and conventions
Development guidelines	dev-guidelines.md	All agents follow your team's standards

Plan command

Turn documentation into an actionable task list, then batch-run it:

# Generate tasks from a PRD
aiagentflow plan docs/prd.md -o tasks.txt

# Review the generated tasks
cat tasks.txt

# Run them all
aiagentflow run --batch tasks.txt --auto --context docs/architecture.md

---

Project Structure

src/
├── cli/            # CLI entry point and commands
├── core/           # Config system, workflow engine, QA policies
├── providers/      # LLM provider adapters (Anthropic, OpenAI, Gemini, Ollama)
├── agents/         # Agent implementations and prompt library
├── git/            # Git operations wrapper
├── prompts/        # Default prompt templates
└── utils/          # Shared utilities (logger, fs, validation)

---

Development

# Clone and install
git clone https://github.com/aiagentflow/aiagentflow.git
cd aiagentflow
pnpm install

# Run in dev mode
pnpm dev run "your task here"

# Type check
pnpm typecheck

# Run tests
pnpm test

# Lint & format
pnpm lint
pnpm format

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repo and clone your fork
2. Create a branch for your feature: git checkout -b feature/your-feature
3. Follow the coding standards:
   • Functions: camelCase, Classes: PascalCase, Files: kebab-case
   • All public functions need JSDoc, types, and error handling
   • Use custom AppError subclasses — never raw throw new Error()
4. Check your work: pnpm typecheck && pnpm lint && pnpm test
5. Open a PR against main with a description of what and why

Architecture rules

• Dependency direction flows downward: cli → core → utils → types
• Config types are inferred from Zod schemas, never manually defined
• New providers only require one adapter file + registry entry

---

Roadmap

• Project scaffolding, config system, LLM provider layer
• Workflow engine, agent implementations, Git integration
• QA policies, token tracking, session persistence
• Context documents — feed specs, PRDs, and guidelines to agents
• Plan command — generate task lists from documentation
• Multiple providers — Anthropic, OpenAI, Gemini, Ollama
• Project auto-detection — language, framework, test runner, package manager
• Auto-commit on QA pass
• Workflow mode presets — fast, balanced, strict
• VSCode extension
• Desktop GUI

---

License

MIT

---

aiagentflow.dev