Project agents

Besides Claude and Codex, a project can bring its own agents. Any program that speaks the Agent Client Protocol (ACP) works: an eve agent, Gemini CLI, Goose, OpenCode, or one you write yourself.

Its chats work like any other: they stream, ask before acting, and are saved on your environment, where they show up in your chat list and search.

Add an agent#

Make a folder for it under .repogo/agents in your project, with an agent.json that says how to start it:

{
  "name": "Helper",
  "command": "npx",
  "args": ["eve", "acp"],
  "cwd": "agent"
}

• name is what the agent picker shows. Without it, the folder's name is used.
• command and args start the agent. A path starting with ./ is a file in the agent's folder.
• cwd is where it runs: project (the default) for agents that work on your code, or agent for its own folder. eve agents need agent.

The folder name is the agent's id: lowercase letters, numbers, dots, dashes and underscores.

Give it an icon#

icon sets the agent's icon in the picker, the composer and its chats in the chat list. It's either an https image URL or the name of a logo RepoGo has: claude, openai, codex, vercel, openrouter, github, cloudflare or fly.

{ "name": "Muse", "command": "muse-acp", "icon": "https://example.com/muse.png" }

Without one, the agent gets RepoGo's default icon. Your phone loads an image URL directly from that site and keeps a copy.

Use an agent in every project#

To offer an agent in all your projects, put its folder in ~/.repogo/agents on your environment instead, with the same agent.json. It shows in every project's picker.

If a project has its own agent with the same folder name, the project's one is used there.

A global agent with cwd set to project works on the code of whichever project the chat is in, and one copy runs per project. With agent, it runs in its own folder, and one copy serves every project.

Ship an agent in a plugin#

A plugin's folder can hold an agent too: put an agent.json beside its app.ts, in .repogo/plugins/<name> or ~/.repogo/plugins/<name>. The agent and the plugin share a name and a folder, so one folder can bring the agent, the methods and pages that show whether it's set up, and the code it runs, with the packages in the plugins folder's node_modules.

When two folders have an agent with the same name, the project's .repogo/agents wins, then the project's plugins, then ~/.repogo/agents, then ~/.repogo/plugins.

An agent for Gemini CLI, working on the project's code:

{ "name": "Gemini", "command": "gemini", "args": ["--experimental-acp"] }

Offer models#

Agents that list their own models over ACP show them in the picker after their first chat, and you pick one per chat.

For an agent that can't, like eve, list them in agent.json with the variable the agent reads its model from:

{
  "name": "Helper",
  "command": "npx",
  "args": ["eve", "acp"],
  "cwd": "agent",
  "modelEnv": "HELPER_MODEL",
  "models": [
    { "id": "claude-sonnet-5-5", "name": "Sonnet" },
    { "id": "claude-haiku-5-5", "name": "Haiku" }
  ]
}

Each model can have its own icon, in the same forms as the agent's: { "id": "claude-sonnet-5-5", "name": "Sonnet", "icon": "claude" }. Without one, a model whose id names its provider (like claude-… or gpt-…) shows that provider's logo, and any other shows the agent's icon.

The first model is the default. The agent starts with HELPER_MODEL set to the picked model, so an eve agent reads it in agent/agent.ts:

import { defineAgent } from "eve";
import { anthropic } from "eve/models/anthropic";

export default defineAgent({
  model: anthropic(process.env.HELPER_MODEL ?? "claude-sonnet-5-5"),
});

One copy of the agent runs for all its chats, so picking another model restarts it. Other open chats with it carry on, with their conversation handed to the restarted agent.

Start a chat with it#

1. Start a new chat in the project and tap the model pill.
2. Choose Project, then the agent, or one of its models.

Picking the agent is the go-ahead: RepoGo starts its command when you send, the way it runs the project's plugins. Only add agents from projects you trust.

An agent whose agent.json has a problem is listed with the reason, and can't be picked until it's fixed.

What to know#

• Effort and fast mode belong to the agent itself, so the picker doesn't show them.
• When it asks to use a tool, you answer with the agent's own options.
• If your environment restarts, an agent that can reopen its sessions carries on. One that can't is handed the conversation so far.
• An eve agent needs Node.js 24 and a model connection: run npx eve dev in its folder once and sign in with /login, or put an API key in its .env.local.