_{Geodi · 22×12 dot sprite · core/ui/geodi_art.py}

Landing · Docs · Self-improving hub · Eval artifacts · 한국어

GEODE v1.0.25: Autonomous Agent Runtime + Evaluation Substrate

A general-purpose runtime for autonomous tool work. You ask in plain language; GEODE plans, calls tools, and reports, for one prompt or a long-running session. An experimental outer loop mutates scaffold candidates and admits them only through evidence-bound safety gates; the public record does not yet establish sustained self-improvement.

Experimental status: SIL (Self-Improving Loop) and Crucible are active experiments, not stable production features. Their protocols, promotion gates, schemas, and reported results may change as validation continues.

Have a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan? Route GEODE through that subscription. No API key. Subscription setup ↓

Using Anthropic? GEODE's built-in Anthropic route requires ANTHROPIC_API_KEY. The former Claude CLI subscription integration is retired; legacy settings fail before dispatch with a migration hint.

Benchmark snapshot: Tau2 native user-simulator track

GEODE keeps benchmark numbers tied to the exact runtime and model route that produced them. The 2026-07-03/04 Tau2 run below used GEODE v0.99.269 with the public evals/benchmarks tau2 adapter, sierra-research/tau2-bench@1901a30 (tau2==1.0.0), gpt-5.2 through OpenAI PAYG, agent reasoning effort high, max_steps=200, and tau2's native user_simulator using gpt-4.1-2025-04-14 with effort medium.

Raw run logs are preserved in geode-eval-artifacts/tau2/simulations/ (geode-gpt-5-2-high-native-user-*-base-20260703/results.json — per-task rewards, action checks, and full simulation transcripts). These numbers are directly comparable to GEODE reruns with the same harness, split, user simulator, model route, and max-step settings. They should not be mixed with the earlier geode_user smoke rows. Compared with frontier Tau2 headlines, this is an independently run GEODE adapter measurement, not the providers' internal research setup.

The current weak spot is not gross tool availability. It is required action coverage under compound tasks: Retail failures often miss DB/write side effects, while Telecom failures cluster around MMS/APN/app-permission/roaming combinations where one necessary user or agent action is omitted.

The latest subscription-route regression (2026-08-02) used gpt-5.4 at effort high for both GEODE agent and GEODE user. The exact mock/create_task_1 diagnostic remained 0/1 because the model supplied an unrequested optional description=""; the first Telecom-small roaming task passed 1/1 with every required DB, user-action, mobile-status, and speed check. These two diagnostic rows are not the native-user headline. Their 158 canonical events and ten exact tool pairs are pinned to geode-eval-artifacts@f588ce9.

Benchmark snapshot: MCPMark Verified available-services track

The 2026-07-04 MCPMark run used GEODE v0.99.269-era code on branch feature/mcpmark-agentworld-run, eval-sys/mcpmark@cd45b7f, GEODE's public evals/benchmarks MCPMark adapter, gpt-5.5 through the OpenAI Codex subscription route, and reasoning effort xhigh.

This is not a full MCPMark Verified leaderboard score. It covers the standard service slices that were runnable in the local environment; Notion was blocked by missing notion_state.json, and Playwright/WebArena was blocked by missing Docker images/browser service stack.

Raw run logs are preserved in geode-eval-artifacts/mcpmark/results-geode-agentworld/ (geode-gpt55-xhigh-20260704-mcpmark-verified-* — per-task meta.json verifier results, messages.json final answers or empty placeholders, and execution.log ordered MCP action/result records where produced). The public MCPMark snapshot does not retain full model dialogue; see its trajectory contract. These rows are directly comparable only to the same MCPMark commit, service set, GEODE adapter, model route, and timeout settings.

Experimental scaffold-optimization loop

GEODE includes an experimental non-parametric scaffold-optimization loop. It mutates candidates across the system prompt, tool policy, task decomposition, reflection, skills, agent contracts, and tool descriptions; it never updates model weights. Fitness is an adversarial safety audit, not a capability benchmark: Petri-grade, multi-dimensional, with a hard floor on critical safety dimensions, so any change that regresses one is rejected. The public evidence currently demonstrates rejection and invalidation discipline, not repeated core promotion or monotonic improvement.

The selection contract is a (1+1) champion chain: mutate, audit, permit promotion on a real gain, otherwise revert. Two loops run together. An inner agentic loop runs a task; an outer loop evaluates scaffold candidates. The loop lineage (Promptbreeder, STOP, ADAS, DGM, GEPA) is well established. GEODE re-aims it from capability to safety and from weights to scaffolding. It is a recombination of known mechanisms, not a new primitive.

• The closed loop →: autoresearch, mutate / audit / promote / revert end to end
• Two loops →: the inner-vs-outer mental model
• Lineage and positioning →: where GEODE sits among prior self-improving loops
• Self-improving hub →: live generations, mutations, and promotion decisions
• Petri bundle →: the live safety-audit transcript viewer

What you can ask it

Copy-paste these to see what it does:

"Summarize the latest RAG papers on arXiv from this month"
"Find LinkedIn job postings that match my profile and rank them"
"Schedule a 9 AM standup reminder every weekday"
"Watch hacker news for posts about LangGraph and DM me on Slack"
"Compare gpt-5.5 vs claude-opus-4.7 for code review"
"Find launch emails, summarize them, and add the follow-up to my Calendar"

GEODE chooses the right tools (web search, file ops, MCP servers, sub-agents), runs them, and shows you the answer with sources and cost.

Setup in 5 minutes

Prerequisites: what you need first

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, API key (paste and go), or skip into dry-run mode for now. It can also import an existing ~/.codex/auth.json credential, but GEODE does not execute Codex CLI for inference.

If you already ran codex auth login, the next geode invocation can detect that token. Codex CLI is otherwise optional.

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)

GEODE signs in directly through /login openai and calls the ChatGPT backend through its in-process codex-oauth adapter. It can also read an existing ~/.codex/auth.json credential without spawning the Codex CLI executable.

geode                                 # start GEODE
# inside the session: /login openai   # ChatGPT device-code login

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. GPT-5.6 Sol/Terra/Luna and GPT-5.4 are dual-lane: GEODE uses ChatGPT OAuth when a subscription profile is active and the Platform API when an API-key profile is selected. If you want 5.5, you need ChatGPT.
• Existing Codex CLI credentials remain importable, but codex-cli is not a GEODE inference backend.
• 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.

Anthropic API-key path. /login anthropic now configures ANTHROPIC_API_KEY. Legacy claude-cli or Anthropic oauth settings are read only to emit a migration error; GEODE never launches the Claude CLI.

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

For Anthropic users who want the recommended third-party integration path, ChatGPT Team users, and anyone without a paid OpenAI subscription. You buy API credits directly.

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 a hard cap in ~/.geode/config.toml:

[cost]
limit_usd = 5

Step 4: Run

geode                                                # interactive chat
# Then type: what's new in AI today?

You should see something like:

  ✓ web_search → ok (1.5s)
  ✓ web_fetch → ok (1.1s)

  Today's top AI stories:
  • Anthropic released Claude Opus 4.8 with 1M-token context...
  • OpenAI's GPT-5.5 system card published; pricing matches 4.6...
  • LangGraph 0.6 ships native streaming for tool calls...

  ✢ Worked for 8s · claude-opus-4-8 · ↓2.1k ↑412 · $0.018

If you see this, you're done. If you see an error, run geode doctor for a diagnosis or jump to Troubleshooting.

Other useful commands

geode about           # version, model, registered auth, paths, daemon status
geode doctor          # 7-check bootstrap diagnosis with fix hints
geode update          # uv install: latest patch; source install: pull + rebuild
geode update --latest # explicitly allow minor/major uv package upgrades
geode uninstall       # remove runtime data and the installed CLI
geode setup --reset   # wipe ~/.geode/.env and re-run the wizard

Optional integration: connect Gmail, Calendar, Drive, Docs, Sheets, Tasks, and Contacts with /login google; see Connect Google Workspace.

Updating

GEODE detects whether it is a persistent uv tool or an editable source install:

geode update
geode version

For a standard registry-backed uv tool, this replaces the stored install request with a compatible-release constraint and installs the newest patch in the current major/minor series. Minor and major upgrades require an explicit opt-in:

geode update --latest

For an editable source checkout, geode update instead runs git pull --ff-only, uv sync, uv tool install -e . --force, then geode version. It resolves the actual GEODE checkout from install metadata rather than using an unrelated current repository; missing metadata is an error, never a cwd fallback. If geode serve was running, GEODE verifies the update before stopping it, then confirms the replacement daemon is ready. Preview either path without changing files:

geode update --dry-run

Custom uv tool receipts with extras, --with packages, constraints, an explicit Python, or resolver settings stop with a manual-update hint so those settings are never discarded silently. The hint identifies the receipt and preserves a recorded source reference instead of silently switching it to PyPI.

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

Put Slack's SLACK_BOT_TOKEN (xoxb-) and Socket Mode SLACK_APP_TOKEN (xapp-) in ~/.geode/.env; put channel bindings, receiver choices, and project-specific Gateway behavior in .geode/config.toml. See docs/setup.md → Gateway for the full setup. After that, mentioning the bot in a bound channel routes the pushed event into the same agent loop you use locally; later replies in that thread continue the same checkpoint without another mention.

Remote desktop control stays disabled in Gateway sessions unless the operator explicitly sets [gateway] allow_computer_use = true; see the computer-use guide before enabling it for a restricted binding.

The live Slack E2E receipt shows ordinary conversation and a browser-DOM UI task completing through Socket Mode. Strict pixel computer_use captured the desktop but stopped when the active OpenAI subscription source had no compatible visual grounding; it did not guess coordinates or silently switch providers. The primary answers used the subscription route, while post-turn processing also made an auxiliary GLM PAYG call, so the complete lifecycle is not advertised as subscription-only.

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

To run a campaign, start with the quick-start: docs/self-improving/campaign-quick-start.md.

Configuration

Secrets live in .env, behavior lives in config.toml. The two never collide, because .env is secrets-only and config.toml is behavior-only, so each has a single precedence rule. The detailed path design is in docs/architecture/storage-hierarchy.md, with a standalone diagram at docs/diagrams/geode-context-config-paths.html.

• The global ~/.geode/.env is the authoritative secret store. A project ./.env fills only the keys it lacks and never shadows a global key. An OPENAI_API_KEY in ~/.geode/.env wins even when a project ./.env leaves it blank.
• The project ./.geode/config.toml overrides the global ~/.geode/config.toml. Behavior is tuned per project.
• ~/.geode/auth.toml stores LLM-provider credential profiles, plan metadata, and provider OAuth account state. Raw API keys still live in ~/.geode/.env.
• Google Workspace is separate: non-secret account and scope metadata lives in ~/.geode/google/accounts.json, long-lived secrets in the OS keyring service geode.google.oauth, and access tokens only in process memory.
• Runtime history, usage, diagnostics, daemon logs, and per-project private data live under ~/.geode/. Project context that should travel with a workspace lives under ./.geode/.

Every field rides one ladder. Higher wins:

1. os.environ                      shell exports (session-scoped)
2. global  ~/.geode/.env           secrets: authoritative
3. project ./.env                  fills only the keys global lacks
4. project ./.geode/config.toml    behavior: project wins
5. global  ~/.geode/config.toml
6. built-in defaults

.env ranks the global file higher, config.toml ranks the project file higher. The asymmetry is deliberate: credentials have one home, behavior is tuned per project.

Add or switch a credential:

geode setup                          # re-run the wizard (subscription OAuth or API key)
/login openai                        # in a session: subscription OAuth
/login google                        # in a session: Google Workspace OAuth
/key openai sk-proj-...              # in a session: paste an API key
echo 'OPENAI_API_KEY=sk-proj-...' >> ~/.geode/.env    # edit the authoritative file

When a change does not take effect, run geode config explain <KEY>. It prints every layer, marks the winner and any masked layers with file paths, and points at the exact line to edit. geode about shows the effective model. Full reference: Configuration basics.

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.

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

What's inside

Using GEODE as an MCP server

geode-mcp (installed with the CLI) speaks MCP over stdio, so any MCP client, Claude Code, Claude Desktop, Cursor, can drive GEODE as a tool. This repo ships .mcp.json, so Claude Code sessions opened in this project pick the server up automatically; elsewhere register it with claude mcp add geode -- geode-mcp.

Verified 2026-06-11 against the live runtime (initialize handshake, tools/list, tool calls):

Remote access (v0.99.171): geode-mcp --http [--host H] [--port P] serves the same tools over the MCP streamable-HTTP transport. Auth is a bearer token from GEODE_MCP_TOKEN (a secret, put it in ~/.geode/.env); clients pass Authorization: Bearer <token>. A non-loopback bind without a token is refused at startup, run_agent reaches GEODE's full tool surface, so an open bind is a remote-execution surface. For personal cross-device use, SSH needs no setup at all: claude mcp add geode -- ssh <host> geode-mcp.

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.

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, or when you want to experiment with scaffold candidates under an evidence-bound 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.

graph LR
    AG["Agent<br/>AgenticLoop, SubAgent<br/>CLIPoller, Gateway"] --> HA["Harness<br/>SessionLane, PolicyChain<br/>TaskGraph, HookSystem"]
    HA --> RT["Runtime<br/>Agentic tools, MCP catalog<br/>Memory, Skills"]
    RT --> MD["Model<br/>Claude, OpenAI, GLM"]

    style AG fill:#1e293b,stroke:#3b82f6,color:#e2e8f0
    style HA fill:#1e293b,stroke:#f59e0b,color:#e2e8f0
    style RT fill:#1e293b,stroke:#10b981,color:#e2e8f0
    style MD fill:#1e293b,stroke:#8b5cf6,color:#e2e8f0

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)
└── result_cache/       # Pipeline LRU (SHA-256, 24h TTL)

License

Apache License 2.0, LICENSE