GroundFetch

GroundFetch

Lightweight grounded web search for coding agents.

GroundFetch calls grounded search providers and returns compact JSON results with source titles and URLs. It supports Gemini generateContent, Antigravity's Cloud Code PA wrapper, and Grok's Responses API. It is designed for agent workflows that want source-backed web lookup without keeping an MCP server loaded.

Install

git clone https://github.com/clavulin/groundfetch.git
cd groundfetch
python3 -m pip install .

Or run directly from the checkout:

python3 -m groundfetch --query "OpenAI models official docs" --limit 5

If you are asking Codex to install from just the repository URL, paste this:

Install GroundFetch from https://github.com/clavulin/groundfetch for this user.
Clone the repo if needed, install it with Python, symlink `skills/groundfetch`
into `~/.codex/skills/groundfetch`, and verify `groundfetch --help` works.
Do not invent credentials; if configuration is missing, report the exact
`GROUNDFETCH_*` variables needed from README.md.

If you are asking Claude Code to install from just the repository URL, paste this:

Install GroundFetch from https://github.com/clavulin/groundfetch for this user.
Clone the repo if needed and install it with Python. Copy `skills/groundfetch`
into `~/.claude/skills/groundfetch` (copy, do not symlink), then delete the
Codex-only `agents/openai.yaml` from that copy so only the Claude-relevant skill
files are installed. Verify `groundfetch --help` works. Do not invent
credentials; if configuration is missing, report the exact `GROUNDFETCH_*`
variables needed from README.md.

Configure

GroundFetch only reads GROUNDFETCH_* settings.

Create ~/.config/groundfetch/.env:

GROUNDFETCH_API_KEY=...
GROUNDFETCH_MODEL=gemini-3.1-flash-lite

GroundFetch supports two kinds of authentication:

1. API keys — a Gemini API key (above), or a Grok (xAI) API key.
2. Read OAuth files — existing Antigravity (agy) and Grok CLI auth files created by those tools' own login flows. GroundFetch reads them; it never runs a login flow itself.

Optional settings:

GROUNDFETCH_PROVIDER=gemini
# Run multiple providers concurrently and merge/dedupe results by URL:
# GROUNDFETCH_PROVIDERS=gemini,grok
GROUNDFETCH_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GROUNDFETCH_TIMEOUT=30
GROUNDFETCH_USER_AGENT=groundfetch/0.1

Antigravity auth (read OAuth file)

GroundFetch reads existing Antigravity OAuth auth JSON files compatible with CLIProxyAPI and sends requests to Antigravity's Cloud Code PA v1internal:generateContent endpoint instead of the standard Gemini API. It does not run an Antigravity login itself — create the auth file with CLIProxyAPI (or another Antigravity login tool), then point GroundFetch at it:

GROUNDFETCH_PROVIDER=antigravity
GROUNDFETCH_ANTIGRAVITY_AUTH_FILE=~/.cli-proxy-api/[email protected]
GROUNDFETCH_MODEL=gemini-3-pro

Optional Antigravity settings:

GROUNDFETCH_ANTIGRAVITY_BASE_URL=https://daily-cloudcode-pa.googleapis.com,https://cloudcode-pa.googleapis.com
GROUNDFETCH_ANTIGRAVITY_USER_AGENT=antigravity/2.0.11 darwin/arm64
GROUNDFETCH_ANTIGRAVITY_CLIENT_ID=your-google-oauth-client-id
GROUNDFETCH_ANTIGRAVITY_CLIENT_SECRET=your-google-oauth-client-secret

GroundFetch uses the stored Antigravity access token directly. The client id and secret are required only for refreshing an expired access token with the stored refresh_token. It discovers project_id via loadCodeAssist when missing and falls back to onboardUser for first-use accounts.

Grok auth

GroundFetch authenticates Grok in two ways.

Read the Grok CLI login (OAuth file). Run grok login first; the CLI stores session credentials in ~/.grok/auth.json. GroundFetch reads the active https://auth.x.ai::<uuid> entry, uses its key as a bearer token, and checks expires_at. Expired Grok tokens are not refreshed by GroundFetch; run grok login again.

GROUNDFETCH_PROVIDER=grok
GROUNDFETCH_GROK_AUTH_FILE=~/.grok/auth.json
GROUNDFETCH_GROK_BASE_URL=https://cli-chat-proxy.grok.com/v1
GROUNDFETCH_GROK_MODEL=grok-build
GROUNDFETCH_GROK_USER_AGENT=grok-cli/0.2.54
GROUNDFETCH_GROK_CLIENT_VERSION=0.2.54

Use a Grok (xAI) API key. When GROUNDFETCH_GROK_API_KEY is set, GroundFetch sends a bearer-token request and skips the auth file. The base URL defaults to https://api.x.ai/v1 (override with GROUNDFETCH_GROK_BASE_URL); set GROUNDFETCH_GROK_MODEL to a model your key can use.

GROUNDFETCH_PROVIDER=grok
GROUNDFETCH_GROK_API_KEY=xai-...
GROUNDFETCH_GROK_MODEL=grok-4