# GEODE

> GEODE is a self-evolving autonomous execution agent: an inner agentic loop runs tasks (research, analysis, automation, scheduling) and an outer self-improving loop (Petri audit -> fitness gate) tunes the system that runs them.

Version v1.0.1. Last sync 2026-07-18. Docs links point to clean markdown twins (.md); drop the .md suffix for the rendered page.

## Start here

- [Docs](https://mangowhoiscloud.github.io/geode/docs.md): documentation root, what GEODE is and where to go next
- [Portfolio](https://mangowhoiscloud.github.io/geode/portfolio): capability overview with demos
- [About](https://mangowhoiscloud.github.io/geode/about): project background
- [Source](https://github.com/mangowhoiscloud/geode): GitHub repository

## Overview

- [What GEODE is](https://mangowhoiscloud.github.io/geode/docs.md): An autonomous execution agent that runs an inner agentic loop and improves itself through an outer loop. What it does, who it is for, where to go next.
- [How GEODE runs a task](https://mangowhoiscloud.github.io/geode/docs/overview/how-it-runs.md): One request, traced end to end. The same core serves a CLI task, a gateway message, and a scheduled self-improving run.
- [The 5-layer stack](https://mangowhoiscloud.github.io/geode/docs/architecture/overview.md): Model, Runtime, Harness, Agent, Self-Improving. What each layer owns, and where its responsibility ends.

## Getting Started

- [Quick Start](https://mangowhoiscloud.github.io/geode/docs/quick-start.md): Install GEODE and run your first task in a few minutes.
- [Connect Google Workspace](https://mangowhoiscloud.github.io/geode/docs/run/google-workspace.md): Bring your own Google Desktop OAuth client for Gmail, Calendar, Drive, Docs, Sheets, Tasks, and Contacts.
- [Pick a path](https://mangowhoiscloud.github.io/geode/docs/run/pick-path.md): Subscription, API key, or free path. How to choose for your situation.
- [Configure providers](https://mangowhoiscloud.github.io/geode/docs/run/providers.md): Anthropic, OpenAI, Codex, GLM. Where keys go, and what fallback chain you get.
- [Run as a daemon](https://mangowhoiscloud.github.io/geode/docs/run/serve.md): Start, restart, and stop serve. A thin CLI talks to an IPC-served runtime.

## Core Concepts

- [The two loops](https://mangowhoiscloud.github.io/geode/docs/concepts/two-loops.md): The mental model the rest of the docs build on. An inner agentic loop runs a task; an outer loop tunes the system that runs tasks.
- [The inner agentic loop](https://mangowhoiscloud.github.io/geode/docs/architecture/agentic-loop.md): The while(tool_use) primitive. How a turn runs, and the paths that end it.
- [Context assembly](https://mangowhoiscloud.github.io/geode/docs/runtime/context.md): Every LLM call's context is built here. Memory tiers plus prompt layers, under a token budget.
- [Memory tiers](https://mangowhoiscloud.github.io/geode/docs/runtime/memory/5-tier.md): From a raw session log to a single LLM-ready summary. Hierarchical override, budget-aware compression.
- [Prompt assembly](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/prompt-system.md): How the system prompt is layered and assembled before each call.
- [Tools and toolsets](https://mangowhoiscloud.github.io/geode/docs/runtime/tools/protocol.md): The tool registry and deferred loading. A few tools load up front, the rest are fetched on demand.
- [Hooks and observability](https://mangowhoiscloud.github.io/geode/docs/harness/hooks.md): Lifecycle events that handlers subscribe to. How observe, react, decide, and act stack on one event.
- [LLM routing](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/providers.md): Provider selection and model resolution. Fallback chains ship empty by default; fatal errors fast-fail instead of retrying.
- [Tool calling](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/tool-calling.md): How GEODE advertises tools, translates tool choice, executes calls, and replays results across provider adapters.
- [Structured output](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/structured-output.md): GEODE's JSON Schema contract, adapter wiring, strictness rules, and worker-side validation and retry boundary.
- [Sub-agent orchestration](https://mangowhoiscloud.github.io/geode/docs/runtime/orchestration.md): Spawning sub-agents as isolated worker processes in parallel lanes. The parent gets back a summary; write access is governed by toolkit composition.
- [Skills](https://mangowhoiscloud.github.io/geode/docs/runtime/skills.md): User-invocable skills, distinct from tools. Discovery, lifecycle, override.

## The Self-Improving Loop

- [Closed-Loop](https://mangowhoiscloud.github.io/geode/docs/capabilities/autoresearch.md): The outer loop end to end. Mutate the scaffold, audit with Petri, gate the fitness gain on a margin, then promote or revert. No model weight or parameter ever changes.
- [Seed Scenario Generation](https://mangowhoiscloud.github.io/geode/docs/capabilities/co-scientist.md): A nine-role generation loop that grows the evaluation scenario corpus. Supervisor, literature review, generator, proximity, critic, pilot, ranker, evolver, meta-reviewer.
- [Seed pipeline](https://mangowhoiscloud.github.io/geode/docs/capabilities/seed-pipeline.md): The plugin that regenerates the seed corpus each generation. Picker, orchestrator, manifest, cost preview, and the blend survivor selection.
- [Outer-loop configuration](https://mangowhoiscloud.github.io/geode/docs/capabilities/outer-loop.md): The shared schema and loader for autoresearch, seed generation, Petri roles, and the auto-trigger scheduler. Strict by default.
- [Petri × GEODE](https://mangowhoiscloud.github.io/geode/docs/petri/overview.md): Anthropic Alignment Science's evaluation framework, wrapped over the GEODE agent as the loop's measurement layer.
- [Scenarios](https://mangowhoiscloud.github.io/geode/docs/petri/scenarios.md): The Petri seed corpus plus GEODE-specific seeds, grouped into critical, auxiliary, and info dimension buckets.
- [Run an audit](https://mangowhoiscloud.github.io/geode/docs/petri/run.md): geode audit, or inspect eval for the raw path. Choose model roles, dimension set, seeds, and turn budget. Dry-run by default.
- [Judge dimensions](https://mangowhoiscloud.github.io/geode/docs/petri/judge-dimensions.md): The 22-dim rubric and the 18-dim fitness universe. Critical floors versus auxiliary drift, on a 1-10 lower-is-better scale.
- [Seed-generation runs](https://mangowhoiscloud.github.io/geode/docs/petri/seeds.md): The per-generation dashboard. Survivors, tokens, meta-review, and next-generation priors per run.
- [Lineage and positioning](https://mangowhoiscloud.github.io/geode/docs/capabilities/lineage.md): Where this loop sits in the self-evolving agents literature. An honest recombination of known parts, not a new primitive.
- [Bundle viewer](https://mangowhoiscloud.github.io/geode/docs/petri/bundle.md): The live inspect_ai transcript viewer for the latest audit run.

## Operating GEODE

- [Serve and gateway](https://mangowhoiscloud.github.io/geode/docs/harness/serve-gateway.md): Operating the serve daemon's messaging gateway. Pollers, binding routing, lane queue.
- [Messaging integrations](https://mangowhoiscloud.github.io/geode/docs/run/messaging.md): Connect GEODE to Slack, Discord, or Telegram through gateway adapters.
- [Schedule tasks](https://mangowhoiscloud.github.io/geode/docs/run/schedule.md): Natural language and cron, with jitter. A daily report as a single command.
- [Scheduler internals](https://mangowhoiscloud.github.io/geode/docs/runtime/scheduler.md): How scheduled jobs are parsed, persisted, and fired.
- [Lifecycle](https://mangowhoiscloud.github.io/geode/docs/harness/lifecycle.md): Bootstrap, serve, shutdown. The injection order, and the cold-start lazy arc.
- [Long-running safety](https://mangowhoiscloud.github.io/geode/docs/ops/long-running.md): Round, time, and cost guards plus the context overflow ladder. How a long run ends honestly.
- [Cost monitoring](https://mangowhoiscloud.github.io/geode/docs/ops/cost.md): Session and monthly budgets. The usage ledger, geode history, and /cost.
- [Observability](https://mangowhoiscloud.github.io/geode/docs/verification/observability.md): The lenses on a run. Hooks, run logs, transcripts, session metrics, and the logging switchboard.
- [Troubleshooting](https://mangowhoiscloud.github.io/geode/docs/run/troubleshooting.md): Common failure modes and where to look. Logs, hooks, runlog.

## Benchmarks

- [Tau2](https://mangowhoiscloud.github.io/geode/docs/benchmarks/tau2.md): GEODE's tau2-bench measurements: the native user-simulator track headline, every verifier-backed run record, and links to the raw simulation logs.
- [MCPMark](https://mangowhoiscloud.github.io/geode/docs/benchmarks/mcpmark.md): GEODE's MCPMark measurements: the Verified available-services headline, service coverage and blockers, every run record, and links to the raw run logs.

## Guides and How-to

- [Write a tool](https://mangowhoiscloud.github.io/geode/docs/guides/custom-tool.md): Define a tool, register it, and gate it with a permission policy.
- [Register a hook](https://mangowhoiscloud.github.io/geode/docs/guides/register-hook.md): Subscribe a handler to a lifecycle event and wire it in bootstrap.
- [Add an LLM adapter](https://mangowhoiscloud.github.io/geode/docs/guides/llm-adapter.md): Implement the adapter protocol, register it, and route models to it.
- [Configure a binding](https://mangowhoiscloud.github.io/geode/docs/guides/binding.md): Route a messaging channel to a session lane with its own model and policy.
- [Debug a stuck run](https://mangowhoiscloud.github.io/geode/docs/guides/debug-stuck-run.md): Read the transcript and runlog, find where a run stalled, and recover.

## Configuration

- [Configuration basics](https://mangowhoiscloud.github.io/geode/docs/config/basics.md): Where configuration lives, how it loads, and how overrides resolve.
- [config.toml reference](https://mangowhoiscloud.github.io/geode/docs/config/reference.md): Every configuration key, grouped by area: Settings fields, routing.toml, and the self-improving loop sections.
- [Auth and OAuth](https://mangowhoiscloud.github.io/geode/docs/runtime/auth.md): Credential sources, the /login OAuth profiles, Codex token detection, and where API keys live.
- [OAuth token rotation](https://mangowhoiscloud.github.io/geode/docs/ops/oauth.md): Refresh policy and cooldown across providers.
- [System prompt modes](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/system-prompt-modes.md): Default-on persona injection and the audit-mode strip. The two ways the system prompt is reshaped.
- [Prompt caching](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/prompt-caching.md): The static and dynamic boundary, and ephemeral cache control.
- [Prompt hashing](https://mangowhoiscloud.github.io/geode/docs/runtime/llm/prompt-hashing.md): Pinned prompt hashes that break the build on unintended drift.
- [MCP servers](https://mangowhoiscloud.github.io/geode/docs/runtime/tools/mcp.md): Both sides of MCP: the client that attaches external servers, and geode-mcp, the server GEODE ships.

## Reference

- [Frontier comparison](https://mangowhoiscloud.github.io/geode/docs/reference/frontier-comparison.md): What GEODE borrows from Claude Code, Codex CLI, OpenClaw, and Hermes, and where it differs. The reference entry point for GEODE's position in the lineage.
- [External references](https://mangowhoiscloud.github.io/geode/docs/reference/external-references.md): Frontier agent systems, design standards, and prior work GEODE cites — the self-evolving-agents lineage behind the loop.
- [Meta-harness catalog](https://mangowhoiscloud.github.io/geode/docs/reference/meta-harness-catalog.md): Every mechanism that converges the stochastic runtime: Context Control, Plan and Execute, Verify, Observe, and the Scaffold that builds GEODE itself. Code-verified, with control surfaces and paths.
- [CLI and slash commands](https://mangowhoiscloud.github.io/geode/docs/harness/cli.md): The exhaustive reference: every geode command, every slash command with its thin-vs-daemon routing, and the geode-mcp surface.
- [Research, search, and llms.txt](https://mangowhoiscloud.github.io/geode/docs/runtime/research.md): How GEODE explores: llms.txt-first documentation research, web search delegation, local FTS search, and the llms.txt this site publishes.
- [Auto-trigger sidecar](https://mangowhoiscloud.github.io/geode/docs/runtime/automation.md): The cron-scheduled sidecar that fires the self-improving loop: lock, interval gate, and hook telemetry.
- [Computer use](https://mangowhoiscloud.github.io/geode/docs/runtime/computer-use.md): Local desktop automation behind one tool: a pyautogui harness with an always-HITL safety classification.
- [CLI LaTeX rendering](https://mangowhoiscloud.github.io/geode/docs/runtime/ui/cli-latex.md): Rendering math in the terminal: detection, Unicode flatten, and 2D pretty print with a raw-text fallback.
- [CHANGELOG](https://mangowhoiscloud.github.io/geode/docs/reference/changelog.md): Full version history, synced from CHANGELOG.md on every main push.
- [Petri bundle isolation](https://mangowhoiscloud.github.io/geode/docs/reference/petri-bundle-isolation.md): Operator reference for the publish workflow, validator, and hygiene ratchet.

## Developer and Architecture

- [Architecture deep-dive](https://mangowhoiscloud.github.io/geode/docs/develop/architecture.md): The subsystem map and a recommended reading order, retold as data-flow traces.
- [System index](https://mangowhoiscloud.github.io/geode/docs/architecture/system-index.md): Every subsystem with its file path. The flat catalog.
- [Why five layers](https://mangowhoiscloud.github.io/geode/docs/explanation/4-layer.md): Model, Runtime, Harness, Agent, Self-Improving. Why the boundaries fall where they do.
- [Why a self-hosting harness](https://mangowhoiscloud.github.io/geode/docs/explanation/self-hosting.md): The runtime and the build line share primitives. Why that mattered.
- [Why ratchet discipline](https://mangowhoiscloud.github.io/geode/docs/explanation/ratchet.md): Pinned prompt hashes and a staged CI. The shape that prevents drift.
- [Release and PyPI lifecycle](https://mangowhoiscloud.github.io/geode/docs/ops/release-pypi-lifecycle.md): Version locations, verified GitHub and PyPI promotion, Homebrew/core admission, and the rebuild cadence.
- [Backlog disposal](https://mangowhoiscloud.github.io/geode/docs/ops/backlog-dispose.md): Retire an idea with a paper trail instead of a silent delete.

## Codebase Map

- [Layer architecture graph](https://mangowhoiscloud.github.io/geode/docs/codebase-map/layer-graph.md): A generation-date snapshot of the repository: 14 analyzed layers sized by files, drawn over their cross-layer import edges, plus a seven-step reading tour. Built by Understand-Anything, not hand-drawn.

## Optional

- [llms-full.txt](https://mangowhoiscloud.github.io/geode/llms-full.txt): the entire docs content in one file (large)
- [CHANGELOG](https://github.com/mangowhoiscloud/geode/blob/main/CHANGELOG.md): full release history
- [CLAUDE.md](https://github.com/mangowhoiscloud/geode/blob/main/CLAUDE.md): development scaffold and quality gates
- [AGENTS.md](https://github.com/mangowhoiscloud/geode/blob/main/AGENTS.md): agent-facing repo guide