Vercel's fx: A 7.8 MiB Embeddable Coding Agent Kernel Built with Zig

What Is fx

fx is a minimal, embeddable coding agent kernel and CLI written in Zig by Vercel Labs. It solves the same core problem as other coding agents — letting AI read, modify, and test code in the terminal — but with two sharp differentiators: a 7.8 MiB single binary with zero runtime dependencies, and an embeddable core exposed via createFxAgent() that can be dropped into any JavaScript application. Vercel positions it as "Tiny, open, embeddable, native coding agent," emphasizing native compilation over interpreter wrappers.

Three Forms from One Kernel

The same kernel powers three distinct interfaces:

Unix-style CLI: Run fx for a restrained terminal chat; fx ask "explain this repo's changes" for one-shot non-interactive queries. The UI deliberately avoids heavy TUI trappings — no default workspace path or Git branch in the status bar.

ACP for editors: fx acp implements the Agent Client Protocol, allowing VS Code and other editors to drive the agent directly.

Embedded in JS apps: npm install libfx then import { createFxAgent } from "libfx". Node.js uses a native addon; browsers use WebAssembly. An agent is an in-memory conversation object with only prompt, checkpoint, and close operations, enabling products to embed a full AI coding assistant without building their own agent framework.

Why Zig

The language choice reflects a coherent set of trade-offs:

Tiny compile artifact: 7.8 MiB vs. tens to hundreds of MB for TypeScript-based agents' node_modules.

Instant startup: CHANGELOG 0.0.8 states "Native Agent initialization is over 40× faster than the previous version." Native compilation eliminates interpreter warm-up.

Clean WASM target: Zig's WebAssembly support yields fx-core.wasm and fx-term.wasm that run directly in browsers, making embed scenarios natural.

Full control: The author controls every memory allocation and performance characteristic — critical for a kernel meant to run inside others' systems without forcing a heavy runtime on the host.

The README explicitly targets "research and embeddability as part of larger systems," signaling that the primary audience is developers embedding agent capabilities, not just terminal users.

Permissions and Security

An embeddable kernel demands a robust security model. fx provides:

Default auto mode: Routine dev actions execute automatically; each unconfirmed sensitive operation triggers a targeted safety review.

--full-access (formerly --yolo ): Disables permission checks for trusted environments.

Persistent permission memory: /permissions remember stores exact allow/deny rules; /permissions revoke retracts them — smarter than repeated prompts.

/trace command: Generates a private Markdown diagnostic file (logs, session context, permissions, recent activity) for debugging embedded scenarios.

Model-Agnostic Architecture

The kernel connects to multiple model sources without lock-in:

Vercel AI Gateway: fx login with an API key.

ChatGPT Codex subscription: fx login codex uses the user's ChatGPT subscription; Codex Fast mode gets priority service tier.

Grok subscription: fx login grok routes through xAI's Responses API.

Arbitrary Gateway models: Selectable via /model.

Privacy by design: Codex and Grok OAuth tokens stay local ( ~/.fx/chatgpt-auth.json, ~/.fx/grok-auth.json) and never reach Vercel AI Gateway. Subscriptions connect directly to the provider; tokens flow only between local machine and that provider.

Session Management

Engineered for long-running coding tasks:

Auto-compression: At 80% context capacity, long conversations compress into a new context window, continuing the same turn instead of hard truncation or manual session switching.

Cross-session resume: fx session resume restores a prior session; -c continues from the last turn. Compressed sessions retain original replies and tool results.

Corruption recovery: fx session recover extracts valid prefixes from damaged sessions into new ones, preserving checkpoints and referenced result files.

Sessions as files: All sessions stored as local files for manual management.

This is essential for multi-hour agent tasks where context exhaustion cannot crash the run.

Extensibility: Skills, MCP, Sub-agents

Skills: Reusable instruction packs invoked via $skill-name; skill catalog auto-trims to fit the model's context window.

MCP: /mcp browses MCP servers, tools, and resources inline; supports local stdio and Streamable HTTP transports. Project trust mechanism ( /mcp trust approve) prevents unreviewed servers from auto-connecting.

Sub-agents: subagent tool supports one-off task delegation and named persistent sub-agents; child sessions hang privately under the parent.

Limitations and Boundaries

Experimental status: README warns "Status: Experimental. Use at your own risk"; 194 open issues; rapid iteration but no stable release.

Shallow ecosystem: Less than a month old; Skills/MCP ecosystem far less mature than Claude Code's.

Requires subscriptions or Gateway keys: Codex/Grok need personal subscriptions or an AI Gateway API key — not free out of the box.

Zig build barrier: Source builds need Zig 0.16+ (though curl -fsSL https://fx.sh/setup.sh | bash provides one-click install).

Kernel Design: Why It Stays Small

Source layout under src/ splits into core (conversation loop, model routing), tools (tool execution), ui (rendering), acp (Agent Client Protocol) — all hand-written, no heavy frameworks. Size discipline comes from deliberate subtraction:

No duplicate storage: Sessions are local files; no server-side database.

Lean toolset: 0.0.8 cut shell tool actions from 12 to 3 (75% reduction) and sub-agent commands from 6 to 2 — fewer but more general, hence more stable.

On-demand context: Skill catalogs adaptively trim to the model's context window, avoiding irrelevant prompt bloat.

This minimalism isn't corner-cutting; it constrains the kernel to a size that can be audited, trusted, and maintained long-term — crucial for code that runs inside someone else's system.

Embedding Engineering Details

Embeddability is backed by concrete engineering:

Zero-runtime libfx : The npm package has no runtime dependencies; import does not connect MCP, scan skills, or touch the filesystem.

Backpressure: Output is "lossless with backpressure" — slow consumers pause production instead of unbounded event queue growth, preventing host memory exhaustion.

Event-stream API: createFxAgent() emits standardized events ( text_delta, reasoning_delta, tool_start, tool_end), giving the host precise control over rendering and interaction rather than locking them into a black-box CLI.

Cancellation: turn.cancel() and agent.close() release blocked output promptly, avoiding host process hangs.

These details show fx's embeddability is designed for host developers from the ground up, not bolted on later.

Performance: Speed as a First-Class Citizen

A dedicated benchmarks/ directory uses hyperfine for regression tracking. CHANGELOG 0.0.8 documents a 40× initialization speedup alongside 75% shell tool reduction and 67% sub-agent command reduction. For coding agents, startup latency and response delay define UX: fx ask "explain this repo" ready in 0.1 s vs. 5 s is a qualitative difference. Native compilation achieves what interpreter-based approaches physically cannot. Performance tuning and feature pruning proceed in lockstep — the design rejects bloat, treating smallness itself as a performance feature.

Installation and Getting Started

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

Then log in per model source: fx login — Vercel AI Gateway (needs API key) fx login codex — ChatGPT subscription fx login grok — xAI subscription fx setup — configure AI Gateway API key

Run fx in a project directory for interactive chat, or fx ask "..." for one-shots. To embed: npm install libfx and instantiate via createFxAgent(). Building from source requires Zig 0.16+: zig build -Doptimize=ReleaseSafe produces the fx binary.

Privacy and Data Boundaries

Sessions stay local: Stored as files under ~/.fx/; no auto-upload. /trace diagnostics require manual sharing.

Subscription tokens bypass Vercel: Codex/Grok OAuth credentials remain local, connecting directly to the respective provider. README explicitly states tokens are never sent to Vercel AI Gateway or OpenAI.

FX_AUTH_MODE=host-managed : Embedding hosts can inject auth at their network boundary; fx then stops reading/writing local model credentials and stops adding auth headers — authentication fully delegated to the host.

This default-local data design matters for embedded scenarios: user data shouldn't leak to third parties just because an agent library was included.

Positioning vs. Claude Code / Codex

Claude Code / Codex: Full-featured standalone coding agents for end users; mature ecosystems, batteries included.

fx: A tiny, embeddable agent kernel. For terminal users, a lightweight Unix-style CLI; for developers, a createFxAgent() primitive to embed in their own products.

If you want a polished terminal experience with rich ecosystem, Claude Code/Codex win. If you need "embed an agent capability in my app" or "a coding CLI that starts instantly," fx is the most compelling attempt yet — it reframes the coding agent from an application to a kernel, a directional shift.

Project Status and Background

fx originates from Vercel Labs (Vercel's experimental arm, source of several high-quality open-source projects). Created mid-August 2026, it amassed 2.8k+ stars in under a month, signaling strong demand for small, embeddable agents. Iteration velocity is high — version 0.0.8 already carries a long CHANGELOG of substantive changes: 40× init speedup, tool pruning, sub-agent rewrite, MCP browser, WASM SDK, JSPI support. Yet it remains Experimental ("Use at your own risk"), with 194 open issues and early-stage model/skill ecosystems. Production-grade workflows should wait; but for exploring the "agent as kernel" direction, now is the time.

Who Should Use fx

Developers embedding AI programming capabilities into their own products — fx's WASM/SDK is purpose-built for this.

Terminal users craving minimalism and speed — tired of heavy TUIs and Node dependencies, wanting a Unix-tool-fast coding agent.

Researchers studying agent architecture — small kernel, clear Zig source, ideal for examining a minimal agent closed loop.

Vercel ecosystem users — seamless AI Gateway integration.

Core Design Philosophy to Remember

fx's highest-value contribution isn't "another coding agent" but a rethink of the agent's form : instead of a bulky standalone app, build a tiny, embeddable kernel and let the caller choose the interface. This reflects Vercel's ecosystem mindset — AI Gateway unifies model access, fx unifies the agent kernel, together turning agent capability into a freely composable infrastructure component rather than a feature locked inside a specific terminal tool. As AI coding assistants move from "application" to "kernel," the real imagination lies in: the next person who embeds createFxAgent() into their product may build something we haven't imagined yet . fx has laid that foundation small enough, fast enough, and open enough.