AgentGo

AgentGo

AgentGo lets an AI assistant run Codex and Claude Code on your computer. It's an MCP server: once your MCP client is connected to it, the assistant can look around the projects you've allowed, hand a coding task to Codex or Claude Code, check on it while it works, and read the result.

AgentGo runs on the computer where your code and your logged-in codex and claude CLIs live, and puts itself behind a Cloudflare tunnel, so the assistant can reach it from anywhere: a cloud agent, your phone, or another laptop.

Read this first. The agents run as you, with your files, your logins and your git credentials, and they approve their own actions. Anyone who has the AgentGo password can make them do anything they'd do for you. Only give the password to clients you'd trust at your keyboard, and only add projects you'd let an agent loose on.

Why I built it

I got sick of Codex's remote connection and remote device setup. I never got it working reliably, and when it did work it was too slow. AgentGo is my answer to that.

What you need

• macOS or Linux, with Node.js 24.13 or newer. AgentGo uses Node's built-in SQLite, which still prints an "experimental" warning.
• codex, claude, or both, installed and logged in. AgentGo uses your existing logins and never asks for API keys. It's tested with Codex 0.160.1 and Claude Code 2.1.291.
• ripgrep (rg) on your PATH, for the file search tools. On macOS: brew install ripgrep.
• cloudflared for the tunnel. If you don't have it, AgentGo can download it for you (see below).
• An MCP client that supports the Streamable HTTP transport and lets you set an Authorization header.

Getting started

Install the CLI and check that everything it needs is there:

npm install -g agentgo-mcp

agentgo doctor

This installs two commands, agentgo and agentgo-mcp. They're the same thing; this README uses agentgo.

doctor shows whether codex, claude, rg and cloudflared are installed and whether you're logged in to each agent.

Next, tell AgentGo where your projects are. Point it at the folder they live in, and every folder inside it becomes a *workspace* that agents can work in:

agentgo workspace add-folder ~/code

Each workspace is named after its folder, so ~/code/my-app becomes my-app (spaces and other odd characters turn into dashes). Projects you create later show up on their own, and hidden folders are skipped. To add a single project that lives somewhere else, give it a name yourself:

agentgo workspace add notes ~/Documents/notes

agentgo workspace list shows what agents can see, and agentgo workspace remove takes something away. Changes apply straight away, even while the server is running.

Then start the server:

agentgo start

This starts AgentGo in the background along with a Cloudflare tunnel, then prints an MCP URL and the header to send with it:

MCP URL:       https://<random-words>.trycloudflare.com/mcp

Header name: Authorization Header value: Bearer

Add both to your MCP client. Include the word Bearer and the space after it.

The password is created the first time you run start and reused after that. Running start again while the server is up just prints it again. To replace it, run agentgo token rotate; the old one stops working straight away.

If cloudflared isn't installed, start stops and tells you. Install it yourself (brew install cloudflared on macOS), or run agentgo start --yes to let AgentGo download the official release from GitHub and check it against its published checksum. Pass --cloudflared if yours is somewhere unusual.

Managing the server

agentgo status

agentgo stop agentgo restart

You don't need to restart after changing workspaces, models or settings; the server picks up changes on the next request. Stopping the server interrupts any runs in progress. Edits they already made stay, but nothing is undone or resumed automatically.

If the server won't start, its log is at ~/.agentgo/daemon.log.

Add --json to any command if you're calling it from a script. The password is in the token field.

A stable address

By default you get a Cloudflare Quick Tunnel. It needs no Cloudflare account, but its URL changes every time the tunnel starts or reconnects. If you have a domain on Cloudflare, you can use a fixed address instead:

agentgo stop

agentgo start --custom-domain-with-cf agents.example.com

If cloudflared isn't logged in to your Cloudflare account yet, this opens a browser so you can log in. AgentGo then creates a tunnel in your account (or reuses the one it made before) and adds a DNS record for the hostname. It won't overwrite a DNS record that already exists.

If you'd rather manage the tunnel in the Cloudflare dashboard, point its public hostname at http://127.0.0.1:8765, save the tunnel token to a file, and run:

agentgo start --tunnel-token-file ~/tunnel-token --hostname agents.example.com --port 8765

start remembers how it was last started, so later start and restart calls reuse the same tunnel. Pass --quick to go back to a Quick Tunnel, or --local to listen on 127.0.0.1 with no tunnel at all.

If the tunnel drops, AgentGo reconnects it in the background. Runs in progress aren't affected.

Local only, over stdio

If your MCP client runs on the same computer, it can launch AgentGo directly instead:

{

"mcpServers": { "agentgo": { "command": "agentgo", "args": ["stdio"] } } }

There's no tunnel or password in this mode. Runs only last as long as the client keeps AgentGo open: when the client disconnects, runs in progress are interrupted.

The stdio server and the background server can't use the same state directory at the same time. Either stop the background server first, or give the stdio one its own directory with "args": ["stdio", "--state-dir", "/path"] and add workspaces to it with the same --state-dir.

What the assistant can do

AgentGo gives the assistant 13 tools.

Finding its way around. These read files directly. They don't start an agent.

Running agents.

A run started by the assistant looks like this:

{

"provider": "codex", "model": "gpt-6.1-sol", "effort": "high", "serviceTier": "priority", "workspaceId": "my-app", "prompt": "Fix the failing tests and explain what was wrong.", "idempotencyKey": "fix-tests-1" }

It returns straight away with a taskId and a sessionId. The assistant then polls getAgentRunStatus and reads the result with getAgentRunOutput. To follow up, it calls continueAgentSession with the sessionId and a new prompt.

A few things worth knowing:

• Agents approve their own actions. Codex runs with its workspace-write sandbox and its automatic reviewer (auto_review). Claude Code runs in auto mode with permission prompts turned off. Their reviewers can still refuse an action. Nobody is there to answer questions mid-run, so if Codex asks for input, the run fails with INPUT_REQUIRED. There's no option to bypass permissions entirely.
• The browsing tools are limited; the agents aren't. readFile, grepFiles and the rest stay inside the workspace, don't follow symlinks, and refuse secrets such as .env, .ssh, .aws, .git, .npmrc and private keys. Agents are only held back by their own sandbox and reviewer, so they can read and run whatever those allow.
• Search skips dependencies and build output. globFiles and grepFiles search one workspace at a time, up to 100,000 files. They follow .gitignore, skip hidden files, and skip folders such as node_modules, vendor, dist, build, target, .venv and __pycache__ wherever they appear. listDirectory and readFile can still open those.
• Models aren't guessed. The assistant should call getSupportedModels first. Codex reports its own list. For Claude, AgentGo starts with the sonnet and opus aliases at low, medium and high effort; add others with agentgo model add claude-sonnet-5-5 --efforts low,medium,high,xhigh,max. An unknown model, effort or tier is an error, never silently swapped. Leave out serviceTier for Claude.
• Up to five runs at once. They can be in different workspaces or the same one. Agents in the same workspace don't know about each other, so give parallel runs separate parts of the code. Extra runs wait in a queue.
• Retries won't start a second run. Each run carries an idempotencyKey. If the assistant retries with the same key and arguments, it gets the original run back. Reusing a key with different arguments is an error.
• Runs have a time limit. 30 minutes unless the assistant asks for longer with limits.wallTimeSeconds, up to an hour by default.
• `succeeded` means the agent finished. It doesn't mean the tests pass or the change is right.
• The assistant sees what the agent shows. Run output includes the agent's messages and the tools it used. For Codex it also includes the commands it ran, their output, and the files it changed. Hidden reasoning isn't included. If an agent prints a secret it read, that will be in the output too.

Where AgentGo keeps its state

Everything lives in ~/.agentgo: your workspaces and settings, the password, tunnel settings, run history, the server log, and cloudflared if AgentGo downloaded it. Use --state-dir or the AGENTGO_HOME environment variable to put it somewhere else. Workspaces can't be inside it, or contain it.

Run history is kept for 30 days. After that, prompts and output are deleted, but a small record of each run stays so a very late retry still can't start it again. Codex and Claude Code keep their own conversation history separately, and AgentGo doesn't touch it.

If the server stops unexpectedly, runs that were in progress are marked interrupted when it next starts. They're never re-run automatically; check the workspace for half-finished changes and continue the session yourself if you want.

Agents don't inherit your whole environment. They get PATH, HOME, locale, proxy settings, and the variables Codex and Claude Code use to log in (OPENAI_*, ANTHROPIC_*, and the AWS, Google and Azure ones). The AgentGo password is never passed to them.

agentgo config show prints the current settings. You can change these in ~/.agentgo/config.json:

| searchExclude | node_modules, dist, … | Folder