GEODE

Prerequisites — what you need first

<details> <summary><strong>Don't know what these are?</strong> Click here for a 1-line explainer of each.</summary>

• Python 3.12+ — the language GEODE is written in. Most laptops don't have a recent enough version. Install from python.org/downloads (download the macOS or Windows installer, click through).
• Git — how you copy GEODE's source code from GitHub. Mac: comes with Xcode Command Line Tools (xcode-select --install). Windows: git-scm.com installer.
• uv — a fast Python package manager (replaces pip). One-line install: copy the curl command below into Terminal/PowerShell.

If any of these fail, see Troubleshooting below. </details>

Setup in 5 minutes

Step 1 — Install GEODE

GEODE's PyPI distribution is geode-agent. It installs the geode command.

uv tool install geode-agent
geode version

If the current release has not been published to PyPI yet, or you are developing GEODE itself, install from source instead:

git clone https://github.com/mangowhoiscloud/geode.git
cd geode
uv sync                              # installs dependencies (~30s)
uv tool install -e . --force         # makes `geode` available everywhere

Step 2 — Run the setup wizard

geode setup

The wizard offers three paths: ChatGPT subscription (auto-detects codex auth login if you've already done it), API key (paste and go), or skip into dry-run mode for now. Pick whichever fits.

If you already ran codex auth login before installing GEODE, you can skip this step entirely — the next geode invocation will detect the token and start.

Uninstalling

geode uninstall removes GEODE runtime data, stops the daemon, and removes the geode-agent uv tool install. Preview first if you want to see exactly what would be removed:

geode uninstall --dry-run
geode uninstall

If you only want to remove the PyPI-installed CLI and keep runtime data under ~/.geode/, use uv directly:

uv tool uninstall geode-agent

Useful partial removal modes:

geode uninstall --keep-config   # keep .env and config.toml
geode uninstall --keep-data     # keep vault, identity, and user profile data
geode uninstall --force         # skip confirmations for automation

Verify removal:

which geode               # should print nothing
uv tool list | grep geode # should not list geode-agent
pgrep -f "geode serve"    # should print nothing

---

Optional — Hook into Slack / Discord / Telegram

Once GEODE works in your terminal, you can let it answer on the messaging channels you already use:

geode serve                          # starts the always-on Gateway daemon

Configure channel bindings in .geode/config.toml (Slack bot token, Discord webhook, etc.). See docs/setup.md → Gateway for the full setup. After that, mentioning the bot in a channel routes the message into the same agent loop you use locally.

Optional — Self-improving loop config (`~/.geode/config.toml`)

Tune the autoresearch / seed-generation / petri audit drivers — model picks, dim set, banner thresholds, PAYG fallback policy — by copying the [self_improving_loop.*] sections from docs/examples/self_improving_loop.config.toml.example into ~/.geode/config.toml. Absent sections fall back to documented defaults. To migrate per-role entries from the legacy ~/.geode/petri.toml:

geode config migrate-petri-toml          # dry-run preview
geode config migrate-petri-toml --yes    # append [self_improving_loop.petri.*] to config.toml

---

Step 3 — Pick a path (manual reference)

The wizard above covers everything below; this section exists as a manual reference for what each path actually does.

---

Path A — ChatGPT subscription (the recommended path for OpenAI users)

Codex CLI signs you in once. GEODE picks up the token from ~/.codex/auth.json and uses it for every call. Your subscription pays the bill; nothing extra to set up.

brew install codex                    # macOS  (or: npm install -g @openai/codex)
codex auth login                      # opens a browser; sign in with your ChatGPT account
geode                                 # done. GEODE finds the token automatically.

Plans that work (per the official Codex CLI docs): Plus, Pro, Business, Edu, Enterprise.

Quotas (OpenAI-published, per 5-hour window): roughly 15–80 messages on Plus, up to 1,600 on Pro 20x. Edu and Enterprise have no fixed cap; usage scales with your workspace credits. Your admin needs to flip "Allow members to use Codex Local" before sign-in works on those tiers.

Tier notes: - gpt-5.5 is subscription-only. API-key users (Path B) top out at gpt-5.4. If you want 5.5, you need ChatGPT. - ChatGPT Team is not currently supported by Codex CLI. Team users should use Path B. - Free / Go appear on OpenAI's pricing page but aren't listed in the CLI README. Treat them as best-effort; if it works, great, but no promises.

When the token nears expiry, GEODE refreshes it on its own (120 seconds before, plus a 401 retry). You shouldn't see this happen.

Why Claude Pro isn't a Path A option. Anthropic's terms changed on 2026-01-09: third-party tools may no longer reuse the Claude Code OAuth token. GEODE doesn't read ~/.claude/.credentials.json to keep your account safe. The only Anthropic path GEODE accepts is an API key (Path B). (Reference)

---

Path B — API key (pay-as-you-go)

For Anthropic users (any tier, including Claude Pro / Max — OAuth isn't available), ChatGPT Team users, and anyone without a paid OpenAI subscription. You buy API credits directly. New Anthropic accounts get $5 in free credits, enough for hundreds of prompts.

Get an Anthropic API key (4 clicks):

1. Sign up at console.anthropic.com
2. Top-right menu → Settings → API Keys
3. Click Create Key → name it "geode" → Copy the sk-ant-... string
4. Save it where GEODE will find it:

mkdir -p ~/.geode
echo 'ANTHROPIC_API_KEY=sk-ant-paste-your-key-here' > ~/.geode/.env
chmod 600 ~/.geode/.env

Want OpenAI or ZhipuAI GLM instead? Add OPENAI_API_KEY=sk-proj-... or ZAI_API_KEY=... to the same file. GEODE picks whichever is available.

What it costs in practice. A single prompt runs around 3,000 tokens, about $0.01. A research session with ten tool calls usually lands between $0.05 and $0.30. Your $5 free credit lasts roughly 500 prompts. Set cost_limit_usd=5 in .env if you want a hard cap.

---

How GEODE compares

A qualitative read on where GEODE sits next to the frontier harnesses (Claude Code, Codex CLI, OpenClaw) as of May 2026. This is about posture, not benchmarks. Marker legend: ✅✅ leader on the axis · ✅ supported · ⚠️ partial / qualified · ❌ absent · n/a not applicable.

<details> <summary><strong>A. Runtime posture</strong> — how the agent stays alive</summary>

</details>

<details> <summary><strong>B. Channels & UX surfaces</strong> — how it reaches users</summary>

</details>

<details> <summary><strong>C. LLM provider & cost governance</strong></summary>

</details>

<details> <summary><strong>D. Persistence, memory & verification</strong></summary>

</details>

<details> <summary><strong>E. Extensibility & observability</strong></summary>

</details>

---

Use Claude Code or Codex for short coding sessions inside an IDE or via cloud sync. Use OpenClaw to run a multi-channel chat agent fleet across many messaging surfaces. Use GEODE when an agent must work over hours or days with multi-tier memory, multi-layer verification, scheduling, and daemon-backed tool execution, and when you want that agent to keep improving its own scaffolding under a safety floor.

Sources — Claude Code (reverse-engineered reference). Codex CLI release notes + developers.openai.com/codex/config-reference + github.com/openai/codex. OpenClaw (TypeScript). GEODE — CHANGELOG.md and the self-improving hub.

---

<details> <summary><strong>Architecture overview</strong> (for contributors)</summary>

GEODE has two control layers:

• Scaffold (production) — Claude Code + CLAUDE.md + development Skills + CI Hooks. The external harness that produces GEODE's code and guarantees quality. The self-improving outer loop also mutates parts of this scaffold.
• GEODE Runtime (agent) — while(tool_use) loop + agentic tools + native ToolRegistry + runtime Skills + runtime Hooks + multi-layer Verification. The internal system of the autonomously executing agent.

4-Layer Stack (Model → Runtime → Harness → Agent) + Sub-Agent System + 5-Tier Memory.

.geode/ — agent context lifecycle (5-tier hierarchy assembled into every LLM call):

Tier 0    SOUL            GEODE.md — agent identity + constraints
Tier 0.5  User Profile    ~/.geode/user_profile/ — role, expertise, language
Tier 1    Organization    Cross-project data (signals, history)
Tier 2    Project         .geode/memory/PROJECT.md — analysis history (LRU-50)
Tier 3    Session         In-memory — conversation, tool results, plans

.geode/
├── config.toml         # Gateway, MCP servers, model
├── memory/             # T2: Project Memory (LRU rotate)
├── rules/              # Auto-generated project rules
├── vault/              # Permanent artifacts (reports, research)
├── skills/             # project runtime skills (5-tier discovery)
├── plans.json          # Disk-persistent PlanStore (v0.53.3)
└── result_cache/       # Pipeline LRU (SHA-256, 24h TTL)

Full architecture → | Hook System → | Wiring Audit →

</details>

<details> <summary><strong>Development workflow (Scaffold)</strong></summary>

CANNOT (guardrails) before CAN (freedom). A 7-step workflow plus quality gates. The CI ratchet (pytest, mypy, ruff, import-order, test-count) must pass before any merge. Test count is monotonically increasing only.

See CONTRIBUTING.md and docs/workflow.md.

</details>

<details> <summary><strong>Why — motivation</strong></summary>

In 2026, AI coding agents have made remarkable progress. They read, write, fix, and test code autonomously. But how much of real work is actually coding? Research, document analysis, scheduling, notifications, data pipelines, multi-axis evaluation for decision-making — the space requiring autonomous execution beyond coding is far broader.

Yet the core of all autonomous behavior is surprisingly simple: an LLM calls tools, observes results, decides the next action — a while(tool_use) loop. Claude Code, Codex, OpenClaw — all frontier harnesses stand on this primitive. GEODE generalizes it into a daemon-backed, memoryful runtime for long-running tool work.

</details>

---

Troubleshooting

Run geode doctor first. It checks Python version, geode PATH, ~/.geode/.env, Codex CLI OAuth, ProfileStore, the serve socket, and ~/.local/bin PATH — and prints a concrete fix command for each failure. The expanders below cover the same ground in narrative form.

<details> <summary><strong>"command not found: python3"</strong> — Python isn't installed or isn't on your PATH.</summary>

Mac: xcode-select --install then brew install python@3.12. Windows: download the installer from python.org and check "Add Python to PATH" during setup. Verify with python3 --version — must be 3.12 or higher. </details>

<details> <summary><strong>"command not found: uv"</strong> — uv isn't on your PATH yet.</summary>

The install script writes uv to ~/.local/bin. Either restart your terminal, or run source ~/.bashrc (bash) / source ~/.zshrc (zsh). Verify with uv --version. </details>

<details> <summary><strong>"command not found: geode"</strong> — the global install hasn't run.</summary>

For a PyPI install, run uv tool install geode-agent. For a source checkout, run uv tool install -e . --force from the geode/ directory. Both paths put the geode command in ~/.local/bin/. If that directory isn't on your PATH, add export PATH="$HOME/.local/bin:$PATH" to your shell config. </details>

<details> <summary><strong>"401 Unauthorized" or "Invalid API key"</strong> — wrong key, expired key, or wrong file location.</summary>

Check cat ~/.geode/.env and confirm the key starts with sk-ant- (Anthropic), sk-proj- (OpenAI), or id.secret (ZhipuAI GLM). Make sure there are no extra spaces or quote characters. If you used the ChatGPT subscription path (Path A), re-run codex auth login to refresh the OAuth token. </details>

<details> <summary><strong>"Address already in use" when running geode serve</strong> — daemon is already running.</summary>

ps aux | grep "geode serve" to find the PID, then kill <PID>. Or use geode serve --port <other> to pick a different port. </details>

<details> <summary><strong>The model doesn't seem to use my tools / runs in circles.</strong></summary>

Check geode model — some models are better at tool use than others. Default is claude-opus-4-7 (best). If you're on gpt-5.5, set effort: "high" in .geode/config.toml. Run tail -f ~/.geode/logs/serve.log to see what the model is actually doing. </details>

<details> <summary><strong>I want to see what GEODE is doing under the hood.</strong></summary>

tail -f ~/.geode/logs/serve.log (or whichever log file you redirected when starting geode serve manually). Every LLM call, tool invocation, and decision is logged with timing. The core.audit.diagnostics fa4 channel writes per-month files under ~/.geode/diagnostics/<YYYY-MM>.log for cross-process traces. </details>

<details> <summary><strong>How do I update?</strong></summary>

uv tool upgrade geode-agent   # PyPI install
geode update                  # source checkout

---