Skip to content

Connect an agent

Install the Jezero plugin in each agent you use, so the agent searches Jezero by habit and sends its sessions to your server. This guide covers Claude Code, Codex, OpenCode, Hermes Agent, Antigravity, any other MCP client, and the app's Agents view.

Before you start

  • This computer is connected: it has a key and the admin has approved it. See Connect a second computer, or Manage computers and keys for the details.
  • python3 (3.9 or newer) is on the agent's PATH: every plugin runs the client core with it.
  • The client bundle is unpacked in ~/.jezero-src/jezero-client. The commands below use that path; change it if you unpacked the bundle elsewhere. To get it:
mkdir -p ~/.jezero-src
curl -fsSL https://YOUR-JEZERO/client/jezero-client.tar.gz | tar -xz -C ~/.jezero-src

Check the connection before installing anything:

python3 ~/.jezero-src/jezero-client/jezero_client.py status

You should see:

key: /home/me/.jezero
server https://YOUR-JEZERO: HTTP 200 {"ok":true,"device":"laptop","version":"..."}
queued sessions: 0
rejected uploads: 0

A read-only computer shows server https://YOUR-JEZERO: read-only, N readable sources instead.

What each agent gets

Every plugin is a thin adapter over the same client core, so they behave alike. They differ in what their agent lets a plugin do.

Agent Tools At session start On the first prompt Upload Skill Older sessions
Claude Code MCP server through the local bridge, brought by the plugin protocol and recent work related past work at each stop and at session end jezero backfill
Codex MCP server through the local bridge, registered by setup protocol and recent work related past work at each stop and at session end jezero backfill
OpenCode MCP server, registered by the plugin protocol and recent work, in the system prompt related past work, in the system prompt when the session goes idle jezero none
Hermes Agent jezero_* tools nothing protocol, recent work and related past work, added to the first message at the end of a turn and when the session closes jezero:jezero backfill --agent hermes
Antigravity MCP server through the local bridge, brought by the plugin protocol and recent work related past work, before the first model call when the conversation stops jezero backfill --agent antigravity
  • Tools: search, get_item, later, timeline and list_sources. Hermes Agent gets the same tools under the names jezero_search, jezero_get_item and so on. See MCP tools.
  • Local bridge: jezero_client.py mcp, a small MCP server on the computer that adds the key to each request. The agent's configuration names the bridge, never the key. See MCP bridge.
  • Protocol: a short text that tells the agent to search Jezero before non-trivial work, to check later before relying on a decision, and to cite item ids. Print it with python3 ~/.jezero-src/jezero-client/jezero_client.py protocol.
  • Recent work: the five newest items of the project the session runs in. Nothing is added when the folder belongs to no project.
  • Related past work: up to three items whose title or summary contains at least two distinctive words of the first prompt. See Context on the first prompt.
  • Upload: the session is queued and sent by a background process, so the agent never waits. A stop sends at most once every 15 minutes per session (Hermes Agent: once every 10 minutes); the end of a session always sends. What is still queued goes out at the next session start. See The upload queue.
  • Skill: when to search and how to search well, for agents that load skills.

Context hooks wait at most 2.5 seconds for the server (JEZERO_HOOK_TIMEOUT). A hook never blocks or breaks the agent: errors go to client.log in the client home.

A plugin installed on a computer without a key stays quiet: the hooks print nothing, the tools are missing or answer that Jezero is not connected, and nothing is uploaded.

Claude Code

The plugin brings everything: the hooks, the skill and the MCP server, which is the local bridge (python3 ${CLAUDE_PLUGIN_ROOT}/core/jezero_client.py mcp --agent claude-code), so Claude Code's configuration never holds the key.

  1. Install the plugin:
claude plugin marketplace add MarsGotta/jezero
claude plugin install jezero@jezero

You can also run /plugin inside Claude Code. To install from your server's bundle instead of GitHub, use claude plugin marketplace add ~/.jezero-src/jezero-client.

  1. If this computer used an older Jezero client, remove the MCP entry it registered, which holds the key in clear:
python3 ~/.jezero-src/jezero-client/jezero_client.py setup --agent claude-code

You should see one of:

claude: the Jezero plugin brings the MCP server; nothing to register; removed the user-scope jezero entry (the plugin's own server replaces it)
claude: the Jezero plugin brings the MCP server; nothing to register

Run it with the same CLAUDE_CONFIG_DIR as the agent, if you set one.

  1. Restart Claude Code.

To give Claude Code the tools without the plugin (no hooks, no upload), run the same setup command without the plugin installed. It copies the core to the client home and registers the bridge at user scope:

claude: MCP server jezero registered (stdio bridge; the key stays in /home/me/.jezero)

For claude -p and other runs where nobody can answer a permission prompt, allow the Jezero tools in ~/.claude/settings.json (or in settings.json inside CLAUDE_CONFIG_DIR). The plugin's tools are named mcp__plugin_jezero_jezero__search and so on; those of a server registered by setup, mcp__jezero__search:

{
  "permissions": {
    "allow": ["mcp__plugin_jezero_jezero", "mcp__jezero"]
  }
}

For a single run, claude -p --allowedTools mcp__plugin_jezero_jezero "..." does the same.

Check it works. claude plugin list shows jezero@jezero as enabled, and claude mcp list shows the plugin's server as connected:

plugin:jezero:jezero: python3 /home/me/.claude/plugins/.../core/jezero_client.py mcp --agent claude-code - ✔ Connected

A line jezero: https://YOUR-JEZERO/mcp (HTTP) next to it is the old entry: run step 2. Start Claude Code in a project folder and ask about something you worked on before, without naming Jezero. The agent should call search, then later, and cite item ids like [123].

Update. Claude Code caches plugins by version:

claude plugin marketplace update jezero
claude plugin update jezero@jezero

Restart Claude Code to load the new version.

Remove.

claude plugin uninstall jezero@jezero

If setup registered the bridge without the plugin, also run claude mcp remove jezero --scope user.

Codex

The plugin brings the hooks and the skill, and setup registers the MCP server: the local bridge, so Codex's config.toml never holds the key.

  1. Install the plugin:
codex plugin marketplace add MarsGotta/jezero
codex plugin add jezero@jezero

You can also install Jezero from /plugins inside Codex. To install from your server's bundle, use codex plugin marketplace add ~/.jezero-src/jezero-client.

  1. Register the MCP server:
python3 ~/.jezero-src/jezero-client/jezero_client.py setup --agent codex

You should see:

codex: MCP server jezero added to config.toml (stdio bridge; key in /home/me/.jezero)

It adds this block to config.toml in CODEX_HOME (default ~/.codex) and leaves the rest of the file as it was:

[mcp_servers.jezero]
command = "python3"
args = ["/home/me/.jezero/core/jezero_client.py", "mcp", "--agent", "codex"]

With the key outside ~/.jezero, the block also gets env = { JEZERO_CLIENT_HOME = "..." }. An old block with url and http_headers, written by an older client with the key in clear, is replaced: codex: replaced the old jezero entry in config.toml (it held the key in clear) with the stdio bridge.

  1. Trust the hooks: open Codex, run /hooks and trust the Jezero hooks. Codex does not run a plugin's hooks until you do, so until then there is no context and no upload.

Check it works. codex plugin list shows jezero@jezero installed, enabled with its version, and codex mcp list lists jezero. Then ask about past work in a project folder, as for Claude Code.

Update.

codex plugin marketplace upgrade jezero
codex plugin add jezero@jezero

If Codex lists the hooks as untrusted again in /hooks, trust them again.

Remove.

codex plugin remove jezero@jezero
codex mcp remove jezero

OpenCode

The OpenCode plugin is one folder with its own copy of the core and the skill. It registers the MCP server itself, when OpenCode loads it, so your opencode.json is never edited.

  1. Install it with setup:
python3 ~/.jezero-src/jezero-client/jezero_client.py setup --agent opencode --opencode-plugin ~/.jezero-src/jezero-client/opencode

It writes ~/.config/opencode/plugins/jezero.ts, pointing at a copy of the core in ~/.jezero/core/, and the skill in ~/.config/opencode/skills/jezero/. It follows XDG_CONFIG_HOME, and skips OpenCode when neither ~/.config/opencode nor the opencode command exists.

Or, from a clone of the repository, load the plugin folder in opencode.json:

{
  "plugin": ["file:///home/me/jezero/plugins/opencode/jezero.ts"]
}
  1. Restart OpenCode.

The plugin adds a remote MCP server named jezero at the URL in client.json plus its mcp_path (/mcp by default), with the key in its header, read from the key file each time OpenCode starts. The key stays in OpenCode's memory, not in its configuration files. If your configuration already has an mcp.jezero entry, the plugin leaves it alone.

Check it works. Start OpenCode in a project folder and ask which Jezero sources it can read: it should call list_sources on the jezero server. If the key was missing when OpenCode started, the server is not registered: restart OpenCode after init.

Update. Download the bundle again and repeat step 1. With a clone, pull it.

Remove. Delete ~/.config/opencode/plugins/jezero.ts, ~/.config/opencode/skills/jezero/ and ~/.jezero/core/, or remove the plugin line.

OpenCode sessions reach Jezero only through the plugin, when a session goes idle: backfill cannot send sessions from before it was installed.

Hermes Agent

The Hermes plugin brings its own tools and calls the server with this computer's key.

  1. Install and enable it:
hermes plugins install MarsGotta/jezero/plugins/hermes --enable

Hermes installs plugins per profile: run it in each profile that should use Jezero.

  1. Restart Hermes, including the gateway if you run one.

The jezero_* tools appear only once Hermes finds a key: in ~/.jezero, or in the folder named by JEZERO_CLIENT_HOME in the environment Hermes runs in. On the first turn of a session the plugin adds the protocol (once per session), recent work and related past work to your message (Hermes keeps the system prompt unchanged). Scheduled jobs and subagent sessions are never uploaded.

Check it works. hermes plugins list shows jezero as enabled. Ask "which Jezero sources can you read?": the agent should call jezero_list_sources.

Send older sessions.

python3 ~/.jezero-src/jezero-client/jezero_client.py backfill --agent hermes

It reads state.db in HERMES_HOME (default ~/.hermes); pass --hermes-home FOLDER for another profile.

Update.

hermes plugins update jezero

Restart Hermes afterwards.

Remove.

hermes plugins remove jezero

Antigravity

The Antigravity plugin brings the MCP server, the hooks and the skill.

  1. Install it:
agy plugin install https://github.com/MarsGotta/jezero/tree/main/plugins/antigravity

[!WARNING] Use the full path to plugins/antigravity. The bare repository URL installs every plugin folder of the repository under the same name, and the last one, Claude Code's, wins: no MCP server and hooks that cannot run.

The plugin lands in ~/.gemini/config/plugins/jezero.

  1. Allow the tools. Antigravity asks once before the first call of a read-only tool. Headless agy runs cannot ask, so add the rule to ~/.gemini/antigravity-cli/settings.json:
{
  "permissions": {
    "allow": ["mcp(jezero_jezero/*)"]
  }
}

The MCP server is the local bridge, jezero_client.py mcp --agent antigravity, so the key never sits in Antigravity's configuration. The bridge, the hooks and the background upload use ~/.gemini/config/jezero when it holds a key, for sandboxes that see ~/.gemini but not your home (see Agents in a sandbox).

Check it works.

agy plugin list

You should see:

Installed plugins:
- jezero (enabled)
    Source:     antigravity
    Components: 1 skill, 1 MCP server, 1 hook

Send older conversations.

python3 ~/.jezero-src/jezero-client/jezero_client.py backfill --agent antigravity

Update. Run the install command again.

Remove.

agy plugin uninstall jezero

Any other MCP client

Any MCP client can read Jezero. It gets the tools only: no hooks, no upload.

With the local bridge. A client that runs local (stdio) servers can use the bridge with this computer's key, so its configuration holds no key:

{
  "mcpServers": {
    "jezero": {
      "command": "python3",
      "args": ["/home/me/.jezero-src/jezero-client/jezero_client.py", "mcp"]
    }
  }
}

Over HTTP, with a key of its own. A client that only speaks MCP over Streamable HTTP, or that runs on a computer without the client core, needs its own key in its configuration:

Warning

This stores the key in the client's configuration file, in clear. Use the bridge when the client supports it, give the key only the sources it needs, and revoke it with jezero device revoke when the client goes away.

  1. Make the key, on the server:
jezero new-token

Hand the token to the client and add a client block with the digest. The server picks it up within a second:

[[clients]]
name = "shop-assistant"
token_sha256 = "SHA256"
sources = ["agent-*"]

See [[clients]] and Limit what a key can read.

  1. Configure the client with the URL https://YOUR-JEZERO/mcp and the header Authorization: Bearer ***. The field names depend on the client; a common shape is:
{
  "mcpServers": {
    "jezero": {
      "type": "http",
      "url": "https://YOUR-JEZERO/mcp",
      "headers": { "Authorization": "Bearer ***" }
    }
  }
}

Either way, add the protocol to the client's instructions, so it uses Jezero by habit:

python3 ~/.jezero-src/jezero-client/jezero_client.py protocol

Use the app

The Jezero app shows the agents on this computer and the Jezero version in each:

jezero agents

Its Agents view (4) has an install or update button per agent, and shows the commands before running them: the ones on this page. For Claude Code and Codex, installing adds the marketplace, installs the plugin and runs setup; updating updates the marketplace and the plugin. For OpenCode it runs setup --opencode-plugin, and for Hermes Agent and Antigravity the plugin's install command. The view also says how each agent reaches the MCP server: MCP via plugin, MCP server registered, or old MCP entry with the key in clear: run setup when an older client left the key in the agent's configuration.

Next steps