Client¶

The client core, jezero_client.py: where it keeps its files, what client.json holds, the environment variables it reads, what each hook does for each agent, and how sessions travel to the server. For the flags of each command, see jezero_client.py.

The core is one Python file (Python 3.9 or newer, standard library only, so it runs with the python3 that ships with macOS). Every plugin carries a copy in its core/ folder, next to jezero_projects.py, the project rules it shares with the server. Its version is VERSION in the file (0.5.1). The plugins are thin adapters that map their agent's events to the core's hook events.

Nothing in the core may block or break an agent: every network call has a short timeout, hooks catch their own errors and write them to client.log, and uploads run in a detached process.

Client home¶

The folder that holds this computer's key, queue and state. The core picks the first of:

1. $JEZERO_CLIENT_HOME, when set.
2. For a command run with --agent (hook, mcp, status, flush, and each agent of setup and backfill), that agent's own folder, when it holds a client.json: ~/.gemini/config/jezero for antigravity, $CLAUDE_CONFIG_DIR/jezero for claude-code, $CODEX_HOME/jezero for codex.
3. $CLAUDE_CONFIG_DIR/jezero, then $CODEX_HOME/jezero, when it holds a client.json.
4. ~/.jezero.

Steps 2 and 3 are for agents run in a sandbox that cannot see your home folder: they keep their own key inside the agent's config folder. To create one there, run init with JEZERO_CLIENT_HOME pointing at that folder. A background upload started by a hook runs with JEZERO_CLIENT_HOME set to the hook's home, so it sends the queue of the key that queued it.

The OpenCode plugin picks its own home the same way, with $XDG_CONFIG_HOME/opencode/jezero (default ~/.config/opencode/jezero) as the agent folder, and passes it to the core as JEZERO_CLIENT_HOME.

Files¶

client.json¶

{
  "url": "https://YOUR-JEZERO",
  "device": "laptop",
  "projects": {
    "paths": {"~/clients/shop-web": "shop"},
    "roots": ["work"],
    "aliases": {"atlas-wt": "atlas"}
  }
}

The client counts as set up when client.json has a url and token is not empty. The device value is informational: the server knows the device by the name it was approved with.

Projects¶

projects follows the same rules as the server's [projects], first match wins:

The client applies the rules to the session's working folder, so the git rule works with this computer's repositories. The answer travels with the upload as X-Jezero-Project and wins on the server (see HTTP API). The same project chooses the recent work shown at session start.

state.json¶

Hooks and the uploader write state.json at the same time, so each change reads the file again, applies itself and saves it.

Environment variables¶

Commands¶

python3 ~/.jezero-src/jezero-client/jezero_client.py init --url https://YOUR-JEZERO --device laptop

You should see:

Device key created. The key stays in /home/me/.jezero; the server only keeps its SHA-256 fingerprint.
Ask the Jezero admin to approve it with:

  jezero device approve laptop SHA256

status prints, on a computer that uploads:

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

While the server refuses the key (HTTP 401 or 403) and sessions wait, a line says since when:

key: /home/me/.jezero
server https://YOUR-JEZERO: HTTP 403 {"ok":false,"error":"this key may not upload"}
queued sessions: 1
uploads refused since 2026-10-22 03:32: HTTP 403 {"ok":false,"error":"this key may not upload"} (the queue is kept)
rejected uploads: 0

Files the server rejected for good are counted, and the five newest are listed with their reason:

key: /home/me/.jezero
server https://YOUR-JEZERO: HTTP 200 {"ok":true,"device":"laptop","version":"0.1.0.dev0"}
queued sessions: 0
rejected uploads: 1
  2026-10-22 03:35 claude-code: HTTP 413 {"ok":false,"error":"file too large"}

On a read-only computer, after a list_sources call:

key: /home/me/.jezero
server https://YOUR-JEZERO: read-only, 4 readable sources

Not set up, status exits 1 with not set up (/home/me/.jezero): run `init` first.

Hook events¶

stop and session-end do nothing on a read-only computer or when the transcript is not a file the server accepts (for example a Claude Code sub-agent transcript).

The text the core adds looks like this:

Recent work on project `billing` in Jezero (newest first):
- [3] 2026-10-20 Dashboard chart colours
- [2] 2026-10-19 Invoice export: back to plain UTF-8 for the accounting import

Jezero has past work that may be related (check with `get_item` before using):
- [2] 2026-10-19 Invoice export: back to plain UTF-8 for the accounting import

The prompt's words are lowercased, without accents, at least 3 characters (letters, digits, ., -, _), without English and Spanish stop words, unique, at most 20.

The hook reads these fields of the agent's JSON: session_id, cwd, prompt (user-prompt), transcript_path (stop, session-end) and hermes_home (Hermes).

Per agent¶

The OpenCode plugin runs session-start and user-prompt with a 5-second limit.

Hermes Agent¶

The Hermes plugin imports the core instead of running it. It adds the jezero_search, jezero_get_item, jezero_later, jezero_timeline and jezero_list_sources tools (see MCP tools), each with a 20-second timeout, and only once the computer is set up. On the first turn of a session it adds the protocol, once per session, with the tool names Hermes uses (jezero_search, jezero_later, jezero_get_item); a session id that comes back after a context compression does not get it twice. Recent and related work follow under Jezero (shared memory of past work; check with jezero_get_item and jezero_later before relying on it):. Without a key it adds nothing.

Antigravity¶

Antigravity hooks read and write JSON. The core takes conversationId as the session id, the first of workspacePaths as the folder and transcriptPath as the transcript, and answers {} or, with context:

{"injectSteps": [{"systemMessage": {"systemMessage": "## Jezero: shared memory of past work (read-only) ..."}}]}

Protocol¶

The text session-start gives every agent, also printed by protocol:

## Jezero: shared memory of past work (read-only)

Jezero indexes past sessions of all of this user's agents and their project tasks: decisions, fixes, exact errors, commands and facts, each with the date it happened. Use it out of habit, without waiting to be asked:

- Before non-trivial work in a project, or when the user mentions something you have no context on, call the jezero `search` tool with 2-5 distinctive words (names, errors, ids). Matching is literal: try a synonym if nothing comes back.
- Before relying on a decision, plan, status or number from Jezero, call `later` on that item: a later session may have changed it. Answer with the newest state.
- Cite item ids like [123] when an answer comes from Jezero. If Jezero has nothing, say so; never fill the gap with a guess.
- Jezero is read-only and ingests sessions by itself: there is nothing to save.

Upload queue¶

1. Queue. stop, session-end and backfill check that the transcript maps to an inbox path (table below) and write a pointer, spool/pending/<agent>__<session>.json: {"agent", "session_id", "path", "cwd", "project", "queued_at"}. The folder is the hook's cwd, else the first cwd found in the first 50 lines of the transcript (or the cwd of a Hermes export); the project comes from the rules. A newer pointer for the same session replaces the older one.
2. Start. The hook starts python3 jezero_client.py flush as a detached process, so the agent never waits for the network.
3. Flush. One flush at a time (spool/flush.lock). Pointers are taken in name order:
4. an unreadable pointer is deleted;
5. a transcript that no longer exists counts as gone;
6. a transcript with the same modification time and size as when it was last sent, or as when the server last rejected it, counts as unchanged;
7. the rest are sent gzip-compressed with PUT /inbox/v1/<agent>/<path> and X-Jezero-Project, with a 60-second timeout, and count as sent.
8. Answer.
9. HTTP 200: sent.
10. HTTP 401 or 403: the server refused the key (not approved yet, revoked, or not allowed to upload). The flush stops (failed), the whole queue stays, and client.log says so once: uploads refused by the server (...): the queue stays until the server's admin allows this key to upload (upload = true in its [[clients]] block, picked up within a second). status shows uploads refused since ....
11. HTTP 400, 413 or 415: the server will never accept this file as it is. It counts as rejected, leaves the queue, and is recorded in state.json; it is sent again only if the file changes. status lists it.
12. Any other status or a network error: the flush stops (failed) and the queue stays for the next hook.

flush prints the counts:

{"sent": 1, "unchanged": 0, "gone": 0, "failed": 0, "rejected": 0}

Characters other than A-Z a-z 0-9 . _ - become _, and each part is cut at 150 characters.

Hermes exports¶

Hermes keeps its sessions in a database, so the core writes one file per session to spool/hermes/<session>.json, the shape the server's hermes connector reads with export_dir:

{
  "format": "jezero-hermes-export/1",
  "session": {"id": "20261021_091200_ab12cd", "source": "cli", "title": "Invoice export fix", "started_at": 1792573920.0, "cwd": "/home/me/projects/billing"},
  "messages": [
    {"id": 1, "role": "user", "content": "the invoice export breaks accents", "tool_calls": null, "timestamp": 1792573921.5}
  ]
}

Only user and assistant messages are exported (active ones, when the database marks them), and only the session columns that exist. Sessions whose source is cron or subagent are not exported. The file is rewritten only when the session changed, so an unchanged session is not uploaded again.

Backfill¶

backfill queues the sessions changed in the last --days (default 90) days, then starts an upload. Each agent's sessions go to the queue of the key that agent uses (see Client home), so a sandboxed agent's sessions upload under its own device name.

You should see:

queued 12 sessions; uploading in the background

An agent whose key is missing prints claude-code: not set up (/home/me/.jezero): run `init` first, and the other agents go on.

Read-only computers¶

init --no-upload writes "upload": false. Then hooks give context but never queue or upload, backfill prints claude-code: read-only computer (init --no-upload): nothing to upload for each agent, and status checks the key with list_sources instead of the inbox. Use it on the computer that runs the server, whose sessions the connectors already read, and approve it on the server with jezero device approve DEVICE SHA256 --read-only.

MCP bridge¶

jezero_client.py mcp is a local stdio MCP server that forwards every JSON-RPC line it reads to <url><mcp_path> with this computer's key, so the agent's configuration holds no key. The Claude Code and Antigravity plugins start it, and setup registers it in Claude Code (when the plugin is not installed) and Codex. With --agent NAME it uses that agent's key (see Client home). It keeps the server's Mcp-Session-Id, waits up to 60 seconds per message, and answers requests (not notifications) with a JSON-RPC error -32000 when it cannot help:

Setup¶

setup registers Jezero in each agent named with --agent (every agent without it), using the key that agent uses. An agent without a key prints NAME: not set up (/home/me/.jezero): run `init` first, and setup exits 1 after trying the others.

What it prints, for each case:

setup never writes the key into an agent's configuration. Only OpenCode's plugin passes the key to OpenCode in memory, as a header of the remote server it registers.

TLS¶

The core verifies the server's certificate with $JEZERO_CA_FILE when it is set, else with ca.pem in the client home when it exists, else with Python's default trust store. On macOS, where Python may not trust the system's certificates, a certificate error makes the core export the keychains' root certificates to ca.pem once and retry the request.

Limits¶

See also¶

• Connect a computer: the client, step by step.
• Connect an agent: installing each plugin.
• HTTP API: the routes the client calls.
• Command reference: every flag of jezero_client.py.