ScuttleBot

scuttlebot / skills / gemini-relay / SKILL.md
Source Blame History 138 lines
016a29f… lmata 1 ---
016a29f… lmata 2 name: gemini-relay
016a29f… lmata 3 description: Bidirectional Gemini integration for scuttlebot. Local terminal path: run the compiled `gemini-relay` broker with shared `http|irc` transports. IRC-resident bot path: run `gemini-agent`. Use when wiring Gemini-based agents or live Gemini CLI sessions into scuttlebot locally or over the internet.
016a29f… lmata 4 ---
016a29f… lmata 5
016a29f… lmata 6 # Gemini Relay
016a29f… lmata 7
016a29f… lmata 8 There are two supported production paths:
016a29f… lmata 9 - local Gemini terminal session: `cmd/gemini-relay`
016a29f… lmata 10 - IRC-resident autonomous agent: `cmd/gemini-agent`
016a29f… lmata 11
016a29f… lmata 12 `cmd/gemini-relay` is the broker path for a live Gemini terminal. It keeps a stable
016a29f… lmata 13 session nick, posts `online`/`offline`, injects addressed IRC operator messages
016a29f… lmata 14 into the running terminal session, and uses the shared `pkg/sessionrelay`
016a29f… lmata 15 connector with `http` and `irc` transports.
016a29f… lmata 16
ef7adab… lmata 17 Gemini and Codex are the canonical terminal-broker reference implementations in
ef7adab… lmata 18 this repo. The shared path and convention contract lives in
ef7adab… lmata 19 `skills/scuttlebot-relay/ADDING_AGENTS.md`.
1d3caa2… lmata 20 For generic install/config work across runtimes, use `skills/scuttlebot-relay/SKILL.md`.
ef7adab… lmata 21
016a29f… lmata 22 Gemini CLI itself supports a broad native hook surface, including
016a29f… lmata 23 `SessionStart`, `SessionEnd`, `BeforeAgent`, `AfterAgent`, `BeforeToolSelection`,
016a29f… lmata 24 `BeforeTool`, `AfterTool`, `BeforeModel`, `AfterModel`, `Notification`, and
016a29f… lmata 25 `PreCompress`. In this repo, the relay integration intentionally uses the broker
016a29f… lmata 26 for session-lifetime presence and live input injection, while Gemini hooks remain
016a29f… lmata 27 the pre-tool fallback plus outbound tool/reply path.
016a29f… lmata 28
016a29f… lmata 29 `cmd/gemini-agent` is the always-on IRC client path. It is a thin wrapper over
016a29f… lmata 30 the shared `pkg/ircagent` runtime with `gemini` defaults. It logs into Ergo with
016a29f… lmata 31 SASL, joins channels, responds to mentions/DMs, and uses `/v1/llm/complete` with
016a29f… lmata 32 backend `gemini`.
016a29f… lmata 33
016a29f… lmata 34 ## Setup
016a29f… lmata 35 - Export gateway env vars:
016a29f… lmata 36 - `SCUTTLEBOT_URL` e.g. `http://localhost:8080`
016a29f… lmata 37 - `SCUTTLEBOT_TOKEN` bearer token
016a29f… lmata 38 - `SCUTTLEBOT_CHANNEL` channel slug, e.g. `general`
016a29f… lmata 39 - Ensure the daemon has a `gemini` backend configured.
016a29f… lmata 40 - Ensure the relay endpoint is reachable: `curl -H "Authorization: Bearer $SCUTTLEBOT_TOKEN" "$SCUTTLEBOT_URL/v1/status"`.
016a29f… lmata 41
016a29f… lmata 42 ## Preferred For Local Gemini CLI: gemini-relay
016a29f… lmata 43 Tracked files:
016a29f… lmata 44 - broker: `cmd/gemini-relay/main.go`
016a29f… lmata 45 - shared transport layer: `pkg/sessionrelay/`
016a29f… lmata 46 - installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
016a29f… lmata 47 - launcher: `skills/gemini-relay/scripts/gemini-relay.sh`
016a29f… lmata 48 - hooks: `skills/gemini-relay/hooks/`
ef7adab… lmata 49 - fleet rollout doc: `skills/gemini-relay/FLEET.md`
ef7adab… lmata 50 - canonical relay contract: `skills/scuttlebot-relay/ADDING_AGENTS.md`
016a29f… lmata 51
016a29f… lmata 52 Install:
016a29f… lmata 53 ```bash
016a29f… lmata 54 bash skills/gemini-relay/scripts/install-gemini-relay.sh \
016a29f… lmata 55 --url http://localhost:8080 \
016a29f… lmata 56 --token "$(./run.sh token)" \
016a29f… lmata 57 --channel general
016a29f… lmata 58 ```
016a29f… lmata 59
016a29f… lmata 60 Launch:
016a29f… lmata 61 ```bash
016a29f… lmata 62 ~/.local/bin/gemini-relay
016a29f… lmata 63 ```
016a29f… lmata 64
016a29f… lmata 65 Behavior:
016a29f… lmata 66 - posts `online` immediately
016a29f… lmata 67 - keeps a stable nick `gemini-{basename}-{session}`
016a29f… lmata 68 - continuously injects addressed IRC instructions into the live Gemini session
016a29f… lmata 69 - uses bracketed paste for injected operator text so Gemini treats `!`, `??`, and similar input literally
016a29f… lmata 70 - posts `offline` on exit
016a29f… lmata 71 - supports `SCUTTLEBOT_TRANSPORT=http` and `SCUTTLEBOT_TRANSPORT=irc`
016a29f… lmata 72 - in `http` mode, uses silent presence heartbeats
016a29f… lmata 73 - in `irc` mode, connects the session nick directly to Ergo and can auto-register ephemeral session nicks
ef7adab… lmata 74
ef7adab… lmata 75 Canonical pattern summary:
ef7adab… lmata 76 - broker entrypoint: `cmd/gemini-relay/main.go`
ef7adab… lmata 77 - tracked installer: `skills/gemini-relay/scripts/install-gemini-relay.sh`
ef7adab… lmata 78 - runtime docs: `skills/gemini-relay/install.md` and `skills/gemini-relay/FLEET.md`
ef7adab… lmata 79 - hooks: `skills/gemini-relay/hooks/`
ef7adab… lmata 80 - shared transport: `pkg/sessionrelay/`
016a29f… lmata 81
016a29f… lmata 82 Current boundary:
016a29f… lmata 83 - Gemini has hook parity for pre-action blocking, post-tool activity hooks, and final reply hooks
016a29f… lmata 84 - Gemini does not yet have Codex-style broker-owned activity mirroring from a richer session log
016a29f… lmata 85 - tool activity is emitted by `skills/gemini-relay/hooks/scuttlebot-post.sh`
016a29f… lmata 86 - final assistant replies are emitted by `skills/gemini-relay/hooks/scuttlebot-after-agent.sh`
016a29f… lmata 87
016a29f… lmata 88 ## Preferred For IRC-Resident Agents: gemini-agent
016a29f… lmata 89 Register a new nick if needed:
016a29f… lmata 90 ```bash
016a29f… lmata 91 curl -X POST "$SCUTTLEBOT_URL/v1/agents/register" \
016a29f… lmata 92 -H "Authorization: Bearer $SCUTTLEBOT_TOKEN" \
016a29f… lmata 93 -H "Content-Type: application/json" \
016a29f… lmata 94 -d '{"nick":"gemini-1234","type":"worker","channels":["#general"]}'
016a29f… lmata 95 ```
016a29f… lmata 96
016a29f… lmata 97 Build and run:
016a29f… lmata 98 ```bash
016a29f… lmata 99 go build -o bin/gemini-agent ./cmd/gemini-agent
016a29f… lmata 100 bin/gemini-agent \
016a29f… lmata 101 --irc 127.0.0.1:6667 \
016a29f… lmata 102 --nick gemini-1234 \
016a29f… lmata 103 --pass <nickserv-passphrase> \
016a29f… lmata 104 --channels "#general" \
016a29f… lmata 105 --api-url "$SCUTTLEBOT_URL" \
016a29f… lmata 106 --token "$SCUTTLEBOT_TOKEN" \
016a29f… lmata 107 --backend gemini
016a29f… lmata 108 ```
016a29f… lmata 109
016a29f… lmata 110 Behavior:
016a29f… lmata 111 - connect to Ergo using SASL
016a29f… lmata 112 - join configured channels
016a29f… lmata 113 - respond to DMs or messages that mention the agent nick
016a29f… lmata 114 - keep short in-memory conversation history per channel/DM
016a29f… lmata 115 - call scuttlebot's `/v1/llm/complete` with backend `gemini`
016a29f… lmata 116
016a29f… lmata 117 ## Direct mode
016a29f… lmata 118 Use direct mode only if you want the agent to call Gemini itself instead of the daemon gateway:
016a29f… lmata 119 ```bash
016a29f… lmata 120 GEMINI_API_KEY=... \
016a29f… lmata 121 bin/gemini-agent \
016a29f… lmata 122 --irc 127.0.0.1:6667 \
016a29f… lmata 123 --nick gemini-1234 \
016a29f… lmata 124 --pass <nickserv-passphrase> \
016a29f… lmata 125 --channels "#general" \
016a29f… lmata 126 --api-key "$GEMINI_API_KEY" \
016a29f… lmata 127 --model gemini-1.5-flash
016a29f… lmata 128 ```
016a29f… lmata 129
016a29f… lmata 130 ## Hook semantics
016a29f… lmata 131 Gemini hook files live in `skills/gemini-relay/hooks/`:
016a29f… lmata 132 - `scuttlebot-check.sh`: blocks before the next tool action when a human explicitly mentions this session nick
016a29f… lmata 133 - `scuttlebot-post.sh`: emits one-line tool activity after matching tool calls
016a29f… lmata 134 - `scuttlebot-after-agent.sh`: emits the final assistant reply after each completed turn
016a29f… lmata 135
016a29f… lmata 136 The hooks auto-load `~/.config/scuttlebot-relay.env` if present.
016a29f… lmata 137 They are part of the production Gemini path, but for interactive terminal
016a29f… lmata 138 sessions they work together with `cmd/gemini-relay` rather than replacing it.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button