geode-agent 0.99.333

GEODE — 범용 자율 실행 에이전트

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

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

GEODE v0.99.333: A Self-improving Autonomous Execution Agent

A general-purpose autonomous agent that also rewrites the scaffolding it runs on. You ask in plain language; GEODE plans, calls tools, and reports, for one prompt or a long-running session. Underneath, an outer loop keeps tuning the system that runs your tasks.

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 ↓

Claude Pro / Max? Anthropic's terms (effective 2026-01-09) forbid third-party harness from using the Claude Code OAuth token, so GEODE doesn't read it. Use an Anthropic API key instead (Path B). Your Console account is the same; new accounts get $5 free credit.

---

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 plugins/benchmark_harness 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.

Domain	Tasks	Reward / pass^1	Notable action checks	Duration
Airline base	50	0.8200 (41 / 50)	read 81/91, write 33/49	avg 284.10s / max 979.65s
Retail base	114	0.7632 (87 / 114)	read 320/354, write 140/174	avg 206.52s / max 873.92s
Telecom base	114	0.8772 (100 / 114)	write 471/496, generic 20/20	avg 252.87s / max 818.58s
Weighted total	278	0.8201 (228 / 278)	domain action schemas differ	-

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.

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 plugins/benchmark_harness 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.

MCPMark service	Tasks	Passed	Accuracy	Notes
Filesystem standard	30	25	83.3%	papers/author_folders counted as a failed no-result transport run after two attempts
Postgres standard	21	20	95.2%	Uses postgres-mcp==0.3.0 in unrestricted mode
GitHub standard	23	19	82.6%	Uses ghcr.io/github/github-mcp-server:v0.15.0; transient repos cleaned up
Measured total	74	64	86.5%	filesystem + postgres + github only

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 and messages.json full agent transcripts). These rows are directly comparable only to the same MCPMark commit, service set, GEODE adapter, model route, and timeout settings.

---

The self-improving loop

GEODE is a self-evolving agent on the non-parametric branch: it improves by mutating its own scaffolding (system prompt, tool policy, task decomposition, reflection, skills, agent contracts, tool descriptions), never the 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 selection seeds co-evolve, a co-scientist pipeline grows adversarial seeds alongside the agent, so they apply moving selection pressure, not a stable ruler. Cross-generation fitness is measured on a separate version-frozen held-out bench that never mutates; only that held-out curve counts as evidence of real improvement.

Selection is an honest (1+1) champion chain: mutate, audit, promote on a real gain, otherwise revert. Two loops run together. An inner agentic loop runs a task; an outer loop tunes the system that runs tasks. The loop lineage (Promptbreeder, STOP, ADAS, DGM, GEPA) is well established. GEODE re-aims it from capability to safety, from weights to scaffolding, on co-evolved adversarial seeds. A recombination occupying an empty cell, 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"

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

Don't know what these are? Click here for a 1-line explainer of each.

• 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.

Tool	Install	Verify
Python 3.12+	python.org/downloads	python3 --version
Git	git-scm.com	git --version
uv	curl -LsSf https://astral.sh/uv/install.sh | sh	uv --version

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.

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

[cost]
limit_usd = 5

---

Step 4: Run

geode                                                # interactive chat
geode "what's new in AI today?"                      # one-shot prompt

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

---

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 channel secrets such as SLACK_BOT_TOKEN in ~/.geode/.env; put channel bindings, poller 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 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

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 credential profiles, plan metadata, and OAuth-derived account state. Raw API keys still live in ~/.geode/.env.
• 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
/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.

"command not found: python3", Python isn't installed or isn't on your PATH.

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.

"command not found: uv", uv isn't on your PATH yet.

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

"command not found: geode", the global install hasn't run.

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.

"401 Unauthorized" or "Invalid API key", wrong key, expired key, or wrong file location.

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.

"Address already in use" when running `geode serve`, daemon is already running.

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

The model doesn't seem to use my tools / runs in circles.

Check geode model, some models are better at tool use than others. Default is claude-opus-4-8 (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.

I want to see what GEODE is doing under the hood.

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.

How do I update?

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

---

What's inside

Feature	What it does
while(tool_use) loop	The single primitive every behavior is built on. Sub-agents, plans, batches are all instances of the same loop
Self-improving outer loop	Mutates GEODE's own scaffolding, audits each change against an adversarial safety rubric, and promotes only on a real gain. See the closed loop
Agentic tools + MCP catalog	Web search, file ops, scheduling, memory, calendar, Slack/Discord, Korean job-board search, plus the Anthropic-published MCP registry (cached at ~/.geode/mcp/registry-cache.json). Auto-installed on first use
3-provider failover	Anthropic + OpenAI + ZhipuAI. ChatGPT subscription OAuth is auto-detected through Codex CLI; Anthropic/OpenAI/ZhipuAI pay-as-you-go API keys also work. Failover is in-provider only (no surprise cross-vendor charges, v0.53.0 governance)
5-tier memory	SOUL (0) → User Profile (0.5) → Organization (1) → Project (2) → Session (3). Persistent, survives daemon restarts
Progress plans + review checkpoints	update_plan shows a Codex-style per-turn checklist without blocking execution. create_plan + approve_plan remain for explicit review checkpoints, persisted in .geode/plans.json
MCP server (geode-mcp)	Exposes GEODE itself as an MCP server (stdio): run_agent, self_improving_status, self_improving_propose/apply (2-step confirm gate), query_memory, get_health. Registered for Claude Code via the repo-shipped .mcp.json
Long-running daemon	geode serve runs as background daemon. Slack / Discord / Telegram pollers + scheduler tick + IPC for the thin CLI
Sub-agents	Full inheritance of parent capability, depth/cost guards, isolation by Lane
Turn verification	Rule-based per-turn checks (empty turn, tool errors, plan-step mismatch) + opt-in LLM-judge scoring (core/agent/verify.py); a verify FAIL triggers replanning

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):

Check	Result
Handshake + 6 tools listed	pass
self_improving_status / get_health / query_memory	pass (live data)
Server version in handshake	was the mcp SDK's "1.26.0", now reports GEODE's version (the SDK's FastMCP.__init__ exposes no version kwarg; pinned by tests/core/test_mcp_server_tools.py)
get_health credential honesty	*_configured only meant "API key present" and read false on OAuth/CLI-lane setups, now also reports *_credential_source
run_agent, self_improving_propose/apply	not exercised in the automated check (token cost / mutation side effects); apply is gated behind a 2-step proposal confirm

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.

A. Runtime posture, how the agent stays alive

	Claude Code	Codex CLI	OpenClaw	GEODE
Always-on daemon	❌ per-invocation	⚠️ opt-in codex remote-control	✅✅ launchd / systemd control plane	✅ geode serve daemon
Native scheduler (cron)	⚠️ scheduled cloud agents (/schedule, cloud-executed)	❌ (Codex Cloud Automations only, issue #8317)	✅ cron add/edit/list CLI	✅ cron + event triggers
Thin CLI ↔ daemon IPC	❌	⚠️ remote-control server mode	✅ Gateway / Agent split	✅ IPC server
Sub-agent isolation	✅ Agent tool + run_in_background	✅ multi_agent feature	✅✅ Lane Queue + Session bindings	✅ Lane + depth / cost guard
Session resume / fork	✅ JSONL transcripts	✅ /resume + /fork slash commands	✅ Session bindings with TTL	✅ session resume

B. Channels & UX surfaces, how it reaches users

	Claude Code	Codex CLI	OpenClaw	GEODE
Slack	❌ (MCP plugin possible)	⚠️ Codex Cloud only, not CLI	✅ Socket Mode, first-class	✅ Socket Mode, first-class
Discord / Telegram / other chat	❌	❌	✅✅ many channels (Discord, Telegram, WhatsApp, Signal, iMessage, Teams, Matrix, Feishu, LINE, ...)	✅ Discord + Telegram pollers
IDE plugin	✅ VS Code · JetBrains	✅✅ VS Code · JetBrains · Cursor · Windsurf	❌	❌
Web UI	✅ claude.ai/code	✅ Codex Cloud	⚠️ WebChat plugin	❌ (docs site only)
MCP server catalog	✅ first-class	✅ first-class	✅ first-class	✅ Anthropic-published registry (cached at ~/.geode/mcp/registry-cache.json)

C. LLM provider & cost governance

	Claude Code	Codex CLI	OpenClaw	GEODE
Multi-provider failover	✅ Anthropic + AWS Bedrock + Google Vertex (env routing)	✅✅ OpenAI + Azure + Bedrock + Ollama + any OpenAI-compatible (model_providers config)	✅ auth.order cooldown-based auto-failover	✅ Anthropic + OpenAI + ZhipuAI, in-provider only
Subscription OAuth tier	✅ Pro / Max	✅✅ Plus · Pro · Business · Edu · Enterprise	⚠️ OpenAI + Gemini onboarding	⚠️ ChatGPT only (Plus / Pro / Business / Edu / Enterprise), Anthropic ToS (2026-01-09) blocks third-party Claude OAuth
Token / cost budget guard	⚠️ cache token tracking only	⚠️ retry caps (request_max_retries)	⚠️ partial	✅ explicit token + cost budget governance
Context overflow handling	✅ autocompaction	⚠️ skills progressive disclosure + fork	✅ compaction + transcript streaming	✅✅ layered context-overflow handling
Cross-vendor failover policy	❌	⚠️ manual model_providers switch	✅ automatic	❌ by design (no surprise cross-vendor charges)

D. Persistence, memory & verification

	Claude Code	Codex CLI	OpenClaw	GEODE
Memory tiers	✅ CLAUDE.md merge + auto memory (~/.claude/projects/*/memory)	✅ hierarchical AGENTS.md (global ~/.codex/ + repo + nested dirs)	⚠️ session-scoped	✅✅ multi-tier (SOUL · User · Org · Project · Session)
Progress / review plans	✅ TodoWrite persistence	✅ turn plan updates	✅ task registry	✅ update_plan for progress + .geode/plans.json for checkpoints
Permission / sandbox layers	✅ default / auto / bypass modes + Confirmation UI	✅ sandbox_mode (read-only / workspace-write / danger-full-access)	✅✅ Policy Chain across many audit surfaces	✅ Policy Chain + tool gates
Multi-layer guardrails	⚠️ permission + hooks	⚠️ hooks + sandbox	✅ audit.runtime engine	✅ turn verify (rule-based + opt-in LLM-judge, core/agent/verify.py) → replan on FAIL, plus safety-axis fitness gate in the self-improving loop
Hook events	✅ PreToolUse / PostToolUse / UserPromptSubmit / Stop / SubagentStop / PreCompact / SessionStart / SessionEnd / Notification	⚠️ SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PermissionRequest / Stop	✅ several event types · many bundled handlers	✅✅ broad event surface (docs/architecture/hook-system.md)

E. Extensibility & observability

	Claude Code	Codex CLI	OpenClaw	GEODE
Plugin / extension surfaces	✅ manifest + marketplace (user / project / local scopes)	✅ /plugins slash command + plugin sharing	✅✅ extension points (Channel · Tool · Skill · Hook) via @openclaw/plugin-sdk	✅ runtime SkillRegistry + MCP/tool surfaces
Skill system	✅ Deferred tools + SKILL.md manifest	✅ SKILL.md + progressive disclosure (.agents/skills/)	✅ skill filter + archive upload	✅ runtime SkillRegistry across bundled/global/project scopes
Swappable pipeline DAG	❌	❌	⚠️ flows (channel-setup / doctor / provider, not a DAG abstraction)	⚠️ external package responsibility; GEODE core no longer ships a pipeline port
Trace / replay / Run Log	✅ tengu_* telemetry + /insights HTML	⚠️ /status + /debug-config only	✅ ACP session lineage + Task Registry	✅ Native RunLog + Petri eval integration
Self-improving safety loop	❌	❌	❌	✅✅ outer loop: scaffold mutation + adversarial safety audit + (1+1) promote/revert
Cross-provider review	❌	❌	❌	⚠️ multi-voter cross-provider ranking panel (≥2 providers, plugins/seed_generation/agents/ranker.py) in the self-improving loop; agreement calibration is WIP

---

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.

---

Architecture overview (for contributors)

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.

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

Layer	Core	Entry points
Agent	AgenticLoop, SubAgentManager, CLIPoller, Gateway wiring	core/cli/, core/server/, core/messaging/, core/integrations/messaging/, core/wiring/
Harness	SessionLane, LaneQueue, PolicyChain, TaskGraph, HookSystem	core/orchestration/, core/hooks/
Runtime	Agentic tools, native ToolRegistry, MCP Catalog (Anthropic registry plus project-configured servers), runtime Skills, Memory (multi-tier), PlanStore	core/tools/, core/memory/, core/orchestration/plan_store.py
Model	ClaudeAdapter, OpenAIAdapter, CodexAdapter, GLMAdapter	core/llm/

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

Full architecture → | Hook System → | Wiring Audit →

Development workflow (Scaffold)

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.

Gate	Command	Target
Lint	uv run ruff check core/ tests/	0 errors
Type	uv run mypy core/	0 errors
Test	uv run pytest tests/ -q	all pass

See CONTRIBUTING.md and docs/workflow.md.

Why, motivation

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.

---

License

Apache License 2.0, LICENSE