Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
Gemini as a nodeterm agent
Gemini (@google/gemini-cli, gemini on PATH — measured here at 0.54.4) is a builtin agent id
alongside claude, codex, opencode and grok: AGENT_CONFIG.gemini in src/shared/agents/config.ts —
label Gemini, colour #4285f4, launchCmd: 'gemini', promptInjectionMode: 'stdin-after-start',
expectedProcess: 'gemini', and no argvPromptSeparator (grok is the only agent that asks for
one, pinned in config.capabilities.test.ts). Status comes from gemini's own hooks, never from
parsing output.
Unlike grok, almost nothing here is a guess. The CLI is installed on the machine this integration was built on, and it ships its own hook reference at
/usr/lib/node_modules/@google/gemini-cli/bundle/docs/hooks/reference.md(330 lines) plus a command reference atbundle/docs/reference/commands.md. Where those two are not specific enough, the answer was read out of the shipped bundle JS itself. Every claim below cites one of: that hook reference by line, the bundle by chunk + line,gemini --help, or a captured transcript (src/core/__fixtures__/gemini/session.jsonl, taken from~/.gemini/tmp/nodeterm/chats/session-2026-08-09T10-48-fd01438b.jsonlon this host). The few genuinely open items are marked unverified and collected in §7–§8.
Personal Google accounts can no longer use Gemini CLI (since 2026-06-18). Google moved the terminal experience to Antigravity CLI (
agy, closed source; nodeterm'santigravityagent —docs/antigravity-agent.md) and Gemini CLI now refuses the free tier, Google AI Pro and Google AI Ultra (announcement: google-gemini/gemini-cli discussion #27274). Gemini Code Assist Standard/Enterprise licences, Vertex AI and paid Gemini API keys are unaffected, so thegeminiagent stays — existing nodes must still load, and those users still run it. What a refused user sees is the browser saying "Authentication succeeded" and then the CLI's sign-in screen again, withThis client is no longer supported for Gemini Code Assist for individuals. To continue using Gemini, please migrate to the Antigravity suite of products(captured from a user's screen, 2026-09-28). Reinstalling or deleting~/.geminidoes not help. nodeterm names it in two places:AgentConfig.notice(the tooltip wherever gemini is offered) and a slim node banner raised when a gemini-harness pane prints that sentence (renderer/terminal/gemini-retired.ts) — the one place this agent reads its output, because the refusal comes before any session and so before any hook. The banner types nothing; it offers an Antigravity node beside this one and Google's migration guide.
1. What gemini is, capability by capability
Capabilities are membership lists in src/shared/agents/config.ts, not a flag bag. What matters for
maintenance is not that gemini is in a list but what had to be true before it could join — that
is the price of adding the next agent to the same list.
| List | gemini | What had to be true first |
|---|---|---|
AGENT_HOOK_TARGETS |
joined (pre-branch) | A normalizer for gemini's own event names (normalizeGemini, src/shared/agents/normalize.ts), a subscription list restricted to the events it maps (GEMINI_HOOK_EVENTS, src/shared/agents/hook-events.ts), and an installer — which is the shared one, because gemini keeps hooks in a single settings file exactly as claude does (core/agents/hooks/gemini.ts → installHooksInto on ~/.gemini/settings.json). |
RESUMABLE_AGENTS |
joined (pre-branch) | resumeCommand('gemini', id) → gemini --resume <id>, and a session id that reaches the renderer off every hook payload. Unverified: that gemini's hook session_id is the id --resume accepts (its docs say so; no live run). |
USAGE_CAPABLE (the per-node context meter) |
joined this branch | BOTH numbers, from gemini's own transcript: a used count and a trustworthy window. Used = the newest turn line's tokens.input (core/gemini-session.ts). The window is the harder half, and the reason gemini could join at all is that its CLI states a family rule with a catch-all default, not a per-model table — so geminiWindowFor mirrors tokenLimit() and an unheard-of model still gets the right answer (§4). Plus a third thing that is easy to miss: joining this list turns on more than the meter — see the warning under the table. |
TITLE_READ_CAPABLE |
joined this branch (the list was created for it) | A read leg that resolves a session's own name without searching another agent's tree (pickGeminiTitle over the transcript path the context tail already tracks), and one routing rule for the readers: readAgentSessionName in core/agent-session-name.ts, serving the desktop IPC handler and both shells' session-name sweeps. This list exists because of gemini: it names its own sessions but cannot be told a name, so the read and write legs had to split (§6). |
RENAME_CAPABLE |
deliberately NOT joined | There is no rename command to write to. Gemini's session commands are /chat (an alias for /resume) with `debug |
PERMISSION_MODE_CAPABLE |
joined this branch | A per-agent translation, because gemini does not share claude's flag spelling: --approval-mode default|auto_edit|yolo|plan (gemini --help, 0.54.4) against our manual|auto|acceptEdits|plan|bypassPermissions. The table is GEMINI_MODES in src/shared/agents/approval-mode.ts; §5 has the mapping and the one mode — auto, which is also the DEFAULT — gemini has no word for. |
CONTEXT_LINK_CAPABLE |
joined (pre-branch) | A parser for gemini's event-sourced chat format plus a locator by sessionId (handoff/locate.ts's locateGemini), and a discovery route — the marker block merged into ~/.gemini/GEMINI.md. |
TRANSFER_SOURCE_CAPABLE |
joined (pre-branch) | The same native-transcript reader cross-agent transfer needs. |
CANVAS_CONTROL_CAPABLE |
joined (pre-branch) | The marker block in ~/.gemini/GEMINI.md (gemini gets no skill — that is claude's discovery mechanism, which grok borrows). Membership is what sets NODETERM_CANVAS_CONTROL in the session env. |
CHAT_CAPABLE |
joined 2026-09 | Its own reader, core/gemini-chat.ts (§3, "The ⌘M chat view's fold"), routed in readChatTranscript BEFORE anything claude-shaped (through capabilityAgentId, so a custom agent built on gemini reads it too) and located strictly by the session id in the file's header — never claude's resolveTranscript, whose cwd fallback would answer with a stranger's claude session. CLAUDE_TRANSCRIPT_READABLE stays claude-only, so the find bar and context.ensure are untouched. Local-only (CHAT_LOCAL_ONLY): a remote node answers "not supported yet". |
SUBAGENT_CAPABLE |
not joined | Subagent cards are driven by claude's Agent/Task tool correlation; gemini's equivalent vocabulary is not mapped. |
BRANCH_CAPABLE |
not joined | Branch sends claude's /branch and resumes by claude's session id; gemini has no counterpart. |
RECURRING_CAPABLE |
not joined | /loop, /schedule, /cron are detected from claude's Skill / CronCreate / ScheduleWakeup tool names. |
⚠ Ask what ELSE a list gates before joining it.
hasUsagegated three features, not one, and theUSAGE_CAPABLEjoin above turned on all three at once. Two of them route throughcore/transcript-ipc.ts'sresolveTranscript, which has a cwd fallback: when the sessionId leg misses — and it always misses for a gemini or codex id, since no<that id>.jsonlexists under~/.claude/projects— it returns the newest claude transcript for that cwd. Socontext.ensurerehydrated a codex/gemini node's meter from a stranger's claude session (wrong numerator, wrong denominator, then flapping against the correct tail), and the find bar indexed that session's messages as this node's hits. Fixed by a pure predicate,readsClaudeTranscript(src/renderer/lib/transcriptGates.ts), which now readsCLAUDE_TRANSCRIPT_READABLE(claude only) — it first reusedCHAT_CAPABLE, and was split off when grok, then gemini, joined that list with readers of their own. The meter stays onhasUsage; what a non-claude agent gives up is only the mount-time head start — its meter fills on the first hook event after mount instead of instantly. Correct-but-later beats instant-but-borrowed.
2. The hook dialect: claude-shaped envelope, gemini's own event names
Gemini's envelope is the easy part. Its base input schema is claude's five fields
(reference.md:46-58):
session_id, transcript_path, cwd, hook_event_name, timestamp
transcript_path is present (reference.md:53) — the exact opposite of grok, which carries none
and forces a (cwd, sessionId) derivation plus a remembered sessionId → dir map in both shells.
For gemini the shells simply take the path they are handed, jail it, and hand it to the tail. That
one field is the difference between a five-line branch and grok's thirty.
What is not claude's is the event names. Gemini publishes eleven events
(reference.md, one ### heading each — count it, the file has exactly eleven):
BeforeTool · AfterTool · BeforeAgent · AfterAgent · BeforeModel · BeforeToolSelection ·
AfterModel · SessionStart · SessionEnd · Notification · PreCompress
GEMINI_HOOK_EVENTS subscribes seven of them, and the four omissions are each for a different
reason:
| Left out | Why |
|---|---|
AfterModel |
Fires per streamed chunk — reference.md:236, "Fired for every chunk generated by the model", and its fireAfterModelEvent(originalRequest, chunk) call sits inside the chunk loop (bundle/chunk-YMKYUNCI.js:331095). Subscribing means one hook process per chunk. It is also the event carrying llm_response.usageMetadata.totalTokenCount — the one number worth having — which is exactly why the context meter reads the transcript instead (§4). Do not "just add AfterModel" to get the tokens. |
BeforeModel |
NOT per-chunk — it fires once per model request (reference.md:189, "Fires before sending a request to the LLM"; fireBeforeModelEvent at chunk-YMKYUNCI.js:330773, outside the loop). An earlier comment in hook-events.ts attributed per-chunk firing to both, and that was wrong. It is omitted for the plain reason the two below are: it reports nothing we render. A turn's start is already BeforeAgent. |
BeforeToolSelection |
reference.md:204-219 — no state we render. |
PreCompress |
reference.md:287-297 — no consumer. |
The seven map as follows (normalizeGemini); anything else returns null, a deliberate no-op:
| gemini event | NormalizedAgentEvent |
note |
|---|---|---|
BeforeAgent |
working, newTurn: true |
the turn start (mirrors claude's UserPromptSubmit); newTurn is what clears per-turn fan-out once per turn rather than on every tool event |
BeforeTool / AfterTool |
working |
keeps RUNNING alive across a long tool call |
AfterAgent |
done |
the turn end |
SessionStart |
session start |
source is startup|resume|clear (reference.md:250-251) and maps unconditionally — a /clear really is one session ending and another beginning |
SessionEnd |
session end |
reason is exit|clear|logout|prompt_input_exit|other (reference.md:265-266), likewise unconditional. Gemini subscribing SessionEnd is what lets the context tail untrack itself (codex does not, so its tail is released by releaseNodeTails instead) |
Notification with notification_type === 'ToolPermission' |
blocked + lastMessage |
the addition this branch made — see below |
Notification, any other type |
nothing (null) |
a closed match, on purpose |
Notification is gemini's only ask-the-user signal, and it is matched as a closed set
Before this branch, a gemini node sat on RUNNING while it waited for a permission answer: the
last hook heard was BeforeTool, and gemini has nothing like claude's PermissionRequest.
Notification (reference.md:272-285) is the one signal that a human is being asked something.
blocked rather than waiting for two reasons: normalizeClaude already uses blocked for a
permission ask (every consumer treats them alike), and BUSY_STATES then refuses an in-place
restart on that node — correct, because /quit typed into a permission prompt would answer the
prompt instead of quitting. That refusal only became reachable for gemini once gemini joined
EXIT_SEQUENCES (§6): restartEligibility returns not-resumable before it ever consults
BUSY_STATES.
The match is === 'ToolPermission', never a substring, and this is measured rather than cautious:
- The docs name exactly one type (
reference.md:278,notification_type: ("ToolPermission")). - So does the bundle:
NotificationTypeis an enum with exactly one member (chunk-YMKYUNCI.js:333959-333962), and the single call site isfireNotificationEvent(NotificationType.ToolPermission, message, serializedDetails)(:362327, insidefireToolNotificationEvent). - And it fires only for a real confirmation dialog.
notifyHooksis called fromresolveConfirmation(chunk-YMKYUNCI.js:340094-340101) aftershouldConfirmExecutehas returned details; when it returns nothing the code takesoutcome = ProceedOnce; break;and the notification never happens. An auto-approved oryolotool call therefore fires nothing.
That last point is what makes gemini structurally safe from grok's strobe: there,
type.includes('permission') turned a notification grok emits before every tool call into a
NEEDS YOU badge plus a chime plus an OS notification plus a phone inbox card, per tool call.
Widening gemini's test "to be safe" is the unsafe direction — an unknown future type must stay a
no-op, because a badge stuck on a finished node has no later hook to clear it.
Nothing here can be answered from our side: the hook is observability only and its flow-control
fields are ignored (reference.md:284-285), so this reports state and no more — no pendingId,
unlike claude's deterministic-approval path.
Hook installation
core/agents/hooks/gemini.ts is a thin wrapper over the shared installHooksInto on
~/.gemini/settings.json — merged and idempotent, preserving other tools' hooks, exactly as
claude's is. The event list is imported from GEMINI_HOOK_EVENTS; the SSH installer imports the
same constant (src/main/remote-ssh/remote-hooks.ts:57-59, AGENT_TARGETS). That is not
cosmetic: the two lists used to be declared separately and had drifted so far that the remote
installer subscribed gemini to claude's event names, which gemini never fires — remote gemini
nodes reported no status at all. One definition is the fix.
Gemini's events are plain strings, so its emitted config is byte-identical to what it has always
been; only grok needs the { event, matcher } form of ManagedHookEvent.
3. Where gemini's conversation lives
~/.gemini/tmp/<project>/chats/session-<ISO-ish stamp>-<short id>.jsonl
— the same root handoff/locate.ts's locateGemini walks, and the root the transcript jail was
widened to. That widening is the security-relevant part: hook POSTs can arrive over the remote
reverse tunnel, so a forged POST must not aim a file read at an arbitrary local path.
isSafeLocalTranscriptPath (core/claude-accounts-core.ts:79-102) now admits four roots —
claude's ~/.claude/projects, a managed account's {userData}/claude-accounts/<id>/projects,
gemini's ~/.gemini/tmp, and codex's <codexHome>/sessions. Per root, never $HOME: this
predicate exists precisely so a forgery cannot reach ~/.ssh/id_rsa, and a home-wide allowance
hands that straight back.
The transcript is event-sourced: a line is an append, and metadata changes arrive as
{"$set":{…}} records that a reader folds over the ones before them. One of those records is
{"$set":{"messages":[…]}} — an in-session history sync: when gemini has to rewrite the
conversation it holds in memory (a tool result patched onto an earlier call, say), it writes the whole
array in one record, and its own reader CLEARS what it had and takes that array as the history
(chunk-TYAF55F7.js:285852-285857 writes it, :285303-285335 reads it). It is routine and has
nothing to do with resume — the never-resumed capture has one at line 2.
Both readers therefore scan backwards for the newest line that parses to something they accept
(latestJsonLineWhere in core/gemini-session.ts, shared with codex-session.ts), with the needle
as a cheap pre-filter only — a line can mention a key deep inside without carrying it at the top
level, and gemini's $set line is exactly that case.
What a resume actually does (measured in the same bundle, 0.54.4): it appends to the same
file and writes exactly one record, {"$set":{"sessionId":…}} (:285453). Nothing is replayed.
The one branch that does re-write history is the legacy .json → .jsonl migration
(:285430-285450), and even that appends each message as its own ordinary line, not as a
$set.messages array. This matters because an earlier version of this document — and of
pickGeminiTitle's docblock — described the $set.messages walk as the resume mechanism; it is
not. See §6.
The ⌘M chat view's fold (core/gemini-chat.ts)
The paragraph above calls the file event-sourced; for the CHAT view the precise shape matters, and
it was measured against 0.61.0's ChatRecordingService (chunk-JDPZ4CE3.js, appendRecord,
pushMessage, rewindTo, updateMessagesFromHistory, and its own reader loadConversationRecord):
- A message record (
{id, timestamp, type, content, displayContent?, thoughts?, tokens?, model?, toolCalls?},type∈user | gemini | info | warning | error) is an upsert: the same id is written again, in full, whenever the message changes — its tool calls added, their results landed (toolCalls[].result=functionResponseparts), its tokens arrived. A tool's output is ALSO recorded as its owntype:"user"record offunctionResponseparts. {$rewindTo: id}deletes that message and everything after it.{$set: {messages}}REPLACES the model's history: at session start (the<session_context>preamble), at every compression (all turns re-minted under NEW ids, a<state_snapshot>summary inserted as a user turn, older turns dropped) and when an aborted turn is rolled back.
The chat thread is therefore the message records alone, upserted by id, with rewinds honoured and
$set.messages ignored — it is what gemini will send next, not what was said, and honouring it
would erase the thread at every compression and present the snapshot as the human's words. A rewind
to an id the thread never held (a post-compression copy, or one before the 5 MB read cap) is ignored
rather than wiping everything as gemini's own loader does. User bubbles prefer displayContent (the
typed text, when an @file expanded content) and drop <session_context> / <hook_context> text
PER PART (a BeforeAgent hook's context is appended beside the prompt). Thoughts are dropped; info /
warning / error render as [info] … assistant notes. Because a record depends on earlier ones,
the view does not page: one whole read under the 5 MB cap, olderCursor: null, like grok. The exact
rules, and golden fixtures a port locks to, are in src/shared/chat-fixtures/gemini/README.md.
locateGemini reads only each candidate's header line now (the view re-locates on every live
reload) and honours GEMINI_CLI_HOME, the CLI's own home relocation.
4. The context meter: tokens.input, and gemini's own tokenLimit()
Used tokens — measured shape, __fixtures__/gemini/session.jsonl line 29:
"tokens":{"input":17149,"output":29,"cached":7760,"thoughts":171,"tool":0,"total":17349},
"model":"gemini-3.5-flash"
Both fields are on the same line, which is what lets one backward scan settle used and window.
inputis the used count — it is what fills the window at that turn.totalfolds inoutputandthoughts, which have already left the prompt; the fixture proves the split (input + output + thoughts + tool === totalon every line).cachedis NOT added. It is a subset ofinput(cached input still occupies the window and is already counted there), so adding it double-counts. Claude is the opposite — its input excludes cache reads, which is whycontext-tail.ts'sparseLatestUsagesums them. The two formulas must not be unified. Codex is a third variant with the same trap in the same direction (cached_input_tokensinsideinput_tokens); seecore/codex-session.ts.
The window is where gemini earned its place in USAGE_CAPABLE. Its transcript states no
denominator, so the model id is the only signal — but gemini does not need a guess, because the
CLI's own resolver is a family rule with a catch-all default. Read out of the shipped bundle
(chunk-BS6BSLZD.js:331674-331686):
var DEFAULT_TOKEN_LIMIT = 1048576;
var GEMMA_4_TOKEN_LIMIT = 256e3;
function tokenLimit(model) { switch (model) {
case GEMMA_4_31B_IT_MODEL: case GEMMA_4_26B_A4B_IT_MODEL: return GEMMA_4_TOKEN_LIMIT
case PREVIEW_GEMINI_MODEL: … case DEFAULT_GEMINI_FLASH_LITE_MODEL: return 1048576
default: return DEFAULT_TOKEN_LIMIT } }
geminiWindowFor (core/model-window.ts) mirrors that and only that: the two gemma models as
the special case, everything else on the 1 M default. The five named 1 M cases are redundant, and
copying them would only create something to go stale — an unknown or newly released gemini model gets
the right answer from the default, which is exactly what a per-model allowlist would get wrong,
silently, with a confident wrong denominator. The fixture's gemini-3.5-flash is in neither list and
lands on the default, which is evidence the default branch is the one carrying the feature.
null only when the transcript names no model at all — then the meter stays hidden rather than
dividing by an invented number.
Plumbing: one tail per agent, each with its own parser — not one tail switching on an agent id,
which would have meant changing ContextTail.track(sessionId, path) and its four call sites. The
poller (offset reads, torn-line carry, change-gated push) is written once in createContextTail;
only parse differs (geminiContextParse / codexContextParse). Neither gets
onTaskNotification/onToolResult — both are claude transcript features. Both shells create
both tails and both jail the path the same way (src/main/index.ts:1178-1182,
src/server/agent-status.ts); the desktop's copy additionally skips remote (SSH) nodes, whose
transcript is on the host, while the server has no SSH-project manager and so has nothing to skip.
5. Permission mode: --approval-mode, and the mode gemini has no word for
activePermissionMode(agentId) resolves the project override, else settings.claudePermissionMode
(the persisted key keeps its name — renaming it would silently reset every existing user's choice).
withPermissionMode in src/shared/agents/approval-mode.ts is the single funnel; where the flag
lands is decided one layer up by createAgentNode, and for gemini it goes last (no
argvPromptSeparator), so the composed line stays the historical shape.
gemini --help (0.54.4): --approval-mode [choices: "default", "auto_edit", "yolo", "plan"].
| nodeterm mode | label | gemini flag | note |
|---|---|---|---|
manual |
Ask each time | (none) | gemini's own default is documented as "prompt for approval", which is exactly what the label promises — so no flag reproduces it, as it does for claude |
auto |
Auto | (none) | no equivalent — see below |
acceptEdits |
Accept edits | --approval-mode auto_edit |
the direct equivalent ("auto-approve edit tools") |
plan |
Plan | --approval-mode plan |
"read-only mode" |
bypassPermissions |
Bypass all | --approval-mode yolo |
"auto-approve all tools" |
auto emits no flag, and that is the whole reason this section exists. auto is
DEFAULT_PERMISSION_MODE, so this row decides what an untouched install launches gemini with.
Gemini's vocabulary is exactly those four values, and none of them means "approve most things but
NOT edits" — the nearest, auto_edit, is "auto-approve edit tools", i.e. the opposite end of the one
axis our auto is about. The first version of this table mapped auto → auto_edit anyway, and the
consequence was concrete: every existing gemini node would have started auto-approving file edits
on upgrade, with no notice. Before gemini joined PERMISSION_MODE_CAPABLE it always launched bare
(= gemini's default = prompt for approval), and modeSupported('gemini','auto') would have
answered true, so unsupportedModesNote() would not have admitted it either — a silent widening of
permissions dressed as a translation. So auto is absent from GEMINI_MODES,
modeSupported('gemini','auto') is false, and the launch is the bare pre-branch command. This is
the branch's own rule applied to gemini instead of exempted from it: a mode the CLI cannot express
emits no flag, never a substituted nearest match (the same reason codex's plan and acceptEdits
emit nothing). The cost is that auto and manual land on the same gemini policy — but that policy
is the prompting one, which is the safe direction, and the derived copy now says it out loud:
Auto has no Gemini equivalent, so Gemini sessions start in Gemini's own default.
Pinned by approval-mode.test.ts ("emits NO flag for auto, the default mode, rather than
auto-approving edits"), which asserts the flags, modeSupported, the composed command line, and that
the note names gemini and the mode.
Gemini does NOT inherit claude's auto version gate. That gate exists because Claude Code
< 2.1.71 exits 1 on --permission-mode auto, and it is fed by a claude --version probe (local, or
the SSH host's). Gemini accepts every value in the table on the version measured, so gating it on
claude's probe would downgrade a gemini session on a machine whose claude is old or absent.
activePermissionMode gates only agentId === 'claude', ensureActivePermissionMode awaits the
probes only for claude, and sshAutoModeHint's copy names Claude in every sentence for the same
reason. An agent needing its own gate adds one beside claude's.
Security, re-stated because it is easy to lose: mode values come from hand-editable, git-shared
JSON (settings.json / project.json) and end up interpolated into a shell command line (tmux
send-keys), so the mode is re-validated at the interpolation site — isPermissionMode at the
top of approvalFlags, mirroring permissionModeFlag. The type proves nothing. Without that guard a
forged constructor indexes a plain-object table and hands back a Function, which would have been
stringified onto the send-keys line. An unrecognized mode yields the bare, safe command. The same
hole exists on the agent id (AgentId is open — custom agents carry user-typed ids), which is why
dialectFor looks its record up through Object.hasOwn too, and why flag + vocabulary are ONE record
per agent (APPROVAL_DIALECTS): the previous shape was a tableFor ternary plus a flagFor ternary
whose else branch was codex's flag, so a third agent added to the table and forgotten in the flag
would have emitted --ask-for-approval <a gemini-style value> — a failed launch from an edit that
looks complete.
--sandbox is deliberately untouched: it is a separate axis, and folding it in would widen
filesystem access invisibly.
6. Title, restart, and the --delete trap
The title is READ-ONLY, and that is why TITLE_READ_CAPABLE exists
Gemini names the conversation itself, through its own update_topic tool, so the name lives in
that call's arguments — not in a top-level transcript field (verified against the captured
fixture: no line parses to an object with a title). Measured, __fixtures__/gemini/session.jsonl
line 22:
"toolCalls":[{"name":"update_topic","args":{…,"title":"Test Environment Verified","summary":"…"}}]
pickGeminiTitle matches on the tool name, so a title argument belonging to some other tool can
never be mistaken for the session's name, and takes the last call within a line (a line can hold
several; the newest is the name). Ordering across lines is right for free: the backward scan takes the
newest matching line.
Two places, and NOT because of resume. The reader also walks $set.messages, and the reason
recorded here originally was wrong: it said a resume replays the prior history into that record, so a
pre-resume title would only be found nested inside it. Measured in gemini 0.54.4's bundle, a resume
appends to the same file and writes only {"$set":{"sessionId":…}} (:285453) — §3. A title set
before the resume is therefore still sitting in the file as a top-level update_topic line, and the
backward scan finds it with no fallback at all.
What $set.messages really is: an in-session history sync gemini writes whenever it rewrites the
conversation it holds in memory (:285852-285857), which its own reader treats as replacing the
history (:285303-285335). Since that record can be the newest thing in the file and does carry
messages, a title inside it is a title the session currently believes in — so the walk is kept as
defence, not as the resume path. It costs nothing (the needle pre-filter means non-$set lines
never reach it) and it cannot invent a name: it matches only update_topic, and a top-level line
after the sync still wins by the backward scan. Provenance is now plain — both shapes it walks are
measured in the capture ($set.messages at fixture line 2, toolCalls[].args.title at line 5); what
was composed was the story, not the shapes.
The read is a bounded tail (readSmallTail(p, TITLE_TAIL_BYTES), the same cap claude's title read
uses) of the path the context tail already tracks. Nothing scans. That path authority is created
per shell, so it reaches the router as an injected dep (AgentSessionNameDeps.geminiPathFor), and in
src/main/index.ts it is deliberately held in a let assigned when the tail is created and called
with ?. (:573-575) rather than closed over as a const declared 600 lines later: the later const
makes an early call a TDZ ReferenceError, and TerminalNode's poll does not catch its
readSessionName rejection — one throw kills that node's poll chain for the whole mount. A poll can
fire early, because sessionId is persisted in localStorage and a cold relaunch has one before any
hook arrives. Undefined-until-assigned degrades instead: no path, no name, next tick tries again.
There is no write leg. Gemini is in TITLE_READ_CAPABLE and not in RENAME_CAPABLE, so the
three /rename push sites stay claude+grok and the rename UI never lights on a node where the write
would silently do nothing.
Routing is not cosmetic: claude's resolver scans ~/.claude/projects on a cache miss, and a
gemini session id can never be found there — so an unrouted gemini node would pay that scan on every
poll (a mounted node polls every ~4 s until the name first resolves, and the mirror's sweep adds a
pass a minute) for a guaranteed null.
The sweep gate lives in core, not in the shells: startSessionNameSweep defaults its supports
dep to supportsTitleRead (= canReadTitle, core/session-name-sweep.ts:25), and neither shell
passes supports: any more. That is a deliberate de-duplication: both shells previously carried
their own copy of the gate, reverting both to canRename left the entire suite green while silently
skipping every gemini node, so the mirror and the phone would never see a gemini name. Same drift
class bit this branch three times (the remote installer's event lists, the grok raw-listener
block, this) and the fix each time was one definition in src/core.
In-place restart: /quit, and never --delete
EXIT_SEQUENCES.gemini = '/quit' (renderer/terminal/agent-restart.ts), measured from gemini's own
bundle/docs/reference/commands.md:325 (/quit, alias /exit). Adding it is what makes "Restart
agent (resume)" work on a gemini node: restartEligibility returns not-resumable for an agent with
no exit sequence, before it ever consults BUSY_STATES.
The value must stay BARE. The same command takes a --delete flag that exits and permanently
deletes the session's history and temporary files (commands.md:329-332) — the very conversation
the restart exists to resume. A dedicated test asserts the whole written stream contains no
--delete (agent-restart.test.ts, "never types the history-destroying --delete flag"), and
exitSequence('gemini') is separately asserted not.toContain('--delete').
Choreography is agent-agnostic: write KILL_LINE (Ctrl-U) then the exit line, poll
pane_current_command until a shell owns the pane, then echo-deliver resumeCommand. Nothing is
ever killed; a session that has not quit inside the timeout reports exit-timeout and keeps running.
A working or blocked node is refused. Unverified: that Ctrl-U is clear-line inside gemini's
TUI — the same assumption the module already carries for claude/codex/grok, and its cost if wrong is
one stray keystroke.
7. The three surfaces
| Feature | Desktop | Server Edition (browser) | Mobile (~/projects/nodeterm-ios) |
|---|---|---|---|
| Status hooks → badges, unread dot, notification | yes | yes — wireAgentStatus broadcasts the same normalized events |
yes, for free — the agent-status mirror threads agentId and is otherwise agent-agnostic |
Notification → NEEDS YOU (the fix this branch made) |
yes | yes, same normalizer | yes, via the mirror's needs-you edge |
| Hook installation | installGeminiHooks() at launch, plus the AGENT_TARGETS loop per SSH connect |
same core installer (core/agents/hooks/* is Electron-free) |
N/A — the phone installs nothing |
| Context meter | yes — geminiContextTail + the widened jail |
yes, wired identically in src/server/agent-status.ts (a rare case where the server got the feature in the same change) |
the mirror's per-node context ring gets it for free — pushContextUpdate feeds recordContextUsage in both shells |
context.ensure mount-time rehydration |
claude only, deliberately (readsClaudeTranscript) — a gemini node's meter fills on its first hook event after mount instead of instantly |
it has no server handler at all, so this was never reachable there | N/A |
| Session title read | yes | no — pre-existing gap, not a gemini one. ws-bridge.readSessionName returns '' (src/renderer/bridge/ws-bridge.ts:240): IPC.ptyReadSessionName has never been registered server-side, so claude's read leg is equally stubbed. The fix is to move the routing into core and register it from both shells, exactly as core/transcript-ipc.ts did for the ⌘M channels |
the mirror's session-name sweep runs in both shells and routes per agent (supportsTitleRead), so a gemini name reaches the phone |
| Rename write | N/A — gemini has no rename command (§6) | idem | idem |
| Permission mode | yes | yes (pure renderer + the flag) | follow-up owed — see §8 |
| In-place restart + cold-restore resume | yes | yes | N/A |
⌘M transcript view (ChatPanel) |
yes, local nodes (core/gemini-chat.ts); a remote (SSH) node says "not supported yet"; no plan/question answer cards and no composer model label (gemini's /model is an unmeasured dialog) |
yes — registerTranscriptIpc is core, and the server runs on the host whose sessions it reads |
yes over the relay (chat.page serves the desktop's parse; a remote node is "Could not read the transcript."); golden fixtures in src/shared/chat-fixtures/gemini/ for a direct-SSH Swift port |
| Find bar's transcript index | claude only (readsClaudeTranscript); the terminal-buffer search works normally |
idem | N/A |
| Context links | yes (CONTEXT_LINK_CAPABLE), marker block in ~/.gemini/GEMINI.md |
wired, local-only — src/server/context-link.ts calls initContextLink(pty, {}) with no remote deps |
N/A |
| Canvas control | yes, marker block + the sh+curl shim | not wired — agent:control has no server handler; pre-existing |
N/A — no canvas |
| Managed accounts | N/A — accounts are a claude config-dir mechanism; createAgentNode never stamps an accountId on a non-claude node, and CLAUDE_CONFIG_DIR is irrelevant to ~/.gemini/settings.json |
idem | idem |
| Working indicator | the brand mark, breathing — brandPulsePlan('gemini', …) returns the gemini-color.svg asset and it pulses with a bloom, on the canvas badge and in the notch strip. Before this branch gemini fell through to the plain dot, which says "something is happening" but not who |
N/A for the notch (there is none); the canvas badge works | the phone has its own SwiftUI renderer |
| Fullscreen TUI setting | N/A — claude-tui.ts writes claude's "tui": "fullscreen"; gemini has no analogue |
idem | idem |
| Deterministic hook-reply approvals (phone Approve/Deny) | claude only — pty-manager arms NODETERM_PERM_WAIT_SECS for claude alone, and gemini's Notification is explicitly observability-only (reference.md:284-285), so there is nothing to answer |
idem | a gemini node's approvals are not answerable from the phone |
| Kanban card + card modal | badges, the meter row and the 💬 comments panel all work (derived from the same nodes and the same status store) | same | the iOS board is a separate read/move mirror |
8. Known gaps and follow-ups
Gaps in what shipped — state them, do not paper over them:
- A DENIED tool may hold NEEDS YOU until the next prompt. On Cancel,
AfterToolnever fires (the Cancel branch returns before the call is even scheduled,chunk-YMKYUNCI.js:346153-346157) andfireAfterAgentHookSafeearly-returns whilependingToolCallsremain (chunk-YMKYUNCI.js:344652) — so the badge is cleared by the next turn'sBeforeAgent. Self-healing, and still strictly better than the pre-branch stuck RUNNING, but gemini has no idle rescue notification the way grok might. Measure it: deny a tool live and watch whether the badge clears (§9 item 5). autoandmanualare indistinguishable at launch (§5): gemini has no value forauto, so both emit no flag and land on gemini's own promptingdefault. Closed as far as honesty goes —modeSupportedis false and the derived copy says so — but the dropdown still offers two entries that do the same thing on gemini. Only a gemini-side "approve non-edit tools" value could separate them.- CLOSED, in the opposite direction — the
$set.messageswalk was documented as the resume mechanism and listed here as unverified. Measured in gemini 0.54.4's bundle: a resume appends to the same file and writes only{"$set":{"sessionId":…}}(chunk-TYAF55F7.js:285453), so nothing is replayed and a pre-resume title is still a top-levelupdate_topicline.$set.messagesis a routine in-session history sync (:285852-285857), which is why the never-resumed capture has one at line 2. The CODE is unchanged — the walk is harmless, free and defensive — but the story is fixed in §3, §6 andpickGeminiTitle's docblock, and the checklist item that told a tester to capture "the resumed transcript's$setshape" is gone: there is no such shape to capture. gemini --resume <id>is FATAL when the id does not resolve — measured here: exit 42,Error resuming session: Invalid session identifier "…"(and, from a directory with no chats at all,No previous sessions found for this project), so a cold-restore relaunch whose transcript has been deleted, or whose node runs in a different cwd than the one gemini indexed, dies instead of degrading to a baregemini. Not fixed here (the resume command is shared with claude/codex and the fallback belongs in the restore path, not in a docs pass).- A remote (SSH) gemini node has no meter and no title. The tails deliberately never track a
remote node's transcript — metering the local disk would report the wrong machine — and
geminiPathForthen answersundefined, which reads as "no name". Honest, but a real asymmetry: claude's leg handles remote viasetRemoteTranscriptReaderand a remote-jailed path. - FIXED — the search button's tooltip keyed on
showUsage, so a gemini/codex node offered "Search terminal + conversation" while its transcript leg was gated off. It now keys onclaudeTranscript, and the guard below covers the label too. - Nothing tests the call sites of
readsClaudeTranscript, behaviourally. No test in this repo rendersTerminalNodeorCanvas, so the gates are pinned by a source-text guard (src/renderer/nodes/title-gate.test.ts, in the style ofno-electron.test.ts), which now covers the CLAUDE-TRANSCRIPT gates as well as the two title gates —context.ensure, the find bar'ssearchTranscript, the tooltip, and the inverse mistake of narrowing the meter itself. Each was verified by mutation. The residual weakness is the technique's: it matches identifiers, not behaviour, so a rename that keeps the words satisfies it. The transcript assertions are scoped to the matching LINE (so a failure names the site instead of dumping 6000 lines as its diff); the older title assertions stilltoContainover the whole file, and the "Canvas.tsx must never mentioncanReadTitle" clause would still false-positive on a future legitimate read there. codexHome()returns$CODEX_HOMEunresolved, so a~/…or relative value still misses the jail — pre-existing, and identical tocodex-usage.ts's own behaviour. It fails closed (the meter silently never fills), which is the quieter and therefore worse failure.- The prefix-based jail admits a symlink planted inside an allowed root. Pre-existing for claude's roots; both new consumers turn the file into numbers, never raw bytes.
Follow-ups owed elsewhere:
~/projects/nodeterm-ios— the phone'sAgentLaunch.commandappends the permission-mode flag only for claude, so a gemini launch from the phone gets no flag (not a wrongly gated one), andMirrorSettings.autoSupportedstill has no agent dimension. Recorded from that repo indocs/grok-agent.md§8; not re-verified here — the iOS checkout is absent from this worktree, so treat the line references there as the last known state.- Per-agent
context.ensurerehydration — its own task, not a gate: teach it to resolve gemini's/codex's own transcripts (handoff/locate.tsalready haslocateGemini/locateCodexby sessionId) and route to the matching tail.
9. Gemini device checklist
Far shorter than grok's, because the CLI and a real transcript were both available here. These are the items that genuinely need a running session. Run them in a project with one gemini node, one claude node, and one SSH project.
Hooks + state machine
1. Start `gemini` in a node: does the RUNNING badge appear on the first prompt and clear at
the end of the turn? (BeforeAgent / AfterAgent reaching the hook server at all.)
2. Trigger a real tool-permission prompt. Does the badge switch to NEEDS YOU — i.e. is the live
payload's `notification_type` exactly "ToolPermission"? (Statically closed from the bundle's
one-member enum, so this is a confirmation, not an unknown.)
3. APPROVE it: the badge must go back to RUNNING (BeforeTool/AfterTool), then clear.
4. Run a turn under `--approval-mode yolo`: NO Notification should fire at all (an auto-approved
call never reaches notifyHooks). A NEEDS YOU here would mean the strobe grok had.
5. DENY a tool. Expected (§8.1): the badge may STAY on NEEDS YOU until the next prompt's
BeforeAgent clears it. Confirm, and record how bad it feels — that decides whether a rescue
is worth building.
6. `/clear` mid-session: SessionEnd + SessionStart both fire, the meter untracks and refills.
Context meter
7. Does the meter fill, and does its % move as the conversation grows? Compare against gemini's
own context readout in the TUI.
8. Does the popover name the GEMINI model (not "claude")? And on a fresh mount, does the meter
start EMPTY and fill on the first hook event (the deliberate loss of the head start, §1)?
9. Run a gemma model if you can reach one: the window must be 256k, not 1M.
Title
10. Let gemini name the conversation (it calls update_topic on its own), then check the node title
adopts it — and that a HAND rename stops the poll overwriting it (titleAuto=false).
11. RESUME that session (`gemini --resume <id>`) and check the title survives. It should, with no
$set walk involved: a resume appends to the SAME file (§3, §8.3), so the pre-resume top-level
`update_topic` line is still the newest one. (The item that used to sit here — "capture the
resumed transcript's $set shape" — is gone: measured, there is no such shape.)
12. Confirm there is no rename affordance offered on a gemini node.
Modes + restart
13. Launch each mode from Settings → Agents and confirm the emitted flag: manual ⇒ NO flag,
**auto ⇒ NO flag** (§5 — the one that matters, since `auto` is the default: a gemini session
started with the setting untouched must PROMPT before an edit, not auto-approve it),
acceptEdits ⇒ auto_edit, plan ⇒ plan, bypassPermissions ⇒ yolo. Check a session really STARTS in
it, not just that the flag parses.
14. On a machine with NO claude installed, launch gemini in `acceptEdits`: the `--approval-mode
auto_edit` flag must still be emitted (claude's version gate must not touch gemini). `auto` is
not the probe for this any more — it emits no flag on any machine (§5).
15. "Restart agent (resume)" on an idle gemini node: does it /quit, wait for the shell, and resume
the SAME conversation? Is it refused while the node is RUNNING or NEEDS YOU? Is the history
still there afterwards (i.e. `--delete` was never typed)?
16. Ctrl-U inside gemini's TUI: is it clear-line? (If not, one stray keystroke precedes /quit.)
SSH + surfaces
17. Connect an SSH project, then on the host: is our hook block in `~/.gemini/settings.json`, with
the SEVEN gemini event names (not claude's)? Do remote gemini badges work?
18. A remote gemini node has NO meter and NO title by design (§8.4) — confirm it degrades quietly
rather than showing a wrong number.
19. Server Edition in a browser: badges, NEEDS YOU, and the context meter must all work; the node
title will NOT adopt gemini's name (readSessionName is stubbed server-side, §7).
20. Phone: does a gemini node show the right state and a context ring? Its permission-mode flag is
missing on phone-side launches (§8).
21. macOS notch + canvas badge: does the gemini mark pulse and bloom, in BOTH themes? Its mark is a
gradient, so the `currentColor` bloom is the LABEL colour, not its own ink — the light theme is
where that will look worst if it looks bad anywhere.
22. Kanban card + card modal: badges, the meter row and the 💬 comments panel on a gemini card.
⌘M chat view
23. ⌘M on a gemini node after a few turns with tool calls: prompts, answers and ONE chip per call
with its output; no thoughts, no `<session_context>` preamble. A turn in progress fills in live.
24. `/compress` (or let it auto-compress), then ⌘M: the earlier turns are STILL there, followed by
"[info] Chat history compressed…", and no `<state_snapshot>` bubble appears as your words.
25. Esc a turn mid-stream: the cancelled prompt stays, followed by the cancel note.
26. `/rewind` to an earlier prompt: the rewound turns disappear from ⌘M. Then compress and rewind
again (the known limit: a rewind to a post-compression copy is ignored, so those turns stay).
27. `@file` a file in a prompt: the bubble shows what you typed, not the file's body.
28. Send from the ⌘M composer while gemini is idle: the text lands in gemini's prompt and submits
(bracketed paste into gemini's TUI); refused while RUNNING or NEEDS YOU.
29. An SSH project's gemini node: ⌘M says "Reading a remote Gemini session's transcript isn't
supported yet." with no Retry; the phone says "Could not read the transcript."
30. Phone Chat screen on a LOCAL gemini node over the relay: the same thread as ⌘M, the model
label under it.
31. Close a gemini node, reopen its transcript from "Recently closed": it reads.
Windows (hook wrapper + .cmd shims; nothing here has run on a device yet)
32. On Windows, start nodeterm once and open ~/.gemini/settings.json: every managed event holds ONE
entry, `C:\Windows\System32\cmd.exe /d /c call "<home>\.nodeterm\agent-hooks\gemini-hook.cmd "`,
and an older POSIX `if [ -r ...` entry is gone (replaced, not duplicated).
33. With Git for Windows installed, repeat items 1-3 under BOTH pwsh.exe and Windows PowerShell
(gemini picks pwsh.exe when present, else powershell.exe; ComSpec=powershell wins over both):
RUNNING appears and clears, a real permission prompt flips the badge to NEEDS YOU.
34. Rename/move Git out of the way (no sh.exe anywhere): a gemini turn still runs with no hook
error line in the TUI and the badge simply stays Unknown (the wrapper drains and exits 0).
35. In a gemini node run the canvas skill's line, `& "<userData>\canvas-control\nodeterm.cmd" list`,
and the context skill's `& "<userData>\context-links\context.cmd" list`: both answer. Then
`... open-terminal --cmd=--version` and a `--prompt "two words"` value arrive intact.
36. Draw a context link to a gemini node: the injected note names `context.cmd` with `& `, and
running it verbatim works.