@raylin01/gemini-client

Node.js client for Gemini CLI with both the raw stream-json event API and a higher-level structured session/turn API.

Install

npm install @raylin01/gemini-client

Requirements

• Node.js 18+
• Gemini CLI installed and authenticated

Quickstart

import { GeminiClient } from '@raylin01/gemini-client';

const client = await GeminiClient.init({
  cwd: process.cwd(),
  outputFormat: 'stream-json'
});

const turn = client.send('Summarize this repository.');

for await (const update of turn.updates()) {
  if (update.kind === 'output' && update.snapshot.currentOutputKind === 'text') {
    process.stdout.write(update.snapshot.text);
  }
}

const completed = await turn.done;
console.log('\nSession:', completed.sessionId);

const next = client.send('Now propose 3 refactors.');
console.log('Status:', (await next.done).status);

await client.close();

Structured API

• GeminiClient.init(options) starts the CLI and returns a StructuredGeminiClient
• client.send(input, options?) returns a turn handle immediately
• turn.current(), turn.history(), turn.updates(), and turn.done expose normalized state
• client.getCurrentTurn() and client.getHistory() expose session-level state

Raw Event API

If you need direct access to the Gemini stream-json protocol, the original new GeminiClient(...) API is unchanged.

Event Model

• ready: session established with sessionId
• event: raw stream-json event
• message_delta: assistant token deltas
• tool_use, tool_result: tool lifecycle
• result: run completion
• error_event: structured Gemini warning/error event
• stderr, stdout, exit

API

new GeminiClient(options)

• cwd, geminiPath, env, args
• model, outputFormat, approvalMode, yolo
• sandbox/tool include options

await GeminiClient.init(options)

• returns a StructuredGeminiClient
• keeps the original raw client available at client.raw

Core methods

• startSession(prompt, runOptions?)
• continueSession(prompt, runOptions?)
• sendMessage(prompt, runOptions?)
• interrupt(signal?)
• shutdown()

Session helpers

• listSessions()
• resolveSession(identifier)
• deleteSession(identifier)

And utility subpath export:

• @raylin01/gemini-client/sessions

Session Browser Examples

Gemini sessions can be browsed with the read-only helpers exported from the sessions subpath.

import {
  listGeminiSessionSummaries,
  readGeminiSessionRecord
} from '@raylin01/gemini-client/sessions';

const summaries = await listGeminiSessionSummaries({
  projectPath: process.cwd()
});

const latest = summaries[0];
if (latest) {
  const record = await readGeminiSessionRecord(latest.id, {
    projectPath: process.cwd()
  });

  console.log('Title:', record.summary.summary);
  console.log('Normalized messages:', record.transcript.length);
  console.log('Raw event count:', record.rawMessages.length);
}

Use record.transcript when you want provider-neutral history, and record.rawSession or record.rawMessages when you need Gemini-native details.

Examples

See /examples:

• basic.ts
• events.ts
• error-handling.ts

Troubleshooting

• Use stream-json output for robust structured integration.
• If no sessions are found, verify ~/.gemini/tmp/<project-hash>/chats exists.

Versioning

This package uses independent semver releases.

Used by DisCode

DisCode uses this package as a real-world integration example:

• raylin01/DisCode

License

ISC