Connect

Connect an agent

Set up Claude Code, Codex, opencode or Gemini CLI to use YonedaRepo through its plugin or skill and the account MCP endpoint.

How agents connect#

Agents are ordinary clients of the platform. A coding agent works in a Git clone like a person, and reaches the platform's tools (search, changes, sessions, memories) over MCP. It uses the same tokens, scopes and landing rules as people.

1. Give the agent a token#

Export a token where the agent runs. With the CLI signed in, reuse its login:

Shell
export YONEDA_TOKEN=$(yoneda auth token)

Or create a personal access token under Settings → Personal access tokens with only the scopes and repositories the agent needs, and export that.

Every setup below reads the token from YONEDA_TOKEN when the agent starts; none of them writes a token into a file.

2. Set up the agent#

With the CLI installed:

Shell
yoneda setup claude      # or: codex, gemini, opencode
AgentWhat yoneda setup writesHooks
Claude Code.mcp.json in the current directory, then prints the plugin install commandsYes, with the plugin
Codex[mcp_servers.yoneda] in ~/.codex/config.toml (or $CODEX_HOME), and the skill in ~/.agents/skills/yoneda/No
opencodeThe plugin in ~/.config/opencode/plugins/yoneda/, and the MCP entry in opencode.jsonYes
Gemini CLIThe extension in ~/.gemini/extensions/yoneda/, and the MCP entry in ~/.gemini/settings.jsonNo

All of them point at the account MCP endpoint, https://api.yonedarepo.com/api/v1/mcp (--origin <url> for another platform).

Claude Code plugin#

Inside Claude Code (version 2.1.224 or later), add YonedaRepo's marketplace and install the plugin. yoneda setup claude prints the same two commands:

Text
/plugin marketplace add https://yonedarepo.com/downloads/claude/marketplace.json
/plugin install yoneda@yonedarepo

The marketplace is served by yonedarepo.com and the plugin is a download pinned by its SHA-256, so you need no GitHub or other Git account. The plugin connects to https://api.yonedarepo.com/api/v1/mcp; YONEDA_MCP_URL points it at another platform. To register the MCP server for yourself instead of per project:

Shell
claude mcp add --transport http --scope user yoneda https://api.yonedarepo.com/api/v1/mcp \
  --header "Authorization: Bearer \${YONEDA_TOKEN}"

What the hooks do#

In a clone with a YonedaRepo remote, the Claude Code and opencode plugins:

  • Start each session with context: the repository's memories, recent sessions, open changes, landing rules and contracts.
  • Track what the session reads. Files it reads become the next push's declared reads, and the memories and contracts on them are added as context.
  • Add context for each prompt that is relevant to it.
  • Send pushes through yoneda push, so the declared reads travel with them.
  • Record the session on each commit it pushed, with its transcript (credentials redacted), and offer a draft memory.

The hooks run the yoneda CLI, so it must be installed where the agent runs. Codex and Gemini CLI get the skill and MCP tools without hooks; they can call the same tools directly.

Without the CLI#

Any MCP client can connect with a JSON configuration; see MCP. Git itself works with a token over HTTPS.

Troubleshooting#

SymptomWhat to do
The agent's MCP calls answer 401YONEDA_TOKEN is not set in the agent's environment, or the token expired
/plugin marketplace add fails on the URLUpdate Claude Code: URL marketplaces with downloaded plugins need 2.1.224 or later
Claude Code connects to the wrong platformUnset YONEDA_MCP_URL, or set it to the platform you mean
Hooks do nothingInstall the CLI, and run the agent inside a clone with a YonedaRepo remote