fx: Open-Source Native Coding Agent by Vercel Labs

fx is an open-source coding agent harness and CLI tool from Vercel Labs, written in Zig. You can start it inside a repository, ask it to inspect and change code, run shell commands, continue saved sessions, or use it for a single scripted request.

The same agent runtime also powers several other entry points. fx ask handles headless tasks, fx acp connects the native agent to ACP clients, and the experimental WebAssembly SDK exposes the runtime to JavaScript applications.

Skills, MCP servers, project instructions, permissions, additional workspaces, and subagents extend the core when your project needs more context or tools.

What fx Can Do in a Repository

A normal coding session can combine several operations in one task:

• inspect files and directory structure;
• search source code;
• read and edit files;
• create, rename, copy, or delete files;
• run shell commands, tests, linters, and build tools;
• keep development servers or watchers running as background commands;
• search the public web and fetch known public URLs;
• work with image attachments;
• load reusable Agent Skills;
• call tools exposed by MCP servers;
• create child agents for independent work;
• continue work across saved sessions.

For example, you can start fx at a repository root and enter a task such as:

Inspect the authentication flow, find the failing error path, add a regression test, and run the relevant tests.

The agent can inspect the repository, choose tools for the task, propose file changes, and run commands under the active permission policy.

Install fx

Install the latest release. The installer places fx in ~/.local/bin by default. Set FX_INSTALL_DIR before running the installer if you want another location.

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

For an installation that tracks a fixed release in automation, pass the version explicitly:

curl -fsSL https://fx.sh/setup.sh | bash -s -- <version>

Verify the binary and run local health checks:

fx --version
fx doctor

Building from source requires Zig 0.16 or newer:

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

Authenticate and Start Your First Session

fx can authenticate through a Vercel login:

fx login

You can also configure a Vercel AI Gateway API key:

fx setup

After authentication, move into the repository you want to work on:

cd your_project
fx

The current directory becomes the primary workspace. Type a task directly into the prompt, or enter /help to inspect interactive commands.

For a one-off request, use fx ask:

fx ask "explain the changes in this repository"

Machine-readable output is available through --json:

fx ask --json "summarize the current changes"

The JSON result contains the model output plus execution metadata such as exit code, model, session ID, step count, and tool calls.

Sessions, Resume, Recovery, and Compaction

fx saves interactive conversations under ~/.fx/sessions/. Starting plain fx creates a new session for the current workspace.

List saved sessions:

fx sessions

Inspect the latest session:

fx session last --json

Resume the latest session:

fx resume last

Resume a specific session:

fx resume <session-id>

A headless request can continue the same conversation:

fx ask --resume last "continue with the tests"

fx stores partial responses and recovery checkpoints. Inside the interactive shell, /continue resumes a paused model response. A headless run can continue recoverable work with:

fx ask --resume last --continue-recovery

To make a recoverable copy of a damaged session:

fx session recover <session-id>

Older session formats can be migrated with:

fx session migrate <session-id>

Long conversations use automatic context compaction. After eight completed turns, fx keeps the latest four turns verbatim and condenses older work for subsequent model requests. The saved transcript stays intact. Run /compact when you want to compact the older part of a conversation before the next phase of work.

Models and AI Gateway Usage

List all available models from the shell:

fx models
fx models --json

Inside an interactive session:

/models
/model openai/gpt-5.4

For a temporary process-level model choice:

FX_MODEL=openai/gpt-5.4 fx

fx itself is open source. Hosted model calls use AI Gateway and follow the pricing of the selected model and provider. Inspect usage recorded locally by fx with:

fx usage
fx usage --period 24h --json

Inside the interactive shell:

/usage

/cost is an alias for /usage.

Check the AI Gateway credit balance with:

fx credits
fx balance

or:

/credits
/balance

Permissions and Command Sandboxing

Every tool call passes through fx’s permission runtime. File listing, globbing, searching, and reads inside the workspace do not need approval. File changes, command execution, opening files, skill installation, vision, and access outside the workspace are governed by permission policy.

fx has three permission modes:

Change the mode in an interactive session:

/permissions ask
/permissions auto
/permissions yolo

Inspect the effective permission state from the command line:

fx permissions --json

auto is the default mode. Automatic review uses an additional AI Gateway request for an unresolved sensitive action. Persistent allow and deny rules can settle known actions before automatic review runs.

Manage persistent rules with /allowlist:

/allowlist view effective
/allowlist local add command "zig build test"
/allowlist user add tool read_file
/allowlist local remove command "zig build test"
/allowlist local reset all

Rules can live at user level or inside the private workspace profile in ~/.fx/settings.json. Repository .fx.json files cannot define permission rules.

Command sandboxing is a second control that applies after a command receives permission. os uses fx’s native operating-system sandbox on supported hosts. The current native OS sandbox is available on macOS. none adds no fx command isolation. auto selects the OS sandbox when the host supports it.

Inspect or change command sandboxing inside fx with:

/sandbox

Project Instructions with AGENTS.md

fx reads AGENTS.md files as repository guidance. This is where a project can record conventions such as build commands, testing rules, directory-specific requirements, or coding guidelines.

A global file can live at:

~/.fx/AGENTS.md

A repository can define its own AGENTS.md, and nested directories can define narrower instructions for files inside their scope.

Example:

project/
├── AGENTS.md
├── apps/
│   └── web/
│       ├── AGENTS.md
│       └── src/
└── packages/

Configure fx with .fx.json

Repository-safe configuration lives in .fx.json. The project file controls runtime behavior that can be shared with the repository.

{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072,
  "context": true,
  "sandbox": "os"
}

Work Across Additional Directories

A session has one primary workspace and can also access saved additional directories.

fx workspace list
fx workspace add ../shared
fx workspace remove ../shared
fx workspace clear

The same operations are available inside fx:

/workspace list
/workspace add ../shared
/workspace remove ../shared
/workspace clear

For a process-only directory:

fx --add-dir ../shared

Ignore saved additional directories for one run:

fx --no-additional-dirs

Context Limits

fx applies byte limits to several sources before they enter model context, including project instructions, skill metadata, MCP descriptions and schemas, and image-adapter output.

Override one context limit for the current process with:

fx --context-limit skill_catalog_bytes=32768

Extend fx with Skills

An fx skill is a directory containing SKILL.md. fx discovers skill metadata at startup and loads the full instructions when the skill is invoked.

Open the skill catalog:

/skills

Inspect a skill:

/skills show <name>

Install one skill from a repository:

/skills install vercel-labs/agent-skills --skill find-skills

Install from a local directory:

/skills add ./my-skills --skill my-tool

Create and remove fx-managed skills:

/skills create my-skill
/skills remove my-skill
/skills path

fx discovers skills from several compatible project and user locations, including skills/, .opencode/skills/, .codex/skills/, .claude/skills/, .agents/skills/, .claw/skills/, and their corresponding user-level directories. Managed fx skills live under ~/.fx/skills/.

Read More: Most Popular Agent Skills on GitHub for Coding Agents

Connect MCP Servers

fx works as an MCP client. Configured servers are available to interactive sessions, fx ask, ACP sessions, and authorized subagents.

Native fx reads its trusted MCP profile from:

~/.fx/mcp.json

Add a local stdio server:

/mcp add local-tools npx -y @modelcontextprotocol/server-everything

A manual local configuration can look like this:

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": ["node", "/absolute/path/to/server.js", "--read-only"]
    }
  }
}

Remote Streamable HTTP servers use "type": "http" and a URL. Protected remote servers can use environment-backed headers, bearer tokens, or OAuth configuration.

The current MCP management commands are:

/mcp list
/mcp resource list <server>
/mcp resource templates <server>
/mcp resource read <server> <uri>
/mcp resource complete <server> <uri-template> <variable> [value]
/mcp prompt list <server>
/mcp prompt get <server> <name> [arguments-json]
/mcp prompt complete <server> <name> <argument> [value]
/mcp add <name> <command> [args...]
/mcp remove <name>
/mcp reload
/mcp auth <name> --open
/mcp logout <name>
/mcp path

MCP tool schemas are loaded lazily. fx searches the available catalog, selects the relevant tool, and loads the selected schema into context. Dynamic MCP calls use the same permission policy as built-in tools.

Read More: Discover Popular MCP Servers

Delegate Work to Subagents

A subagent is a child fx session controlled by another agent. Each child has its own model, reasoning effort, permission mode, transcript, and lifecycle.

fx has two child modes:

• a one-off child runs one assignment and finishes;
• a persistent child returns to an idle state and can receive more instructions later.

Press ctrl+x inside an interactive session to open the subagent manager. From there you can inspect the child tree, create persistent children, send follow-up instructions, change child settings, attach an existing session, or manage a child’s lifecycle.

The internal subagent tool exposes six operations:

Built-In Agent Tools

The native runtime includes tools for files, repository search, commands, web access, images, skills, subagents, MCP, and runtime interaction.

Work with Images

Attach an image inside the interactive shell with:

/image ./diagram.png

/img is an alias. /images inspects or clears pending attachments. On supported macOS setups, /paste attaches an image from the clipboard.

A headless request can attach an image with:

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

fx accepts PNG, JPEG, GIF, and WebP images up to 20 MiB each. A selected model with compatible image input receives the attachment as part of the model request. fx can use its vision fallback for other supported workflows.

Connect fx to Editors with ACP

Run the native agent as an Agent Client Protocol server:

cd /absolute/path/to/project
fx acp

An ACP client launches the process and communicates with fx over stdin and stdout. The native runtime supplies the agent behavior, project tools, configuration, permissions, sessions, and project instructions.

A simple client configuration can point to the executable:

{
  "command": "/absolute/path/to/fx",
  "args": ["acp"]
}

Embed fx in JavaScript with WebAssembly

The experimental WebAssembly SDK exposes two main APIs:

A minimal headless setup looks like this:

import { createFxAgent, supportsJspi } from './fx-sdk.js'
if (!supportsJspi()) {
  throw new Error('fx requires JSPI support')
}
const agent = await createFxAgent({
  wasm: './fx-core.wasm',
  env: {
    AI_GATEWAY_API_KEY: 'your_ai_gateway_api_key_here',
  },
})
const session = await agent.createSession()
const turn = session.prompt('Explain this project')
for await (const update of turn) {
  if (update.sessionUpdate === 'agent_message_chunk') {
    console.log(update.content.text)
  }
}
await agent.close()

WebAssembly Runtime Limits

The WebAssembly build has a smaller capability set than native fx. It does not include native processes, OS sandboxing, Keychain access, arbitrary WASI filesystem access, native MCP, subagents, skills, web search, auto-upgrade, clipboard integration, or the native tool suite. A host application can supply selected capabilities such as command execution through its own adapters.

fx CLI Command Reference

Run and Agent Commands

fx pr and fx issue require a Git repository. Publishing with --create requires the GitHub CLI.

Sessions and Local Records

Account and Configuration

Diagnostics and Maintenance

The following commands accept --json for machine-readable output:

ask
status
doctor
permissions
models
workspace
session
sessions
background
usage
credits
replay
upgrade

Global CLI Flags

Useful fx ask Options

fx Slash Command Reference

Type / inside the interactive shell to search the current command catalog.

Sessions and Shell

Account, Model, and Runtime

Inspection and Settings

Tools and Local Data

Keyboard Shortcuts

Pros

• Small native Zig runtime with a terminal-first design.
• Interactive sessions, headless automation, ACP, and WebAssembly embedding share one project.
• Saved sessions include resume, recovery, migration, and context compaction.
• Skills, MCP, project instructions, additional workspaces, and subagents provide several extension paths.
• Permission rules and command sandbox controls can be tuned per user and workspace.

Cons

• Native installation currently works on macOS and Linux.
• Hosted inference requires AI Gateway access and incurs model-provider usage costs.

Alternatives & Related Resources

• 10 Best CLI AI Coding Agents: Open-Source & Commercial
• DeepSeek Harness: Open-Source Plugin-Based AI Agent Harness
• Grok Build: SpaceXAI’s Open-source Terminal AI Coding Agent
• SmallCode: Fast, Free, Local AI Coding Agent for Small LLMs
• Waku: Run Claude Code, Codex & More in One Native App

FAQs

Can fx keep a coding session across terminal restarts?

Yes. Interactive sessions are saved under ~/.fx/sessions/. Use fx sessions to find saved work and fx resume last or fx resume <session-id> to continue it. Resumed sessions restore the conversation context and session state available to fx.

What happens when an fx session becomes too long for efficient model context?

fx compacts older conversation turns after the session reaches its automatic compaction threshold. Recent turns stay verbatim and older work becomes a condensed context record. The saved transcript is not deleted. /compact can trigger compaction before a new phase of work.

Can a repository silently register an MCP server or change my model?

Native MCP servers come from the trusted ~/.fx/mcp.json profile. Project .fx.json files cannot register MCP servers, set the model, set reasoning effort, or define permission rules. Repository files can define supported project runtime settings and AGENTS.md instructions.

Does yolo mode permanently disable my permission settings?

No. yolo changes the effective authority for the current run. It disables fx permission checks and uses no fx command sandbox for that process. It does not rewrite the saved sandbox setting.

Can fx run with local inference?

Yes. fx can use compatible loopback endpoints for model discovery and generation. For a hermetic setup, block outbound networking and avoid networked tools. Prompts and model context then stay on the local machine.