Docs · Evaluation artifacts · 한국어

GEODE v1.0.33 — Autonomous Agent Runtime + Evaluation Substrate

GEODE is a Python agent runtime for research, file work, and scheduled tasks. Its agentic loop calls tools, reads their results, and continues the task. A daemon owns execution and sessions; the terminal client connects over IPC. MCP servers and messaging integrations extend the available tools and channels.

The same distribution includes evaluation tools and experimental scaffold search. These have separate responsibilities from the runtime; see package boundaries.

Quick start

Use Python 3.12+ and uv on macOS or Linux. Git is needed only for source development.

uv tool install geode-agent
geode version
geode setup
geode

The package name is geode-agent; the terminal command is geode. Setup offers ChatGPT sign-in, API-key entry, or an explicit dry-run choice. The terminal client starts the daemon when needed.

Try a request in the session:

Summarize the documents in this directory and cite the source files.
Compare these two design proposals and list the unresolved decisions.

Web access, messaging, and other integrations require their own configuration and permissions. See the setup guide.

Authentication and model selection

Inside a GEODE session:

The OpenAI subscription route calls the Codex backend through an in-process OAuth adapter. It can also read existing Codex credentials; it does not run Codex CLI for inference. Account entitlement and limits still apply. Anthropic uses API keys; the retired Claude CLI subscription route is unsupported.

API-key routes include Anthropic, OpenAI, OpenRouter, and Z.AI. Use hidden terminal prompts instead of placing keys in commands or chat. GEODE-managed provider keys and OAuth accounts are stored in ~/.geode/auth.toml, an owner-only plaintext file, not an OS keychain. Externally supplied environment credentials remain supported.

See provider configuration and authentication for source selection, credential precedence, and account routing.

Optional Jev judgments

GEODE supports Jev judgments through TypeSafe or OpenRouter. Configure a usable credential, then select the judgment route explicitly:

/model judgment typesafe
/model judgment openrouter
/model judgment llm

Choose one route; llm returns to the LLM judgment path. This selection preserves the generative model and effort. Adding a key alone does not enable Jev. Reflection runs after tool-result rounds and before final delivery, subject to runtime guards. See judgment configuration and verification and evaluation for credentials, usage, and the scope of each judgment.

Configuration and operations

Project behavior overrides user defaults. A repository's .env, MCP servers, gateway config, and keys that widen capability (sandbox, computer use, webhooks, storage paths) apply only after geode config trust in that folder. Configuration basics has the full resolution order. Credential resolution also depends on the selected model, source, and account; it is not one flat settings ladder. Google Workspace OAuth has its own account and keyring storage.

geode about                    # Effective model, paths, and daemon status
geode doctor                   # Diagnose local setup and credential availability
geode config explain model     # Show the layers behind a behavior setting
geode update --dry-run          # Preview the update path
geode update                   # Registry install: newest compatible patch
geode update --latest          # Explicitly allow minor/major registry upgrades

Source-checkout updates and customized uv installs have separate handling; see installation and updates. To remove only the uv-installed CLI while keeping runtime data, use uv tool uninstall geode-agent. geode uninstall also removes runtime data; inspect geode uninstall --dry-run first.

Cost guards use observed usage and configured tariffs. They are not a provider billing cap: an in-flight call can exceed a threshold, and missing usage is not zero cost. See usage accounting.

geode starts in the directory where you invoke it; no repository or project configuration is required. Each resolved directory has its own local daemon, reused by later CLI sessions there. Automatic startup does not activate external messaging gateways. geode serve explicitly starts the configured gateway for that workspace; stop its local daemon first if it is already running.

If something fails

• Command not found: check uv tool dir --bin and your shell's PATH.
• Authentication failure: inspect /login status, then sign in or replace the key through /login. Do not paste credentials into diagnostics or issues.
• Unexpected model or setting: inspect geode about, /model, and geode config explain model; running sessions retain admitted settings.
• Daemon connection failure: run geode doctor and check the configured workspace socket and its adjacent serve.log under ~/.geode/run/. Identify the owning process before stopping it; another session may be using it.

Integrations

Messaging. geode serve runs the daemon and configured Slack, Discord, Telegram, and scheduler services. Channel credentials and bindings are opt-in. Remote computer use is disabled in Gateway sessions unless explicitly enabled. See Gateway setup.

MCP client. Attach external tool servers through GEODE's MCP configuration. A server that is not bundled loads only with a grant in ~/.geode/extension-policy.json, and servers defined by a project load only in a trusted folder. See the MCP guide.

MCP server. Configure an MCP client's stdio command as geode-mcp. The core server exposes run_agent, query_memory, and get_health. For HTTP access, geode-mcp --http uses GEODE_MCP_TOKEN bearer authentication; a non-loopback bind without a token is refused. This endpoint can execute agent tools, so access grants execution authority. See the server implementation for its current transport contract.

Package boundaries

Installed code and bundled assets stay separate from mutable state. Scaffold mutation and promotion require a writable GEODE Git checkout.

SIL and Crucible are experimental. They evaluate changes to prompts, tools, and other scaffolding without updating model weights. Safety-audit results and benchmark results have different acceptance contracts. The public record does not establish sustained self-improvement. Start with the self-improving hub or the campaign guide.

Evaluation evidence

Read results with their source revision, task set, model route, effort, timeout, and attempt history. A runtime completion message, a model judgment, and a benchmark verifier result are different observations.

Receipts and privacy-reviewed trajectories are published in the evaluation artifact repository. These tracks do not form a single product score or a frontier-harness ranking.

Development

git clone https://github.com/mangowhoiscloud/geode.git
cd geode
uv sync --locked
uv run geode version

Read AGENTS.md for contributor rules and CONTRIBUTING.md for development and PR guidance. The workflow owns verification and integration; architecture docs own subsystem contracts.

Development guidance in .agents/skills/ is separate from runtime skills in .geode/skills/. Runtime prompt guidance also does not replace executable permission checks. See prompt assembly.

Changelog · Security policy · Apache 2.0 license