AgentGo README

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 <name or folder> 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 <password>

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 <path> 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.

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:

Using it as a library

npm install agentgo-mcp

connectAgent gives you a typed client for a running AgentGo server:

import { connectAgent } from 'agentgo-mcp';

const agent = await connectAgent({
  mcpConnectionURL: process.env.AGENTGO_URL!,
  token: process.env.AGENTGO_PASSWORD!,
});

try {
  const run = await agent.startAgentRun({
    provider: 'codex',
    model: 'gpt-6.1-sol',
    effort: 'high',
    workspaceId: 'my-app',
    prompt: 'Fix the failing tests and explain what was wrong.',
    idempotencyKey: 'fix-tests-1',
  });

  let status = await agent.getAgentRunStatus(run.taskId);
  while (status.pollAfterMs) {
    await new Promise(resolve => setTimeout(resolve, status.pollAfterMs!));
    status = await agent.getAgentRunStatus(run.taskId);
  }

  const output = await agent.getAgentRunOutput(run.taskId);
  console.log(status.status, output.result?.text);
} finally {
  await agent.close();
}

The URL must be HTTPS, except on localhost. Every tool is also available as agent.call(name, args). To connect over stdio instead, pass { transport: new StdioClientTransport({ command: 'agentgo', args: ['stdio'] }) }, importing StdioClientTransport from @modelcontextprotocol/client/stdio.

The package also exports the pieces the CLI is built from:

• start, stop, status and restart do what the commands do. start({ downloadCloudflared: true }) returns the MCP URL and token.
• serveAgentStdio({ stateDir }) serves over stdio from your own process.
• AgentService.create({ stateDir }) loads the workspaces and run history. createAgentMcpServer(service) wraps it in an MCP server you can connect your own transport to, and createAgentHttpServer({ service, token }) serves it over HTTP on 127.0.0.1 with password checks.

Working on AgentGo

From a clone of this repo:

npm install
npm test
npm run typecheck

npm test builds first. The tests use fake codex, claude and cloudflared programs, so they don't spend money or touch Cloudflare. They need rg on your PATH.

There are also smoke tests against the real things:

npm run smoke:providers -- codex
npm run smoke:providers -- claude
npm run smoke:tunnel

smoke:providers runs two short real turns in a temporary folder, checking that the agent can edit a file and remember the conversation. It uses your normal Codex or Claude usage. smoke:tunnel starts a real Quick Tunnel and checks that an authenticated client can reach AgentGo through it, without running an agent. Add -- --yes to let it download cloudflared.

Publishing a release

AgentGo is published to npm as agentgo-mcp and listed in the MCP Registry through server.json. You'll need to be logged in to npm (npm login) and to the registry (mcp-publisher login github, using the official mcp-publisher CLI).

First set both version fields in server.json to the version you're about to release. Then, from the repo root:

git add -A && git commit -m "Describe the release"
npm version minor          # or patch; must match the version in server.json
git push --follow-tags
npm publish
npm view agentgo-mcp@<version> version   # wait until this shows up
mcp-publisher publish

npm pack --dry-run shows what will go into the package before you publish. npm publish builds the package first.

After npm publish succeeds, npm can take a few minutes to list the new version. Don't publish again while you wait; npm rejects a second upload of the same version. mcp-publisher publish fails with "version not found" if you run it before the version shows up, so wait for npm view to show it.

Codex and Claude Code terms

AgentGo isn't made by or affiliated with OpenAI or Anthropic. It runs the codex and claude programs you installed, unmodified, and they use the sign-in you already set up. AgentGo never handles or stores those logins.

Your OpenAI and Anthropic terms still apply to everything the agents do, so:

• Keep it for yourself. Giving someone else your AgentGo password lets them use your Codex and Claude accounts, which both companies' terms forbid.
• Subscriptions are for ordinary, individual use. If you're going to run agents heavily or unattended, sign the CLIs in with an API key instead.

License

MIT. Parts of the Cloudflare hosting, storage and HTTP code are adapted from PrintGo; see NOTICE.