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.

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.

npm install -g @aiagentflow/cli

Or with pnpm:

pnpm add -g @aiagentflow/cli

# 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, Groq, 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.

• 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), Groq, 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/

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

# 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

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.

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.

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

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

# 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

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

• 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

• 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, Groq, 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

MIT

aiagentflow.dev