From install to your first traceable feature.

01Install

One extension — no account, no companion app.

Grab it from the VS Code Marketplace (VS Code & Insiders) or Open VSX (VSCodium, Windsurf, Gitpod). After install, the AFX icon appears in the activity bar and AFX: Open Workbench opens the bottom panel. Works in VS Code, VS Code Insiders, VSCodium & Antigravity (pre-2.0).

Search "agenticflowx" in the Extensions panel and hit Install. illustration

02Connect a model

No vendor billing — you bring the access you already have. All three paths live in Settings → Provider; keys are stored in VS Code SecretStorage, or read from an env var or shell command.

Settings → Provider — subscriptions, keys, and runtimes on one surface. Configure several; switch mid-conversation.

03Model recipes

Frontier plans, value APIs, or fully local — concrete steps for each.

Anthropic · Copilot · ChatGPT

subscription · OAuth

Sign in with the plan you already pay for — a browser OAuth flow, no key to paste.

1. Settings → Provider → pick Anthropic, GitHub Copilot, or ChatGPT (Codex) and hit Sign in.
2. Approve in the browser — Anthropic and Codex use a loopback flow, Copilot shows a device code.
3. Done. Models appear in the picker immediately.

anthropic → claude-opus-4-7github-copilot → gpt-5.4openai-codex → gpt-5.5

Subscription sign-ins — connected accounts show their models right in the same list.

OpenAI · Gemini · xAI · Mistral

API key

Pick the provider, paste the key — SecretStorage keeps it local. Matching env vars work too.

OPENAI_API_KEY → gpt-5.4GEMINI_API_KEY → gemini-3.1-pro-previewXAI_API_KEY → grok-4.20-reasoningMISTRAL_API_KEY → devstral-medium

Key entry — stored in VS Code SecretStorage, masked from telemetry, never written to disk in plain text.

DeepSeek

API key · value pick

Strong coding performance at a fraction of frontier pricing — a favorite for mechanical edits and long sessions.

1. Get a key at platform.deepseek.com.
2. Settings → Provider → DeepSeek, paste it (or set DEEPSEEK_API_KEY).

default → deepseek-v4-pro

DeepSeek in provider settings — key in SecretStorage, models ready in the picker. illustration

Xiaomi MiMo

API key · regional plans

Four catalog entries: the standard API plus dedicated Token Plan variants so billing routes to your region.

1. Settings → Provider → Xiaomi MiMo and paste your key (XIAOMI_API_KEY).
2. On a token plan? Choose the CN, AMS, or SGP variant instead — each has its own key field.

default → mimo-v2.5-proToken Plan → CN · AMS · SGP

Four MiMo entries — standard API plus region-billed Token Plan variants. illustration

Kimi · MiniMax · Z.ai · Groq

API key

All in the built-in catalog with their own key fields — Kimi also ships as the "Kimi For Coding" plan provider, MiniMax has global and CN endpoints, Groq serves very fast open-weight inference.

moonshotai → kimi-k2.6minimax → MiniMax-M2.7zai → glm-5.1groq → gpt-oss-120b

Each catalog entry ships its own key field and default model — no custom config needed. illustration

Routers & enterprise

gateways

OpenRouter (openrouter.ai/api/v1) — one key, hundreds of models, preset included. Vercel AI Gateway and Cloudflare AI Gateway / Workers AI are presets too. Enterprise: Amazon Bedrock, Azure OpenAI, and Google Vertex live in the catalog with their own auth fields.

The good habit: configure two or three. A frontier model for design and review, DeepSeek or a local model for mechanical edits — switch mid-conversation from the composer without losing the thread.

Ollama

local · no key

1. Pull a model: ollama pull qwen3-coder — anything in the Ollama library.
2. Settings → Provider → Add custom → Ollama. Base URL prefilled: http://localhost:11434/v1, key source none.
3. Your local models join the same picker as everything else.

Local runtimes — point AFX at Ollama, or connect your installed Pi CLI and reuse its config.

llama.cpp

local · Custom preset

llama.cpp's server speaks the OpenAI API — the blank Custom preset points AFX at it in under a minute. LM Studio (localhost:1234/v1) and vLLM (localhost:8000/v1) have dedicated presets with the same no-key flow.

1. Start the server: llama-server -m your-model.gguf — it listens on port 8080.
2. Settings → Provider → Add custom → Custom. Base URL http://localhost:8080/v1, API type OpenAI completions, key none.

The Add-custom picker — nine presets, or fill in any OpenAI-compatible endpoint.

04Already on Pi? You're done.

If you drive Pi from the terminal today, AFX plugs straight into your installed Pi CLI — nothing changes on Pi's side. Same config, same sign-ins, same sessions.

1. Settings → Provider → Runtimes → Detect Pi CLI. AFX finds pi on your PATH.
2. That's it — the rest is automatic. AFX points afx.agentBinaryPath at your binary and switches the runtime to Pi RPC (the bundled SDK steps aside).
3. Pi stays yours. Your ~/.pi/agent config (or $PI_CODING_AGENT_DIR), provider auth, and skills are Pi's own — AFX shares Pi's session directory, so terminal and VS Code history live in one place.

One click: detect, and AFX drives your Pi over RPC — config, auth, and sessions untouched. illustration

The Runtimes surface — Pi CLI connection alongside local runtime presets.

05Using the three modes

A mode answers one question: how much may the agent touch? Switch any time with Ctrl+Shift+M or the status bar — mid-conversation is fine. The composer's intent strip follows the mode (Ctrl+Alt+M cycles intents).

Ctrl+Shift+M — the mode switcher. illustration

Code — the default

Use it for everyday work: ask, edit, run, follow up while context is fresh.

• Intents: Default · Ask · Architect · Code — Default sends exactly what you type; zero injection, zero extra tokens. Ask answers without editing; Architect thinks structure-first; Code implements.
• Full access: file edits, commands, the works — with the persistence checkpoint guarding large multi-file writes.

Explore — read-only, enforced

Use it for unfamiliar repos, reviews, and "what does this actually do?" sessions — when you want answers with a hard guarantee nothing changes.

• Real guardrails: write, patch, and mutating shell/git/npm tools are blocked host-side — not a polite prompt. Read-only git (status, diff) stays available.
• PRD intent: Explore swaps the fourth intent slot for PRD — investigate a repo, come out with product requirements.

Explore mode — investigate without touching a line.

What Explore can — and can't — do

The read-only promise is enforced by the extension itself, not just asked of the model. Mutating tools are blocked at the host before they ever run.

Reach for Explore when you're landing in an unfamiliar codebase, reviewing a change with zero risk of touching it, planning before you build, or investigating a bug whose cause you don't know yet. When you're ready to act, switch to Code or Spec — Ctrl+Shift+M.

Explore mode — ask anything, change nothing.

Spec — planning-first

Use it when a piece of work needs to survive the session: requirements, design decisions, tasks a teammate (or tomorrow's you) can pick up.

• Doc-aware composer: a Spec → Design → Tasks stepper sits above the input, tracking where the feature stands; a Sign-off button gates each step.
• Still ships code: Spec mode is markdown-centric, but the task Code action implements straight from the document.

Spec mode — the stepper keeps the document chain honest while you chat.

06Skills & trust

The extension bundles the AFX core — 17 skills in the current build (its pinned skills snapshot predates the new /afx-dash; the CLI and marketplace packs carry all 18). It also discovers any standard skills Pi supports: your team's, your personal ones, other packs.

Settings → Skills shows everything loaded with source paths, scope, and trust controls. By default AFX asks before using a project's own skills (afx.pi.projectTrust) — trust a repo once and it remembers.

How skills load

Skill loading is Pi's mechanism, and it follows the Agent Skills standard. Pi scans global (~/.pi/agent/skills/, ~/.agents/skills/) and project (.pi/skills/, .agents/skills/ up to the git root) locations, plus package skills/ dirs, a skills settings array, and explicit --skill paths. Any directory containing a SKILL.md is discovered recursively.

Loading is progressive disclosure: at startup only each skill's name and description enter the system prompt; the full SKILL.md — instructions, scripts, references — is read on-demand when a task matches, or forced with /skill:name. That's why the 18-skill core pack costs only ~1k always-on tokens.

Where Pi looks, and how loading stays cheap — descriptions always in context, full skills on demand. illustration

Settings → Skills — bundled core shown separately from discovered skills, with per-project trust.

07Settings & history

Providers, models, context behaviour, and runtime options live in the extension's own Settings tab — also under afx.* in VS Code settings.

Appearance is configurable too: Meridian ships seven style variants — lyra, luma, maia, nova, vega, mira, sera. Anonymous telemetry has a clear opt-out, and key fields are masked from capture.

08The AFX CLI

AFX skills follow the open agentskills.io standard, so Claude Code, Codex, and GitHub Copilot run the workflow natively — no VS Code, no separate runtime. The CLI is the installer:

1. Run the installer from your project directory — it prompts for which agents you use.
2. It sets up .claude/skills/ and/or .agents/skills/, .afx.yaml, docs/specs/, docs/adr/, and your agent context files.
3. Start working — /afx-next tells any agent where the project stands and what to do next.

A real install run — the CLI prompts for your agents, syncs the 18 skills, and writes the context files. illustration

09Skill packs

The AFX workflow ships as packs of standard skills. Every skill's SKILL.md name maps 1:1 to the slash command you type — install a pack, get its commands.

Install from the Claude Code marketplace

Each pack is a Claude Code plugin. Skills register immediately — the core pack costs ~1k always-on tokens; full instructions load only when a command runs (progressive disclosure).

Or with afx-cli (any agent)

Pack → command reference

Arguments ride along as text: /afx-task pick, /afx-sprint code, /afx-session note "decision…" — the skill reads everything after its name.

—FAQ