vercel-labs/fx: a Unix-style coding agent written in Zig

What fx is for, and who should care

fx is a coding agent harness and CLI written in Zig. The README describes it as 'optimized for research and embeddability as part of larger systems', and that phrase sets the audience. This is not aimed at someone who wants an IDE in the terminal. It is aimed at two groups: people who want an agent that behaves like a Unix command, and people building larger systems who want to drop an agent core into their own host.

The form factor matters more than the feature list. The README says the CLI output style 'aim[s] to be closer to a Unix shell than a heavy "IDE in the terminal" TUI'. That is a deliberate trade-off. You lose persistent panes and rich rendering; you gain something that composes with pipes, scripts and existing terminal habits. The 7.8 MiB binary and the model-agnostic design (local or cloud inference) point the same way.

If your workflow already lives in a terminal and you resent giving up the screen to a TUI, fx is addressing you directly. If you want a graphical agent with a plugin marketplace, it is not.

How fx runs a turn: sessions, tools and permission review

Running fx from a project directory makes that directory the primary workspace. You type a prompt, or run /help to browse interactive commands. While fx is working, Enter queues a follow-up and Ctrl+Enter steers the active turn at its next model boundary; if the turn has already closed, the steering prompt is queued as the next turn instead.

The permission model is the most interesting mechanism here. fx starts in auto mode. Routine development actions run directly. Each unresolved action gets one narrow safety review based on the current user request and the exact pending action. A clear result authorizes only that action. A caution, or a review that is unavailable, holds the action and returns advice to the agent without opening a permission prompt or ending the turn. That is a different shape from the usual approve/deny dialog: the agent receives guidance rather than a blocked turn.

Tool calls are expanded by default. You can collapse them in /settings, or set "collapse_tool_calls": true in ~/.fx/settings.json, to show one summary per tool-call group. Individual calls stay available in the full transcript with Ctrl+O. Sessions are saved and listed with fx sessions, and resumed with fx session resume last or fx session resume --id <id>.

For noninteractive use, JSON and quiet requests stay noninteractive by default. Adding --prompt-permissions allows configured approval prompts when stdin is a TTY, but automatic safety review never opens that prompt. Prompt text goes to stderr, so JSON stdout stays parseable and quiet stdout stays empty. Piped or redirected stdin remains noninteractive and fails rather than waiting for approval. That is a sensible decision for scripting, and also a sharp edge: a pipeline that would have worked interactively will fail instead of prompting.

Installing fx and running a first request

The README gives a single install command. It pipes a setup script from fx.sh into bash, so read the script first if that pattern bothers you.

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

After installing, sign in. The README lists three routes: Vercel AI Gateway, an eligible ChatGPT subscription through OpenAI Codex OAuth, and an eligible Grok subscription through xAI OAuth. The Codex route is:

fx login codex
fx

The Grok route is the same shape:

fx login grok
fx

Inside fx, /setup opens the configuration surface, where Model provider moves between Gateway, Codex and Grok, and /model lists the active provider's fetched models. To use an AI Gateway API key instead of a subscription, run fx setup.

For a first real use, cd into a project and start fx there. The current directory becomes the primary workspace. A single request without the interactive session looks like this:

cd your_project
fx ask "explain the changes in this repository"

With --json, the output field contains accumulated assistant Markdown across the request, while final_output contains only a completed final assistant response and is an empty string for interrupted, failed, background or otherwise absent final responses. That distinction matters if you are parsing the result in a script: final_output being empty is not the same as an error, and the README documents no separate error field for that case.

Subscription sign-in, token storage and what leaves your machine

The README is unusually explicit about where credentials go, and this is worth reading before you log in. The OpenAI Codex route uses ChatGPT subscription access directly and, per the README, never sends its OAuth token to Vercel AI Gateway. The session is stored privately at ~/.fx/chatgpt-auth.json and refreshed when needed. On supported Codex models, /fast requests OpenAI's priority service tier and consumes ChatGPT credits at the higher Fast mode rate.

The Grok route is described the same way: subscription access directly at xAI, the OAuth token never sent to Vercel AI Gateway or OpenAI, the session stored at ~/.fx/grok-auth.json, refreshed when needed, and used only with the authenticated xAI catalog and Responses API. Both can be removed with /logout codex or /logout grok without affecting other providers.

Two things follow. First, subscription model IDs are the raw IDs returned by each authenticated catalog, so the model names you see depend on what the provider returns, not on a curated list in fx. Second, the privacy claims are claims in the README about token routing, not an audit. If your threat model requires verifying that no token leaves the machine, the README alone will not settle it; the stored JSON files under ~/.fx are the concrete artifacts you can inspect.

There is also /trace, which creates a private Markdown diagnostic with logs, session context, runtime state, permissions and recent activity. On macOS it copies the .md file to the clipboard; elsewhere it saves the file and prints the path. The README tells you to review and redact the trace before sharing it, which is the right instruction and also an admission that the file is not automatically safe to post.

Embedding through ACP and the WebAssembly SDK

The embeddability claim is backed by three surfaces listed in the README. fx acp connects the native agent to editors and other Agent Client Protocol clients. createFxAgent() embeds the agent core in a JavaScript host with fx-core.wasm. createFxTerminal() embeds the interactive terminal with fx-term.wasm. Applications embedding fx can supply network transport, session storage, configuration, permission handling and terminal I/O.

That list is the real architecture statement. fx does not assume it owns the network or the filesystem; the host provides them. It is why the project describes itself as a harness rather than an application. The repository layout supports this reading: there is a top-level sdk/ directory alongside src/, tests/ and examples/, and the examples directory contains browser-agent, nextjs-agent, node-chat and nuxt-agent entries, which are JavaScript hosts rather than Zig ones.

The limitation is stated plainly: the README calls the WebAssembly SDK experimental and points to sdk/README.md and the ACP documentation. If you are embedding fx in a product, treat those two documents as the boundary of what is currently promised. The native binary path and the WebAssembly path are not described as equally mature, and the README does not give a stability guarantee for the JavaScript API surface.

Where fx is the wrong tool

The README's own status line is 'Experimental. Use at your own risk.' That is not boilerplate here. The release history shows v0.0.4, v0.0.5 and v0.0.6 within about a week of each other in August 2026, which is the cadence of a project still finding its shape rather than one holding an API steady.

Concretely, three cases argue against fx. First, if you need a documented, stable extension ecosystem, the README points at skills, MCP and subagents through external documentation pages, and the MCP section is truncated in the README itself. You are depending on docs hosted at fx.sh, not on a frozen specification in the repository. Second, if your team relies on a full-screen TUI with panes and mouse interaction, fx is explicitly not that. Third, if you are looking for a general Vercel product, this is not one: fx is a vercel-labs repository, and the Vercel connection visible in the README is the AI Gateway as one of three model providers.

There is also the scripting edge noted earlier. Noninteractive JSON and quiet modes fail rather than wait for approval when stdin is piped or redirected. A CI job that runs fx ask without --prompt-permissions and without a TTY should expect failure on any action the safety review holds, not a prompt. The README documents no retry or fallback for that case.

Alternatives and the difference in approach

The closest comparison the README invites is with terminal agents that present an IDE-like TUI. Those tools put the interface first: persistent panes, diffs rendered in place, a plugin surface designed for end users. fx inverts that. Its README says the CLI output style aims to be closer to a Unix shell, tool calls are expanded by default (collapsible, not hidden), and the binary is 7.8 MiB. If you want the richest possible interactive experience, the TUI-first tools are the better fit and fx is the wrong pick. If you want an agent that behaves like a command and can be embedded, the trade-off runs the other way.

The second comparison is against agents that are tightly bound to one model vendor. fx is model-agnostic by design and ships three sign-in routes: Vercel AI Gateway, OpenAI Codex OAuth and xAI Grok OAuth. A vendor-bound agent will typically have a simpler setup because there is one catalog and one billing path. fx's flexibility costs you a provider-selection step inside /setup and, for the subscription routes, model IDs that are whatever the authenticated catalog returns.

The third comparison is against embedding a general-purpose agent framework in your own application. Those frameworks usually give you a library in a mainstream language with a broad tool ecosystem. fx gives you a native binary plus fx-core.wasm and fx-term.wasm, with the host supplying transport, storage, permissions and terminal I/O. That is a smaller, lower-level contract, and the README marks the WebAssembly SDK experimental. Choose fx for embedding when the binary size and the Zig core are the point; choose a framework when ecosystem breadth is.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-08-25, and the most recent release is v0.0.6 on the same date. The repository is not archived. On the evidence of the release list, work is current, but the version numbers are all 0.0.x, so nothing in the repository promises API stability. The CHANGELOG.md at the top level is where release-to-release changes are recorded; read it before upgrading rather than assuming the WebAssembly or ACP surfaces are frozen.

fx is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. The repository carries a THIRD_PARTY_NOTICES.md file, which is where the bundled dependencies' terms are listed. If you redistribute the binary or embed the WebAssembly modules in a product, that file is the first thing to read, along with LICENSE itself. Nothing here is legal advice, and the licence text governs.

Upgrade cost is dominated by two moving parts. Subscription model IDs come from the provider catalogs, so a model rename on the provider side can change what /model lists without any fx release. And the permission and settings surfaces live in ~/.fx/settings.json and the docs, so a configuration you write today may need review against the CHANGELOG when you move versions. Pinning a version and reading CHANGELOG.md before each bump is the cheap path.

Editorial conclusion

fx suits engineers who want a small, scriptable agent they can drive from a shell or embed through the WebAssembly SDK, and who are comfortable with a project whose README says 'Experimental. Use at your own risk.' It is the wrong choice if you need a stable, documented plugin ecosystem or a full-screen TUI, and it is not a general-purpose Vercel hosting tool. Before adopting it, check the permissions model in the docs, the licence and THIRD_PARTY_NOTICES.md, and whether the ACP and WebAssembly surfaces are stable enough for your host application.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes