Gemini Space
README.md
# Gemini Space
**[English](./README.md) · [简体中文](./README.zh-CN.md)**
[](https://github.com/cunninghamcard-bit/gemini-space/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org)
**Give Google Gemini Web (and its parallel Task subagents) your local machine—speaking the exact Antigravity (`agy`) tool surface Gemini was trained on.**
---
## Why Gemini Space?
Most local coding MCP servers (`Desktop Commander`, `DevSpace`, `Filesystem MCP`) were designed around ChatGPT / Codex (`exec_command`, `write_stdin`, `apply_patch`, `open_workspace`) or Claude Code. When you connect them to **Gemini Web (`gemini.google.com` → Custom Connectors)**, you hit two walls:
1. **Wrong tool distribution**: Gemini models are post-trained heavily on Google Antigravity's PascalCase tool surface (`read_file`, `write_file`, `edit_file`, `run_command`, `manage_task`) with absolute paths and zero `open_workspace` ceremony.
2. **Gemini Web Connector protocol quirks**:
- **Strict JSON Schema subset**: Connector registration fails (`"We had trouble connecting"`) if `inputSchema` contains `$schema`, `additionalProperties`, `$defs`, `const`, or >32-bit integer bounds.
- **~60s hard RPC timeout & no MCP `Tasks`**: Gemini Web declares MCP `2025-11-25` without `tasks` capability, ignores post-turn server push notifications, and kills any tool call exceeding ~60s (`DEADLINE_EXCEEDED`).
- **Parallel Task Subagents**: In **Gemini Task** mode, Gemini spawns multiple cloud subagents that simultaneously `initialize` against your `/mcp` endpoint. Without session isolation and concurrent refresh-token rotation grace, subagents either block each other past 60s, leak background task notices across agents, or trigger `401` token-rotation races.
**Gemini Space** is a lightweight, self-hosted MCP server built from the ground up around those exact constraints—with **zero closed-source binary dependencies** (only 6 runtime npm packages + Node's built-in `node:sqlite`).
---
## Key Features
- **5 Native Deterministic `agy` Tools (Pure Node.js)**
- `read_file`: 800-line / 46,080-byte paginated text reads with UTF-8 safe `ByteOffset` continuation + magic-byte multimodal inline blocks (`PNG`, `JPEG`, `GIF`, `WebP`, `PDF`, `MP3`, `WAV`, `MP4`).
- `write_file`: Automatic parent directory creation, `Overwrite`, and newline-aware `Append` while preserving file mode bits.
- `edit_file`: EOL-normalized (`LF` / `CRLF` / mixed) exact replacement across occurrences with LCS `(+A/-R lines)` diff summaries and per-file write locks.
- `run_command`: Real `80×24` PTY execution (`zsh -c`), inheriting your real `HOME` (`~/.ssh`, `~/.gitconfig`), ANSI stripping, and 10 KiB head/tail truncation with full output saved on disk.
- `manage_task`: `list`, `status`, `send_input` (interactive PTY stdin), and orphan-free process-group + descendant `SIGKILL` (`kill`).
- **45-Second Smart Hold (Bridging Gemini's 60s Ceiling)**
- Non-daemon `run_command` calls automatically hold on the server for up to **45s**—commands under 45s finish in **one round trip**.
- Commands exceeding 45s return a `TaskId`; each `manage_task(Action: "status")` call holds up to another **45s** until completion, preserving the real exit code and output.
- **Built for Gemini Task Multi-Subagent Concurrency**
- Issues soft `Mcp-Session-Id` headers on `initialize` (`1 Gemini Subagent ↔ 1 isolated task/notice queue`), executes commands across subagents truly in parallel, and never `404`s stale sessions across local server restarts.
- **Code Mode (`execute` / `poll_execution` / `cancel_execution`)**
- Run an async JavaScript snippet on your machine calling `tools.read_file`, `tools.edit_file`, `tools.run_command` in loops or `Promise.all`—collapsing 20+ operations into a **single Gemini tool call**.
- **Automatic Local Skills Injection**
- Scans `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`, and `~/.devspace/skills` (`SKILL.md`) into MCP `instructions` (injected directly into Gemini Web's system prompt).
- **OAuth 2.1 + `/web/` Activity Dashboard**
- Single-owner password approval page, SHA-256 hashed SQLite token store with a **300-second refresh-token rotation grace window**, built-in Gemini Schema sanitizer, and a zero-build `/web/` UI to inspect every subagent session and tool call.
---
## Architecture
```mermaid
flowchart LR
subgraph Gemini Web / Gemini Task
SA1["Main Agent / Subagent A\n(Mcp-Session-Id: S1)"]
SA2["Subagent B\n(Mcp-Session-Id: S2)"]
end
Tunnel["HTTPS Tunnel\n(Tailscale Funnel / Cloudflare)"]
subgraph Gemini Space (Local Mac / Linux)
Auth["OAuth 2.1 + 300s Refresh Grace\n+ Gemini Schema Sanitizer"]
Router["Soft Session Router\n(S1 / S2 Isolated Queues)"]
Engine["Deterministic AGY Engine\n(80x24 PTY · 45s Hold · Multimodal FS)"]
CM["Code Mode VM\n(execute / poll / cancel)"]
Web["/web/ Activity UI"]
end
SA1 & SA2 -- "HTTPS POST /mcp" --> Tunnel --> Auth --> Router
Router --> Engine & CM
Router -. "SQLite audit" .-> Web
```
---
## 5-Minute Quickstart
### 1. Prerequisites
- **Node.js `>= 22.19`** (uses built-in `node:sqlite`) and `pnpm`
- macOS or Linux
- An HTTPS tunnel pointing to your local port `7676` (e.g., **Tailscale Funnel** or **Cloudflare Tunnel**)
### 2. Clone & Build
```bash
git clone https://github.com/cunninghamcard-bit/gemini-space.git
cd gemini-space
pnpm install
pnpm build
```
### 3. Initialize & Start Tunnel
```bash
# Expose local port 7676 over HTTPS (example using Tailscale Funnel):
tailscale funnel --bg 7676
# Initialize ~/.devspace/config.jsonc and generate your Owner Password in ~/.devspace/auth.json:
./bin/gemini-space.js init --public-url https://your-machine.your-tailnet.ts.net
# Verify everything is ready:
./bin/gemini-space.js doctor
# Start the server:
./bin/gemini-space.js serve
```
> **Tip:** Your generated Owner Password is saved in `~/.devspace/auth.json` (`ownerToken`). You will enter it once when authorizing Gemini Web or signing into `https://<your-host>/web/`.
### 4. Connect to Google Gemini Web
1. Open **[gemini.google.com/customize/connectors](https://gemini.google.com/customize/connectors)** → click **+ Custom**.
2. Enter your MCP Server URL:
```text
https://your-machine.your-tailnet.ts.net/mcp
```
*(Leave Client ID / Secret blank — Gemini Space supports dynamic OAuth client registration.)*
3. Approve the connection using your **Owner Password** from `~/.devspace/auth.json`.
4. Open a chat (or **Gemini Task**) and start coding directly against your local repositories!
> ⚠️ **Important Google Connector Caveat:** Google binds custom connectors by **hostname** (`*.your-tailnet.ts.net`). Do **not** register a second test connector on the same hostname (even on a different port like `:8443`), or Google will overwrite/revoke the shared OAuth account link. Always use a separate hostname (e.g., `*.trycloudflare.com`) if testing another MCP server alongside production.
---
## Running as a Background Service (`launchd` on macOS)
Create `~/Library/LaunchAgents/dev.gemini-space.server.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>dev.gemini-space.server</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/node</string>
<string>--import</string>
<string>/ABSOLUTE/PATH/TO/gemini-space/bin/silence-sqlite-warning.js</string>
<string>/ABSOLUTE/PATH/TO/gemini-space/dist/cli.js</string>
<string>serve</string>
</array>
<key>WorkingDirectory</key><string>/ABSOLUTE/PATH/TO/gemini-space</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME</key><string>/Users/YOUR_USERNAME</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.out.log</string>
<key>StandardErrorPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.err.log</string>
</dict>
</plist>
```
Load it:
```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.gemini-space.server.plist
```
---
## Configuration (`~/.devspace/config.jsonc`)
```jsonc
{
"configVersion": 1,
"server": {
"host": "127.0.0.1",
"port": 7676,
"publicBaseUrl": "https://your-machine.your-tailnet.ts.net"
},
"agy": {
"workspace": "~",
"holdMs": 45000,
"exposedTools": ["read_file", "write_file", "edit_file", "run_command", "manage_task"]
},
"codeMode": {
"enabled": true
},
"skills": {
"enabled": true,
"paths": []
},
"ui": {
"enabled": true
},
"activity": {
"enabled": true,
"maxCalls": 500
},
"oauth": {
"refreshTokenGraceSeconds": 300
}
}
```
---
## CLI Reference
```bash
gemini-space serve # Start OAuth + MCP + /web/ server
gemini-space doctor # Verify config, OAuth DB, discovered skills & tools
gemini-space init --public-url <https> # Initialize config.jsonc and Owner Password
gemini-space config show # Print resolved configuration
gemini-space config set codeMode.enabled false
```
---
## Acknowledgements & License
Originally forked from [@waishnav/devspace](https://github.com/Waishnav/devspace) for its clean OAuth 2.1 SQLite foundation, then stripped of ~79k lines of legacy surfaces and rebuilt around a pure Node.js deterministic Antigravity tool engine tailored for Google Gemini Web.
Licensed under the [MIT License](./LICENSE).
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues