Getting Started
How to install and run your first AI Agent Flow task.
AI Agent Flow (v1.4.0) is a local-first, multi-agent orchestration framework designed for software engineering. This guide will help you install the CLI and run your first autonomous task.
Prerequisites
- Node.js: Version 18 or higher.
- LLM API Key: You'll need an API key from a supported provider — or use a free-tier option to get started with no credit card:
- Free options: Groq or OpenRouter both have generous free tiers
- Cloud options: Anthropic, OpenAI, or Google Gemini
- Local / no key: Ollama runs models entirely on your machine
Installation
Install the package globally via npm:
npm install -g @aiagentflow/cli
Verify the installation:
aiagentflow --version
Running Your First Task
Navigate to your project directory and run:
aiagentflow run "Add a unit test for the authentication middleware"
The CLI will:
- Analyze: The Architect agent analyzes your codebase and drafts an implementation plan.
- Code: The Coder agent writes the changes across one or more files.
- Review: The Reviewer agent checks for bugs, style issues, and anti-patterns.
- Security: The Security agent scans for vulnerabilities (OWASP top-10, secret exposure, injection flaws).
- Test: The Tester agent writes and runs tests. The Fixer agent resolves any failures.
- Approve: The Judge agent makes the final call.
Other Useful Commands
Run in an isolated git worktree — agents work on a fresh branch, leaving your working directory untouched:
aiagentflow run --isolate "Refactor the payment module"
After the workflow finishes you'll be prompted to merge, keep, or discard the branch. Use these commands to manage active worktree runs:
aiagentflow runs # list active runs
aiagentflow discard --merge <branch> # merge and clean up
aiagentflow gc # prune runs older than 7 days
Review the Architect's plan before coding starts:
aiagentflow run --review-plan "Add OAuth2 support"
The workflow pauses after planning so you can approve, edit in $EDITOR, ask for a regeneration, or abort.
Run batch tasks in parallel:
aiagentflow run --batch tasks.txt --parallel 4 --auto
aiagentflow run --batch tasks.txt --parallel 2 --max-tokens 500000 --max-cost 2.00
Address GitHub PR review comments automatically:
aiagentflow run --pr 42 --isolate
Fetches the PR's review comments and change requests, then runs the full agent pipeline to resolve them. Requires the GitHub CLI (gh auth login).
Implement a GitHub issue end-to-end:
aiagentflow run --issue 7 --isolate --auto
Fetches the issue body and labels as the task. After the Judge approves, a pull request is opened automatically.
Inspect and test MCP server configuration:
aiagentflow mcp list # show configured servers and their tools
aiagentflow mcp test filesystem # start a server and verify it exposes its tools
Manage plugins (custom agents and providers):
aiagentflow plugin list # show installed plugins
aiagentflow plugin install @my-org/aiagentflow-linter # install from npm
aiagentflow plugin install ./local-plugin # symlink a local plugin
aiagentflow plugin remove my-plugin # uninstall
Launch the terminal UI dashboard:
aiagentflow ui
Shows a live auto-refreshing list of active worktree runs with status icons, token counts, and costs. Press q to quit.
Talk to a single agent without running the full pipeline:
aiagentflow chat reviewer --file src/auth.ts "review this for security issues"
Generate a structured report from any past workflow session:
aiagentflow export --format md --output report.md
Generate a task list from a spec or PRD file:
aiagentflow plan docs/spec.md --numbered -o tasks.txt
aiagentflow run --batch tasks.txt --auto
Manage agent memory — knowledge that persists across runs:
aiagentflow memory list # show all stored memories by type
aiagentflow memory show <name> # print one memory's full body
aiagentflow memory rm <name> # delete a memory
aiagentflow memory edit <name> # open in $EDITOR
aiagentflow memory clear --type gotcha # bulk-delete by type
Agents automatically write to the memory store during workflow runs (conventions, decisions, gotchas, architecture notes) and read from it on every subsequent run — so each run starts smarter than the last.
Next Steps
Check out our Configuration Guide to learn how to set up your preferred AI providers and MCP servers.