gemini-code-adapter

A Paperclip adapter that integrates Gemini CLI as an autonomous AI agent runtime, analogously to the built-in Claude Code adapter.

Overview

This adapter enables Paperclip to orchestrate Google's Gemini CLI as a coding agent. It handles prompt construction, token usage reporting, and environment validation.

Gemini CLI enters headless mode automatically when spawned without a TTY (as Paperclip does), so no additional flags are required for unattended operation.

Prerequisites

• Node.js 18 or later
• Gemini CLI installed and available on PATH:

  npm install -g @google/gemini-cli

• A Gemini API key — set as GEMINI_API_KEY (or GOOGLE_API_KEY)
• A running Paperclip instance

Installation

Build the adapter:

cd /path/to/gemini-code-adapter
pnpm install   # or: bun install
pnpm build     # or: bun run build

Register it with Paperclip by adding the path to ~/.paperclip/adapter-plugins.json:

["/path/to/gemini-code-adapter"]

Restart Paperclip to load the adapter.

Agent Configuration

Create an agent in the Paperclip UI under Settings → Agents, selecting Gemini Code (local) as the adapter type.

Field	Type	Default	Description
cwd	string	process cwd	Absolute working directory for the agent process
model	string	gemini-2.5-flash	Model identifier
timeoutSec	number	0 (no limit)	Maximum run duration in seconds
graceSec	number	20	SIGTERM grace period in seconds
extraArgs	string[]	—	Additional arguments forwarded verbatim to the CLI
env	object	—	Environment variables injected into the agent process
command	string	gemini	Override the CLI binary name or path
promptTemplate	string	built-in	Handlebars-style prompt template

Supported Models

• gemini-2.5-flash (default — fast and balanced)
• gemini-2.5-pro
• gemini-2.5-flash-lite
• gemini-2.0-flash

Example Configuration

{
  "cwd": "/path/to/project",
  "model": "gemini-2.5-pro",
  "timeoutSec": 600,
  "graceSec": 30,
  "env": {
    "GEMINI_API_KEY": "AIza..."
  }
}

How It Works

On each heartbeat, Paperclip calls the adapter's execute function. The adapter:

1. Resolves the working directory and builds the runtime environment.
2. Constructs a prompt from the configured template, session handoff notes, and wake context.
3. Spawns Gemini CLI with --output-format json (headless mode activates automatically).
4. Parses the JSON output to extract the response content and token usage.
5. Returns the result to Paperclip.

Unlike Claude Code or Qwen Code, Gemini CLI does not support native session resume — each heartbeat starts a fresh context. Use the promptTemplate and Paperclip's session handoff mechanism to maintain continuity across runs.

Environment Validation

Run the environment test from Settings → Adapters in the Paperclip UI. The test verifies:

• Working directory exists and is accessible
• Gemini CLI is on PATH and executable
• At least one API key is present (GEMINI_API_KEY or GOOGLE_API_KEY)
• A live hello-probe (--prompt "Respond with hello") completes successfully

Project Structure

src/
├── index.ts           # Adapter metadata and model list
├── utils.ts           # Pure utility functions (also unit-tested)
└── server/
    ├── index.ts       # Factory function (createServerAdapter)
    ├── execute.ts     # Core execution logic
    └── test.ts        # Environment validation

Development

The project works with both pnpm and Bun.

# pnpm
pnpm install     # Install dependencies
pnpm build       # Compile TypeScript
pnpm typecheck   # Type-check without emitting
pnpm test        # Run unit tests (vitest)
pnpm test:watch  # Run tests in watch mode
pnpm clean       # Remove dist/

# Bun
bun install      # Install dependencies
bun run build    # Compile TypeScript
bun run typecheck
bun run test     # Run unit tests via vitest
bun test         # Run unit tests via Bun's native runner
bun run clean

Running Tests

Unit tests cover all pure utility functions in src/utils.ts and require no external services or mocks. They run identically under both vitest and Bun's native test runner:

pnpm test   # or: bun run test   (vitest)
bun test    # Bun native runner

Troubleshooting

"Command is not executable" — Install Gemini CLI (npm install -g @google/gemini-cli) and verify which gemini resolves correctly.

"API authentication is not ready" — Set GEMINI_API_KEY in your shell environment or in the agent's env configuration field. You can obtain a key from Google AI Studio.

Agent times out — Increase timeoutSec, or test manually with gemini --output-format json --prompt "Respond with hello" to check responsiveness.

No session continuity — Gemini CLI does not support --resume. Configure a meaningful promptTemplate and rely on Paperclip's session handoff notes to carry context between heartbeats.

License

MIT — see LICENSE.