fx in Practice: Setup, Scripting, and Subagents

Official Sources#

Last updated: August 23, 2026

fx went public on August 18, 2026 and the HN thread did what HN threads do: argued about whether a 26-tool agent needs to exist when pi already ships most of it. Lost in that argument was the practical answer to a simpler question - what is it like to actually install, authenticate, and drive? This guide walks the real setup path from the official docs, then shows what each of fx's four surfaces (interactive CLI, scripted fx ask, ACP server, embedded WASM) is for. Everything below is verbatim from fx.sh documentation or the repository README unless labeled otherwise.

Install#

One line, per the README:

curl -fsSL https://fx.sh/setup.sh | bash

The installer places the binary in ~/.local/bin. The docs flag two follow-ups worth knowing before you run it: read the Installation notes if piping scripts to a shell gives you pause, and check your PATH afterward if fx does not resolve immediately. Building from source requires Zig 0.16.0+:

git clone https://github.com/vercel-labs/fx.git
cd fx
zig build -Doptimize=ReleaseSafe
./zig-out/bin/fx

The README carries an explicit status banner: "Experimental. Use at your own risk." That is the honest frame for everything else in this guide.

Three ways to sign in#

fx separates the harness from inference, and the auth paths reflect that. All three come verbatim from the README:

Route 1 - Vercel AI Gateway (default):

fx login

This opens the Vercel authorization flow and stores the session for later runs. An AI Gateway API key works too, via:

fx setup

Route 2 - ChatGPT subscription through Codex OAuth:

fx login codex
fx

Route 3 - Grok subscription through xAI OAuth:

fx login grok

The privacy mechanics are documented precisely and matter: the Codex route "uses ChatGPT subscription access directly and never sends its OAuth token to Vercel AI Gateway," storing the session privately at ~/.fx/chatgpt-auth.json. The Grok route works the same way against xAI, with its session at ~/.fx/grok-auth.json. Inside fx, /setup offers a Switch provider action, /model lists the active provider's catalog, and /logout codex or /logout grok removes one subscription session without touching the others. On supported Codex models, /fast requests OpenAI's priority tier and consumes ChatGPT credits at the higher Fast mode rate - a nice piece of honesty that the faster lane costs plan quota faster.

First run#

From the quick start:

cd path/to/project
fx

The launch directory becomes the primary workspace. Type a request that names real files - the docs' own example is "Read src/ and tell me how requests are routed. Then add a test for the error path in the router and run the test suite." - and press enter. Tool calls stream into the transcript as they run; escape or ctrl+c interrupts a turn, and ctrl+o opens Review with the full transcript.

Two small quality-of-life details from the docs are worth adopting deliberately. Saved sessions name their terminal tab automatically (session name first, workspace fallback, active model as context), which makes multi-window work legible. And session management is a proper command group:

fx sessions
fx session resume last
fx session resume --id <id>

The permission model, in practice#

fx starts in auto permission mode, and the docs describe a three-layer sequence rather than a y/n prompt: saved rules apply first; an unresolved sensitive call gets "one narrow safety review based on the current user request and the exact pending action"; anything still unresolved becomes an approval prompt with three choices - run once, run and stop asking for that scope this session, or decline.

For automation-minded users the durable layer is the rules store. Inside a saved session:

/permissions remember <allow|deny> <tool-name> <arguments-json>

/permissions lists stable rule IDs and /permissions revoke <rule-id> removes one even if workspace state changed since. That is the same "policies live outside the model's judgment" instinct we saw in Herdr's community policy layers, shipped natively.

Noninteractive behavior is documented just as tightly: JSON and quiet requests stay noninteractive by default, piped or redirected stdin fails rather than waiting for approval, and prompt text goes to stderr so JSON stdout stays parseable. If you want interactive approvals in a TTY-driven script, --prompt-permissions opts in explicitly.

Scripting with fx ask#

fx ask is the single-shot surface - one noninteractive request, then exit:

fx ask "explain the changes in this repository"

Generated prompts arrive over stdin, so shell pipelines stay natural:

printf "summarize src/core\n" | fx ask

Images attach with a repeatable flag:

fx ask --image ./ui.png "describe this interface"

For programs, --json returns structured output instead of Markdown. The documented response shape:

{
  "output": "Assistant Markdown",
  "exit_code": 0,
  "model": "provider/model-id",
  "session_id": "session-id",
  "steps": 1,
  "usage": {
    "requests": 1,
    "input_tokens": 1200,
    "output_tokens": 450
  },
  "tool_calls": [
    { "name": "read_file", "status": "success" }
  ]
}

Failures return nonzero exit_code and can include an error field. The docs are specific about accounting: requests counts settled main-agent completions, and all three usage fields read zero when no request settles, such as an argument failure. In shell scripts, stdout carries raw assistant Markdown while progress and diagnostics stay on stderr - the split that makes CI integration sane. This is the same scripting shape our Codex recurring-work and OpenCode cron guides build on, and fx ask slots into those patterns unchanged.

Subagents without the ceremony#

The subagents documentation describes a child fx session controlled by another agent: same workspace and runtime, its own model, reasoning effort, permission mode, transcript, and lifecycle. Two run modes exist - a one-off child that runs one prompt and finishes, and a persistent child that returns to idle after each turn, stays resumable, and receives queued messages durably, so the child works without copying its full transcript into the parent's context.

Inside an interactive session, ctrl+x opens the manager, which can show the child tree, create and open persistent children, send follow-up instructions, change model/effort/permissions per child, reparent sessions, and resolve child approval requests. Under the hood the model sees exactly one subagent tool with six branches - create, inspect, message, relationship, configure, lifecycle - a design that keeps the tool surface flat while the capability set grows.

This is the quiet counterpoint to the minimalism debate: pi refuses sub-agents on principle ("spawn pi instances via tmux"); fx includes them but keeps them structurally cheap. Neither is wrong - they are optimizing different axes, which our fx deep dive covers in full.

Embedding: the fourth surface#

The README's embed table is short enough to reproduce:

Applications embedding fx provide their own network transport, session storage, configuration, permission handling, and terminal I/O. The WebAssembly SDK is labeled experimental by the project itself, so treat browser embedding as a preview capability - though it is already running publicly at fx.sh/try. For editor users today, fx acp is the stable path.

Extending#

fx takes instructions and tools through three documented channels: reusable skills, external tools via MCP, and the subagent system above. Notably, fx embraces MCP - the protocol pi famously refuses - plus skills and subagents, all inside the 7.8 MiB binary. fx status and fx doctor report an invalid trusted MCP profile without starting its servers, which is the kind of fail-loudly detail that suggests the harness authors have operated fleets before.

Honest gaps#

Stated plainly, mostly by the project itself: the status banner says experimental and means it - v0.0.5 shipped within two weeks of launch, and early-version churn is guaranteed. The WASM SDK is experimental. Subscription model IDs are "the raw IDs returned by each authenticated catalog," which means provider-side renames flow straight through to your config. Memory footprint claims in the README (the 7.8 MiB figure versus a measured 6.39 MiB release artifact) have a small unexplained gap our deep dive flags. And there is no team/managed-deployment story documented yet - this is a single-developer tool today.

FAQ#

Is fx free?#

fx itself is Apache-2.0 open source. You pay for inference behind it: Vercel AI Gateway usage, your ChatGPT subscription (via Codex OAuth), or your Grok subscription (via xAI OAuth).

How does fx differ from Claude Code?#

fx is a minimal native harness with three swappable inference routes; Claude Code couples the harness to Claude models and adds product depth (skills ecosystem, Cowork, managed settings). Our comparison series covers the trade-offs.

Does my ChatGPT token go to Vercel?#

No. The README states the Codex OAuth token is stored locally at ~/.fx/chatgpt-auth.json and never sent to Vercel AI Gateway. The Grok token never reaches Vercel or OpenAI either.

Can I use fx in CI?#

Yes - that is what fx ask is for. Keep stdout clean for parsing (add --json for structure), rely on stderr for diagnostics, and remember piped stdin fails closed instead of waiting for approval prompts.

What is auto permission mode?#

The default mode where routine understood actions run directly, unresolved sensitive calls get one narrow automated safety review, and anything still unresolved becomes an approval prompt with run-once, run-always-this-session, or decline options.

Can multiple fx agents work together?#

Yes, via subagents: one-off children for single tasks, persistent resumable children for ongoing lanes, coordinated through the ctrl+x manager with durably queued messages.

How big is the binary really?#

The README says 7.8 MiB; the published v0.0.5 artifact measures about 6.39 MiB. Either way it is an order of magnitude smaller than heavyweight Electron-free CLIs, and cold-start latency is CI-enforced at budget by the project's own tests.

Does fx run in the browser?#

Yes, experimentally. createFxAgent() and createFxTerminal() wrap fx-core.wasm and fx-term.wasm respectively, and a public demo runs at fx.sh/try.

The takeaway#

fx's setup story is the product thesis in miniature: one install line, three auth routes with explicit token boundaries, a permission system that degrades gracefully from autonomous to scripted contexts, and four surfaces sharing one core. Start with fx login and the interactive shell, graduate to fx ask --json when a workflow stabilizes, and keep an eye on the ACP route if you live in an editor. For where fx sits in the broader minimal-agent wave, read our deep dive on the project, the pi architecture deep dive for the other pole of the minimalism debate, and our OpenCode developer guide for the established open-source middle ground.