Quick Start

Requirements

• Python 3.12+
• uv package manager (install)
• One provider credential. A ChatGPT Plus subscription (OAuth) or an Anthropic, OpenAI, or GLM API key is enough.

1. Install

The PyPI distribution is geode-agent. It installs two commands: geode and geode-mcp.

uv tool install geode-agent
geode version

To develop from a source checkout:

git clone https://github.com/mangowhoiscloud/geode.git
cd geode
uv sync
uv tool install -e . --force

2. Setup wizard

geode setup wires your credentials. It detects a ChatGPT subscription OAuth (~/.codex/auth.json) before asking for API keys. Keys you enter are saved to ~/.geode/auth.toml (see Auth and OAuth). For where the model choice and other settings are saved, see Configuration basics.

geode setup        # first-time setup
geode setup -r     # rerun credential setup; keeps existing credential files

3. First conversation

Running geode auto-starts the serve daemon and attaches a thin CLI over IPC. Free text goes inside this interactive screen. A shell one-shot likegeode "prompt" is not supported.

geode

> summarize today's AI research trends
> /model        # inspect and switch models
> /status       # daemon, MCP, credential state
> /quit

What success looks like

• The banner shows the version and model, and a dim "session cli-… · connected" line appears.
• Free text gets an answer that uses tools along the way.
• geode about reports the EFFECTIVE model you intended.

Common failure modes

Recovery toolkit

The sequence that gets you from a broken state back to a known one.

1. geode doctor. Python, PATH, credentials, and the daemon in one pass.
2. geode about. What model and paths are actually in effect.
3. geode config explain model. Where a setting is being masked.
4. pkill -f "geode serve", then re-enter. Fresh daemon.
5. geode setup -r. Reopens the credential wizard even when a working credential exists. It does not delete ~/.geode/.env, auth.toml, or the dry-run marker before entry. Only the provider whose key you enter successfully is replaced (a successful entry also clears the dry-run marker); cancelling or failing leaves those files as they were.

Update and uninstall

geode update                  # uv: latest patch; source: pull + rebuild
geode update --latest         # uv: explicitly allow minor/major upgrades

Published v1.0.27 does not include the new removal protections below. For a uv installation of that version, remove only the CLI with the original package manager and leave runtime and project data intact.

uv tool uninstall geode-agent # CLI only; keeps runtime and project data

Source checkout only — Unreleased. The procedure and preservation guarantees below apply to source installs containing PR #3295. Landing on main is separate from a PyPI release; the version string alone does not establish whether these protections are included.

geode uninstall --dry-run     # inspect targets and installation ownership
geode uninstall               # remove verified runtime data + uv CLI

Removal is limited to GEODE_HOME (default ~/.geode) and a verified uv tool installation. Project .geode/, source, virtual environments, and build caches are preserved.--keep-config leaves runtime .env,config.toml, and auth.toml in place;--keep-data keeps vault, identity, and user_profile. Other package managers and customized uv installs may require manual removal with the original package manager. A failed step returns a failure exit status; data already removed is not automatically restored.

Next

• Pick a path. Subscription, API key, or the free path.
• The two loops. The mental model the rest of the docs build on.
• Run as a daemon. The road to messaging and schedules.
• Optional: connect Google Workspace with a Google OAuth client you own.