Vercel fx is an open-source AI coding agent from Vercel Labs, built in Zig as a native command-line tool.
Run it in a repository to investigate code, edit files, execute tests, and work through coding tasks.
The conversation prints into your terminal scrollback, where you can search previous commands and results.
Last Updated: Nov 17, 2026
Key Features
- Runs as a native executable on macOS and Linux.
- Reads and edits files, runs shell commands, searches the web, and analyzes images.
- Saves coding sessions that you can resume, fork, and compact.
- Delegates tasks to subagents and runs multiple interactive sessions in one window.
- Connects to Vercel AI Gateway, ChatGPT and Grok subscriptions, and custom model endpoints.
- Uses
AGENTS.md, Agent Skills, and MCP servers for project instructions and additional tools. - Runs coding tasks through
fx askand connects editors through ACP. - Embeds the agent core in Node.js or browser applications with
libfx.
How to Use fx
fx CLI Quick Reference
| Task | Command |
|---|---|
| Start an interactive session | fx |
| Run a one-off coding task | fx ask "<prompt>" |
| Return a JSON result | fx ask --json "<prompt>" |
| Continue the current project | fx -c |
| Choose a saved session | fx -r |
| List saved sessions | fx sessions |
| See active agents | fx sessions --live |
| Sign in | fx login |
| Choose a model | fx models |
| Check provider usage | fx usage --period 7d |
| Check AI Gateway credits | fx credits |
| View permissions | fx permissions |
| Manage MCP servers | fx mcp list |
| Inspect settings | fx config list |
| Check the installation | fx doctor |
| Draft a pull request | fx pr |
| Draft a GitHub issue | fx issue |
| Connect an ACP editor | fx acp |
| Upgrade fx | fx upgrade |
Install fx and connect a model
Install the native CLI on macOS 15 or later or Linux, on either x86_64 or arm64. The installer writes the executable to ~/.local/bin by default.
curl -fsSL https://fx.sh/setup.sh | bashSign in with fx login for Vercel AI Gateway, fx login codex for a ChatGPT subscription, or fx login grok for a Grok subscription. For an AI Gateway API key, run fx login vercel --api-key.
To build from source, install Zig and run these commands.
git clone https://github.com/vercel-labs/fx.git
cd fx
zig build
./zig-out/bin/fx --versionWork on a repository
Open your project and launch fx:
cd your-project
fxDescribe a concrete change in the prompt, for example: “Find why the login test fails, fix the error, and run the affected tests.” fx inspects the repository and shows file changes, commands, and results in the conversation. For visual issues, attach an image with /image ./ui.png.
Run one-off tasks in scripts or CI
fx ask "explain the uncommitted changes"
fx ask --json "summarize failing tests" | jq -r .final_outputFor CI, add AI_GATEWAY_API_KEY as a secret in your runner and invoke fx ask from the checked-out repository.
Resume Sessions and Delegate Work
Continue or fork a conversation
Reopen the conversation for your current project with fx -c, or use fx -r to choose another saved session. fx stores prompts, tool calls, and terminal results. An interrupted turn can continue after the terminal closes.
Use /fork to return to an earlier prompt and try another solution in a new conversation. For long sessions, /compact summarizes older context while retaining the transcript on disk.
Run subagents and multiple instances
Delegate a focused task from the main conversation, such as reviewing tests while you work on a parser fix. Open the agent list with Ctrl+X to inspect a subagent, answer questions, or give it further instructions.
For recurring roles, create an agent profile. Save this reviewer configuration as ~/.fx/agents/reviewer/profile.json:
{
"description": "Review source changes",
"tools": ["read_file", "glob_files", "grep_files"],
"mcp_servers": [],
"effort": "high"
}Ask fx to use the reviewer profile for a subagent, or launch an interactive session with fx --profile reviewer. For several conversations in one terminal window, run fx --instances 3 or enter /launch inside fx. Switch between them with Ctrl+X.
Models, Permissions, and Extensions
Select a model and control permissions
Use /model to switch among models from your connected provider, and /effort to change reasoning effort. If your Vercel team has Token Pass, featured models use the team’s Token Pass credit. Run fx credits to check the balance.
Set the permission mode to match the work you want fx to perform:
| Mode | Behavior |
|---|---|
ask | Confirm every tool action |
auto | Run routine work and review other actions |
full-access | Run without fx permission checks |
Change modes with /permissions or Shift+Tab. full-access disables fx’s permission checks for file and command operations.
Use your own model endpoint
To connect a local Ollama server or another API that speaks OpenAI Chat Completions, define the connection in ~/.fx/settings.json. For example, with Ollama serving qwen2.5:1.5b at localhost:11434:
{
"provider": "local",
"providers": {
"local": {
"protocol": "openai-chat-completions",
"base_url": "http://localhost:11434/v1",
"auth": { "type": "none" },
"model_metadata": {
"qwen2.5:1.5b": {
"context_window": 32768,
"max_output_tokens": 2048,
"supports_tool_use": true
}
}
}
},
"models": { "local": "qwen2.5:1.5b" }
}Start Ollama with a 32K context window, pull that model, and run fx provider local. The model ID and context size in the configuration must match the model served by Ollama.
Add instructions, skills, and MCP servers
Put coding conventions and test commands in your repository’s AGENTS.md. Add an AGENTS.md inside a subdirectory for instructions specific to that part of the codebase. Project settings belong in .fx.json; use fx workspace add ../shared when work also needs a neighboring directory.
Agent Skills load task instructions from SKILL.md files. Browse them with /skills. To connect an MCP service, run a command such as /mcp add slack, complete sign-in, and ask fx to use the service during a task.
Built-In Agent Tools
| Task | Tool |
|---|---|
| Find and read files | glob_files, grep_files, read_file |
| Create and edit files | write_file, edit_file |
| Run shell commands | shell |
| Search or fetch web pages | web_search, web_fetch |
| Analyze images | vision |
| Delegate work | subagent |
| Find skills and MCP tools | toolbox |
| Ask for input | ask_user_question |
| Retrieve earlier output | read_tool_result |
Use fx in Editors and JavaScript Apps
Connect your editor through ACP
Run fx acp and configure it as an Agent Client Protocol server in your editor. The editor sends coding requests to fx with the project’s models, instructions, and tools.
Embed the agent with libfx
Install libfx to run the agent from JavaScript. Browser builds run with WebAssembly. For the following Node.js example, set AI_GATEWAY_API_KEY in your environment and install the package:
npm install libfx
export AI_GATEWAY_API_KEY="your-api-key"Save this as agent.mjs and run it with node agent.mjs:
import { createFxAgent } from 'libfx'
const agent = createFxAgent()
const turn = agent.session().prompt('Explain this project structure.')
for await (const event of turn) {
if (event.type === 'text_delta') process.stdout.write(event.delta)
}
const { sessionId } = await turn.accepted
console.log(`\nSession: ${sessionId}`)
await agent.close()The session ID identifies the saved conversation. Open it in another process with agent.session(sessionId) and send the next prompt. Add JavaScript tools through the agent configuration, or use createFxTerminal() to embed a terminal UI.
Save and resume libfx sessions on a server
By default, Node.js stores libfx sessions in a local temporary directory. To choose a persistent directory, import local from libfx/durable-local and initialize the agent with createFxAgent({ durability: local({ dir: ".fx/sessions" }) }). Store the resulting session ID in your application to continue the conversation after a restart.
On Vercel, libfx stores session steps in Vercel World and uses a queue to continue interrupted work. Create the agent in lib/agent.js and the wake-up route in app/api/libfx/route.js:
// lib/agent.js
import { createFxAgent } from 'libfx'
export const agent = createFxAgent({ name: 'coding' })
// app/api/libfx/route.js
import { agent } from '@/lib/agent'
export const POST = agent.wakeHandler()Subscribe that route to the session queue in vercel.json:
{
"functions": {
"app/api/libfx/route.js": {
"experimentalTriggers": [{
"type": "queue/v2beta",
"topic": "__libfx_wkf_workflow_session",
"retryAfterSeconds": 5
}]
}
}
}In your Next.js server code, run const turn = agent.session().prompt("Review the change") and store the session ID returned by await turn.accepted. The queue calls the route when saved work needs another process. libfx resumes the recorded turn from the last completed step. Vercel deployments authenticate with AI Gateway through the deployment’s OIDC token. For custom tools in durable agents, set idempotent: true for operations safe to repeat and idempotent: false for operations that must not run twice.
Interactive Commands and Keyboard Shortcuts
Useful Interactive Commands
| Command | Action |
|---|---|
/help | Find commands and keyboard help |
/new | Start a new conversation |
/reset | Start fresh and stop background processes |
/resume | Pick a saved conversation |
/fork | Branch from an earlier prompt |
/rename <title> | Rename the conversation |
/compact | Summarize older context |
/agents | Find and switch active agents |
/launch [profile] | Open another fx instance |
/close | Close the visible instance |
/model | Select a model |
/effort | Change reasoning effort |
/fast | Toggle Fast mode |
/permissions | Inspect or change permissions |
/status | View session and configuration |
/usage | View provider usage |
/credits | Check AI Gateway credit |
/image <path> | Attach an image file |
/workspace | Manage extra directories |
/skills | Manage Agent Skills |
/mcp | Manage MCP servers |
/undo | Undo the last tracked file edit |
/trace | Save diagnostic trace |
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Shift+Enter / Ctrl+J | Insert a new line |
Enter while working | Send a steering instruction |
Ctrl+O | Open full output details |
Ctrl+X | Switch agents or instances |
Ctrl+P | Open model picker |
Ctrl+T | Cycle reasoning effort |
Shift+Tab | Cycle permission mode |
Down on empty prompt | Open the agent list |
@ | Attach a repository file or folder |
$ | Find a skill |
Esc twice while running | Interrupt a running request |
Ctrl+C twice | Exit fx |
Ctrl+G | Reload when an update is ready |
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
- Most Popular Agent Skills on GitHub for Coding Agents
- Discover Popular MCP Servers
- Official libfx durability reference
FAQs
Is Vercel fx free to use?
The fx CLI is open source under Apache 2.0. Model usage follows the pricing or access conditions of the provider you connect, including AI Gateway, ChatGPT, or Grok.
Does fx upload an entire repository to the model provider?
fx sends your prompt, file contents read during the task, relevant tool output, and conversation history. Files outside that request are not sent to the model provider.
Does fx run natively on Windows?
The official native CLI builds target macOS and Linux on x86_64 and arm64. There is no native Windows release.
Can I run a task without saving a conversation?
Run fx ask --no-save "your task" to skip the local session record.










