Officially launched

AI Agent Flow is now officially launched on Product Hunt.

aiagentflow CLI - A local-first AI engineering team in your terminal. | Product Hunt
Documentation

Provider Configuration

How to configure Anthropic, OpenAI, Gemini, Groq, OpenRouter, and Ollama with AI Agent Flow.

AI Agent Flow supports six LLM providers — cloud and local. Configuration is handled interactively via aiagentflow init, which writes a .aiagentflow/config.json file in your project directory.

aiagentflow init

The wizard walks you through selecting providers, entering API keys, assigning models per agent role, and setting workflow preferences.

Pro Tip: Run aiagentflow doctor after setup to verify all providers can connect and list available models.

Claude Sonnet 4 is the recommended model for architecture and coding tasks due to its strong reasoning and large context window.

Get your API key at console.anthropic.com.

Default model: claude-sonnet-4-20250514

OpenAI

Compatible with GPT-4o, GPT-4o-mini, and o-series models.

Get your API key at platform.openai.com.

Default model: gpt-4o-mini

Google Gemini

Gemini's large context window makes it excellent for analyzing large codebases.

Get your API key at aistudio.google.com.

Default model: gemini-2.0-flash

Groq

Groq provides extremely fast inference on open-source models. The free tier is generous — good for testing and rapid iteration.

Get your API key at console.groq.com.

Default model: llama-3.3-70b-versatile

OpenRouter

OpenRouter proxies 100+ models through a single OpenAI-compatible API. Many models are available for free — no credit card required.

Get your API key at openrouter.ai.

Default model: meta-llama/llama-3.1-8b-instruct:free

Free tier tip: Append :free to any model ID on OpenRouter to use the free version — e.g. google/gemma-3-12b-it:free.

Ollama (Local First)

For maximum privacy, run AI Agent Flow entirely offline using local models via Ollama.

  1. Install Ollama
  2. Pull a model:
    ollama pull llama3.2
    
  3. Select Ollama during aiagentflow init — no API key needed.

Default model: llama3.2:latest

Assigning Models Per Agent

During aiagentflow init you can assign different providers and models to each of the seven agent roles (Architect, Coder, Reviewer, Security, Tester, Fixer, Judge). This lets you use a powerful model for the Architect while using a faster/cheaper one for repetitive tasks like the Fixer.

The configuration is saved to .aiagentflow/config.json in your project root.

Workflow Settings

These fields live under workflow in .aiagentflow/config.json and can also be overridden per-run with CLI flags.

Worktree Isolation

{
  "workflow": {
    "isolation": "inplace",
    "autoMerge": "never"
  }
}
FieldValuesDefaultDescription
isolation"worktree" / "inplace""inplace"Run tasks in an isolated git worktree (--isolate) or directly in your working directory
autoMerge"never" / "on-judge-pass" / "always""never"When to auto-merge the worktree branch back into the source branch

Approval Gates

{
  "workflow": {
    "approvalGates": ["architect"]
  }
}

approvalGates is a list of agent roles where the workflow pauses for human review before continuing. Setting ["architect"] is equivalent to always passing --review-plan. Valid roles: architect, coder, reviewer, security, tester, fixer, judge.

MCP Servers

Agents can call external tools — read files, query databases, post to Slack, etc. — via MCP (Model Context Protocol) servers. Add a mcpServers map to .aiagentflow/config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "allowedRoles": ["coder", "tester"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}
FieldTypeDescription
commandstringExecutable to run the server (e.g. npx, python, node)
argsstring[]Arguments passed to the command
envRecord<string, string>Extra environment variables for the server process
allowedRolesstring[]Agent roles that may call this server's tools. Omit to allow all roles.

Use aiagentflow mcp list to see configured servers and aiagentflow mcp test <name> to verify a server starts and lists its tools correctly.

Finding MCP servers: Browse the official MCP servers repo for filesystem, GitHub, Postgres, Slack, and many more.

Plugins

Custom agents and providers can be added via the plugin system. Plugins live in .aiagentflow/plugins/ and are managed with aiagentflow plugin install/list/remove.

# Install from npm
aiagentflow plugin install @my-org/aiagentflow-linter

# Symlink a local plugin (for development)
aiagentflow plugin install ./plugins/my-custom-agent

Each plugin exports a manifest object declaring its name, version, and what it contributes (agent, provider, or both). Plugin-contributed agent roles appear in the workflow after their designated built-in anchor (e.g. after: "tester").

Plugin names must not clash with built-in roles (architect, coder, reviewer, security, tester, fixer, judge) or built-in providers (anthropic, openai, gemini, groq, ollama, openrouter).