AgentGo

AgentGo

AgentGo を使うと、AI アシスタントからお使いのコンピューター上で Codex と Claude Code を実行できます。AgentGo は MCP サーバーです。MCP クライアントを接続すると、アシスタントは許可されたプロジェクトを確認し、コーディングタスクを Codex または Claude Code に任せ、作業中の状況を確認し、結果を読み取ることができます。

AgentGo は、コードとログイン済みの codex および claude の CLI があるコンピューター上で動作し、Cloudflare トンネルの背後に配置されるため、クラウドエージェント、スマートフォン、別のノートパソコンなど、どこからでもアシスタントがアクセスできます。

最初にお読みください。 エージェントは、お使いのファイル、ログイン情報、Git 認証情報を使って、ユーザー本人として動作し、自身のアクションを承認します。AgentGo のパスワードを知っている人は、エージェントにユーザーの代わりにできることを何でもさせられます。キーボードの前にいるときと同じように信頼できるクライアントにだけパスワードを渡し、エージェントに自由に操作させてもよいプロジェクトだけを追加してください。

作成した理由

Codex のリモート接続とリモートデバイスのセットアップにうんざりしていました。安定して動作させることができず、動作したとしても遅すぎました。AgentGo はその解決策として作りました。

必要なもの

• Node.js 24.13 以降を搭載した macOS または Linux。AgentGo は Node.js に組み込まれた SQLite を使用します。これは引き続き「experimental」という警告を表示します。
• インストールおよびログイン済みの codex、claude、またはその両方。AgentGo は既存のログイン情報を使用し、API キーを求めることはありません。Codex 0.160.1 および Claude Code 2.1.291 でテスト済みです。
• ファイル検索ツール用に、PATH 上にある ripgrep（rg）。macOS の場合：brew install ripgrep。
• トンネル用の cloudflared。インストールされていない場合、AgentGo がダウンロードできます（詳細は後述）。
• Streamable HTTP トランスポートに対応し、Authorization ヘッダーを設定できる MCP クライアント。

はじめに

CLI をインストールし、必要なものがすべてそろっていることを確認します。

npm install -g agentgo-mcp
agentgo doctor

これにより、agentgo と agentgo-mcp の2つのコマンドがインストールされます。どちらも同じものです。この README では agentgo を使用します。

doctor は、codex、claude、rg、cloudflared がインストールされているか、また各エージェントにログインしているかを表示します。

次に、AgentGo にプロジェクトの場所を伝えます。プロジェクトが保存されているフォルダーを指定すると、その中の各フォルダーがエージェントの作業対象となる ワークスペース になります。

agentgo workspace add-folder ~/code

各ワークスペースにはフォルダー名が付けられるため、~/code/my-app は my-app になります（スペースなどの特殊な文字はハイフンに置き換えられます）。後から作成したプロジェクトは自動的に表示され、隠しフォルダーはスキップされます。別の場所にある単一のプロジェクトを追加するには、名前を指定します。

agentgo workspace add notes ~/Documents/notes

agentgo workspace list でエージェントから見えるものを確認でき、agentgo workspace remove <name or folder> でワークスペースを削除できます。サーバーの実行中でも、変更はすぐに反映されます。

続いて、サーバーを起動します。

agentgo start

これにより、AgentGo と Cloudflare トンネルがバックグラウンドで起動し、MCP URL と、それと一緒に送信するヘッダーが表示されます。

MCP URL:       https://<random-words>.trycloudflare.com/mcp
Header name:   Authorization
Header value:  Bearer <password>

両方を MCP クライアントに追加します。Bearer という語と、その後のスペースも含めてください。

パスワードは初回の start 実行時に作成され、その後も再利用されます。サーバーの稼働中に start を再実行すると、パスワードが再表示されます。パスワードを置き換えるには、agentgo token rotate を実行します。古いパスワードはすぐに使えなくなります。

cloudflared がインストールされていない場合、start は停止し、そのことを通知します。自分でインストールする（macOS の場合は brew install cloudflared）か、agentgo start --yes を実行すると、AgentGo が GitHub から公式リリースをダウンロードし、公開済みのチェックサムと照合します。通常とは異なる場所にインストールされている場合は、--cloudflared <path> を渡してください。

サーバーの管理

agentgo status
agentgo stop
agentgo restart

ワークスペース、モデル、設定を変更した後に再起動する必要はありません。サーバーは次のリクエスト時に変更を反映します。サーバーを停止すると、進行中の実行は中断されます。すでに行われた編集はそのまま残りますが、自動で取り消されたり再開されたりすることはありません。

サーバーが起動しない場合、ログは ~/.agentgo/daemon.log にあります。

スクリプトからコマンドを呼び出す場合は、任意のコマンドに --json を追加してください。パスワードは token フィールドにあります。

固定アドレス

デフォルトでは、Cloudflare Quick Tunnel が使用されます。Cloudflare アカウントは不要ですが、トンネルを開始または再接続するたびに URL が変わります。Cloudflare にドメインをお持ちの場合は、代わりに固定アドレスを使用できます。

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

cloudflared がまだ Cloudflare アカウントにログインしていない場合は、ログインできるようにブラウザーが開きます。その後、AgentGo はアカウントにトンネルを作成するか（または以前に作成したトンネルを再利用し）、ホスト名の DNS レコードを追加します。既存の DNS レコードが上書きされることはありません。

Cloudflare ダッシュボードでトンネルを管理する場合は、パブリックホスト名を http://127.0.0.1:8765 に設定し、トンネルトークンをファイルに保存して、次を実行してください。

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

start は前回の起動方法を記憶するため、以降の start と restart では同じトンネルが再利用されます。Quick Tunnel に戻すには --quick を、トンネルを使わずに 127.0.0.1 でリッスンするには --local を渡してください。

トンネルが切断されると、AgentGo はバックグラウンドで再接続します。進行中の実行には影響しません。

stdio を使ったローカル限定の接続

MCP クライアントが同じコンピューター上で動作している場合は、代わりに AgentGo を直接起動できます。

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

このモードでは、トンネルもパスワードも必要ありません。実行は、クライアントが AgentGo を起動したままにしている間だけ継続します。クライアントが切断すると、進行中の実行は中断されます。

stdio サーバーとバックグラウンドサーバーは、同じ状態ディレクトリを同時に使用できません。先にバックグラウンドサーバーを停止するか、"args": ["stdio", "--state-dir", "/path"] を指定して stdio サーバー専用のディレクトリを用意し、同じ --state-dir を指定してワークスペースを追加してください。

アシスタントにできること

AgentGo はアシスタントに 13 個のツールを提供します。

ファイルやフォルダーの確認。 これらのツールはファイルを直接読み取ります。エージェントは起動しません。

ツール	機能
listWorkspaces	追加したプロジェクトを一覧表示します
listDirectory	ディレクトリ内のファイルとフォルダーを一覧表示します
readFile	テキストファイルから行を読み取ります
globFiles	src/**/*.ts などの名前パターンでファイルを検索します
grepFiles	ripgrep でファイルの内容を検索します

エージェントの実行。

ツール	機能
getAgentCapabilities	インストールされているエージェントとそのバージョンを表示します
getSupportedModels	各エージェントが受け付けるモデル、推論の強度、サービス階層を一覧表示します
startAgentRun	ワークスペース内で Codex または Claude Code にタスクを与えます
getAgentRunStatus	実行が待機中、実行中、完了のどれかを確認します
getAgentRunOutput	エージェントの発言や実行内容、および最終回答を読み取ります
listAgentRuns	過去および現在の実行を一覧表示します
cancelAgentRun	実行を停止します
continueAgentSession	完了した実行に、同じ会話内で追加の指示を送ります

アシスタントが開始した実行は次のようになります。

{
  "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"
}

実行はすぐに taskId と sessionId を返します。その後、アシスタントは getAgentRunStatus をポーリングし、getAgentRunOutput で結果を読み取ります。追加の指示を送る場合は、sessionId と新しい プロンプトを指定して continueAgentSession を呼び出します。

知っておくとよい点をいくつか紹介します。

• エージェントは自らの操作を承認します。 Codex は workspace-write サンドボックスと自動レビュアー（auto_review）を使用して実行します。Claude Code は権限確認プロンプトを無効にした自動モードで実行します。レビュアーが操作を拒否する場合もあります。実行中に質問へ回答する人はいないため、Codex が入力を求めると、実行は INPUT_REQUIRED で失敗します。権限を完全に回避するオプションはありません。
• ファイル閲覧ツールには制限がありますが、エージェントにはありません。 readFile、 grepFiles などのツールはワークスペース内でのみ動作し、シンボリックリンクをたどらず、.env、.ssh、.aws、.git、.npmrc、秘密鍵などの機密情報へのアクセスを拒否します。エージェントを制限するのはそれぞれのサンドボックスとレビュアーだけであり、それらが許可するものは何でも読み取り、実行できます。
• 依存関係とビルド出力は検索対象から除外されます。 globFiles と grepFiles は一度に 1 つのワークスペースを検索し、ファイル数は最大 100,000 件です。.gitignore に従い、隠しファイルを除外し、node_modules、vendor、dist、build、target、.venv、__pycache__ などのフォルダーを、どこにあっても除外します。listDirectory と readFile では引き続きそれらを開けます。
• モデルは推測されません。 アシスタントはまず getSupportedModels を呼び出してください。Codex は独自の一覧を返します。Claude については、AgentGo は sonnet と opus のエイリアスを、低・中・高の推論の強度で使用できる状態から開始します。ほかのモデルは agentgo model add claude-sonnet-5-5 --efforts low,medium,high,xhigh,max で追加します。不明なモデル、推論の強度、サービス階層が指定された場合はエラーとなり、黙って別のものに置き換えられることはありません。Claude では serviceTier を省略してください。
• 同時に実行できるのは最大 5 件です。 異なるワークスペースでも、同じワークスペースでも実行できます。同じワークスペース内のエージェント同士は互いの存在を認識しないため、並行実行にはコードの別々の部分を割り当ててください。追加の実行はキューで待機します。
• 再試行で 2 件目の実行が始まることはありません。 各実行には idempotencyKey が付与されます。アシスタントが同じキーと引数で再試行すると、元の実行が返されます。異なる引数でキーを再利用するとエラーになります。
• 実行には時間制限があります。 デフォルトは 30 分です。アシスタントが limits.wallTimeSeconds で延長を求めた場合は、デフォルトで最大 1 時間まで延長できます。
• succeeded はエージェントの実行が完了したことを意味します。 テストの合格や変更の正しさを意味するものではありません。
• アシスタントに表示されるのは、エージェントが示した内容です。 実行出力にはエージェントのメッセージと、使用したツールが含まれます。Codex の場合は、実行したコマンドとその出力、変更したファイルも含まれます。非公開の推論は含まれません。 エージェントが読み取った機密情報を出力した場合、その内容も出力に含まれます。

AgentGo が状態を保存する場所

すべてのデータは ~/.agentgo に保存されます。ワークスペースや設定、パスワード、トンネル設定、実行履歴、サーバーログ、AgentGo がダウンロードした場合は cloudflared も含まれます。別の場所に保存するには、--state-dir または AGENTGO_HOME 環境変数を使います。ワークスペースをその中に置いたり、ワークスペースにその場所を含めたりすることはできません。

実行履歴は30日間保存されます。それ以降はプロンプトと出力が削除されますが、実行ごとの簡単な記録は残ります。そのため、かなり遅れて再試行しても、同じ実行が再び開始されることはありません。Codex と Claude Code は、それぞれ独自に会話履歴を保存します。AgentGo がその履歴に触れることはありません。

サーバーが予期せず停止した場合、進行中だった実行は次回の起動時に interrupted として記録されます。自動的に再実行されることはありません。変更が途中までになっていないかワークスペースを確認し、必要であれば自分でセッションを続けてください。

エージェントには、環境全体が引き継がれるわけではありません。PATH、HOME、ロケール、プロキシ設定、および Codex と Claude Code のログインに使われる環境変数（OPENAI_*、ANTHROPIC_*、AWS、Google、Azure 関連の環境変数）が渡されます。AgentGo のパスワードがエージェントに渡されることはありません。

agentgo config show を実行すると、現在の設定が表示されます。以下の設定は ~/.agentgo/config.json で変更できます。

設定	デフォルト	制御する内容
maxConcurrentRuns	5	同時に実行できる実行数（最大8）
maxQueuedRuns	100	キューで待機できる実行数
maxRunSeconds	3600	実行で指定できる最長時間
maxRunOutputBytes	10 MiB	停止するまでに実行が生成できる出力量
retentionDays	30	プロンプトと出力の保存期間
searchExclude	node_modules、dist、…	検索対象から除外するフォルダー名とファイル名（config show ですべて確認できます）
codexPath、claudePath、rgPath	codex、claude、rg	各プログラムの場所

ライブラリとして使う

npm install agentgo-mcp

connectAgent は、実行中の AgentGo サーバーに接続するための型付きクライアントを提供します。

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();
}

URL は localhost を除き、HTTPS である必要があります。すべてのツールは agent.call(name, args) からも利用できます。代わりに stdio 経由で接続するには、@modelcontextprotocol/client/stdio から StdioClientTransport をインポートし、{ transport: new StdioClientTransport({ command: 'agentgo', args: ['stdio'] }) } を渡します。

このパッケージは、CLI の構成要素もエクスポートします。

• start、stop、status、restart は、それぞれ対応するコマンドと同じ動作をします。 start({ downloadCloudflared: true }) は MCP URL と token を返します。
• serveAgentStdio({ stateDir }) は、独自のプロセスから stdio 経由でサービスを提供します。
• AgentService.create({ stateDir }) は、ワークスペースと実行履歴を読み込みます。 createAgentMcpServer(service) はこれを MCP サーバーでラップし、独自のトランスポートを接続できるようにします。また、createAgentHttpServer({ service, token }) は、パスワード認証を使って 127.0.0.1 上で HTTP 経由のサービスを提供します。

AgentGo の開発

このリポジトリをクローンした状態から：

npm install
npm test
npm run typecheck

npm test は最初にビルドを実行します。テストでは偽の codex、claude、cloudflared プログラムを使うため、費用が発生したり Cloudflare にアクセスしたりすることはありません。PATH に rg が必要です。

実際のプログラムを使ったスモークテストもあります。

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

smoke:providers は一時フォルダーで実際のターンを2回短く実行し、エージェントがファイルを編集できることと、会話を記憶できることを確認します。通常の Codex または Claude の利用分が消費されます。smoke:tunnel は実際の Quick Tunnel を起動し、エージェントを実行せずに、認証済みクライアントがそのトンネル経由で AgentGo にアクセスできることを確認します。cloudflared のダウンロードを許可するには、-- --yes を追加してください。

リリースの公開

AgentGo は npm で agentgo-mcp として公開されており、server.json を通じて MCP レジストリにも登録されています。 npm（npm login）とレジストリ（公式の mcp-publisher CLI を使った mcp-publisher login github）の両方にログインしておく必要があります。

まず、server.json の 2 つの version フィールドを、これから リリースするバージョンに設定します。次に、リポジトリのルートから以下を実行します。

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 を実行すると、公開前にパッケージに含まれる内容を確認できます。 npm publish は最初にパッケージをビルドします。

npm publish が成功した後、新しいバージョンが npm に掲載されるまで数分かかることがあります。 待っている間に再度公開しないでください。同じバージョンの 2 回目のアップロードは npm に拒否されます。 バージョンが掲載される前に mcp-publisher publish を実行すると、「version not found」というエラーが発生するため、npm view で確認できるまでお待ちください。

Codex と Claude Code の利用規約

AgentGo は OpenAI または Anthropic によって開発されたものでも、両社と提携しているものでもありません。インストール済みの codex および claude プログラムを変更せずに実行し、すでに設定済みのサインイン情報を使用します。AgentGo がそれらのサインイン情報を扱ったり、保存したりすることはありません。

エージェントが行うすべての操作には、OpenAI および Anthropic の利用規約が引き続き適用されます。そのため、以下の点にご注意ください。

• 自分だけで使用してください。 AgentGo のパスワードを他人に渡すと、その人があなたの Codex および Claude アカウントを使用できるようになりますが、これは両社の利用規約で禁止されています。
• サブスクリプションは通常の個人利用を対象としています。 エージェントを頻繁に実行する場合や、無人で実行する場合は、CLI に API キーでサインインしてください。

ライセンス

MIT。Cloudflare のホスティング、ストレージ、HTTP コードの一部は PrintGo をベースにしています。NOTICE をご覧ください。