EN
Geodi, GEODE's official pixel character
Back to the hall

GEODE

Autonomous Agent Harness

From observation to the next action.

A local autonomous-agent harness you can hand research, file work and scheduled tasks.

2026.02.21 — present

Design, judgment, verification: Author · implementation: Claude · review: Codex

  • CLIPublished · PyPI
  • MCP serverImplemented
Recorded evaluation · MCPMark PostgreSQL · 2026-07-04

Before changing anything, it found what was already there.

The task: row-level security for a social service with five tables.

  1. ResearchCalls 1–12 · list_objects, get_object_details, execute_sqlRead the five tables, four helper functions already in place, RLS off on all five, and the policies, privileges and roles.
  2. ActCall 13 · execute_sqlOne transaction: 20 policies and RLS on, reusing 3 existing helpers and adding 3 functions.
  3. VerifyEvaluation harness · not an agent call18 passed, 0 failed. All 13 tool responses over 9 turns came back without an error.
Verifier output, 18 lines (verbatim)
  1. RLS enabled on users
  2. RLS enabled on channels
  3. RLS enabled on channel_moderators
  4. RLS enabled on posts
  5. RLS enabled on comments
  6. Users can update their own profile
  7. Users blocked from updating other users' profiles
  8. Channel owners can update their channels
  9. Non-owners blocked from updating channels
  10. Post authors can update their posts
  11. Channel moderators can update posts in their channels
  12. Unauthorized users blocked from updating posts
  13. Comment authors can update their comments
  14. Post authors can moderate comments on their posts
  15. Channel owners can add moderators
  16. Non-owners blocked from adding moderators
  17. Content visibility varies correctly based on user context
  18. Anonymous users can see 3 public user profiles (correct)

A past run in a configured evaluation sandbox, not a live database or a real security incident. Row counts before the policies are not in the record, so none are shown. Public run record (meta.json, commit 23e3428)

Reviewing a result and repairing it (Reflexion-inspired, within the same task) is a capability of the current GEODE runtime. No such repair appears in this record: every tool response came back without an error. Runtime documentation (hook-system.md)

The model picks the next action; the host keeps the execution boundary.

The runtime from a request entering a session, through the model call and the authority checks on each proposed tool call, to execution, results and records. Pick a flow to highlight only its path, with numbered steps.

The model chooses the next action; the runtime checks tool permissions and decides when the work is complete.

External Scaffold Search / SIL experiments began May 15, 2026

Install the geode-agent package from PyPI or the public repository and run it from your own terminal. It can also be reached as an MCP server.

Runtime architecture · drawn from the code paths at pinned commit 9e2c041
GEODE runtime architectureComponents and connections of the GEODE runtime process. Requests arrive through terminal IPC, messengers or an external MCP host and become a session; AgenticLoop calls the model with the system prompt, conversation and tool schemas. A tool call the model proposes runs only after ToolExecutor’s scope, policy, schema, hook and approval checks pass, and its result becomes the next model input. The checkpoint, the timeline and the evidence rows are separate stores.Terminal userREPL · thin CLIMessenger channelSlack · Discord · TelegramExternal MCP hostrun_agent toolLLM providersHTTPS · model APIsFiles · git · processesstate outside checkpointsMCP serversglobal + trusted projectcore/serverCLIPoller · IPC socketmessenger pollerscore/mcp_server.pyrun_agent · one-shotsupervised/services.pySharedServices.create_sessionLaneQueue · session · globalcore/agent/loopAgenticLoop · six phasessystem prompt · declared sourcesmessages · ConversationContextcore/llm/adaptersadapter.acomplete · error classestool_executor/processor.pyToolCallProcessorcore/tools/plan.pyBoundToolPlan · immutabletool_executor/executor.pyscope · policy · schemaPreToolUse · PostToolUseapproval · HITLeffect receiptresource lock · dispatchcore/toolstool handlers · bash · computercore/mcp/manager.pyMCPServerManagermemory/session_checkpoint.pySQLite messages · state.jsonmemory/effect_receipts.pyEffectReceiptStoreobservability/session_timeline.pySessionTimeline · append-onlyagent/evidence_ledger.pyEvidenceLedger · JSONLcore/agent/verify.pyverify_turn_asynccore/hooksHookRegistry · decisionsHookSystem · observationGEODE runtime processserve daemon · REPL · one-shotEntry · session compositionRun loop · model callTool authority · effectsRecords · recovery · completion1 prompt · cli.sock · Terminal user → CLIPoller · IPC socket12 create_session(IPC) · CLIPoller · IPC socket → SharedServices.create_session23 lane per request · CLIPoller · IPC socket → LaneQueue · session · global34ToolExecutor · AgenticLoop5arun(prompt)6system prompt7messages8tool schemas9StepSnapshot · request10HTTPS11 response · tool_use · adapter.acomplete · error classes → AgenticLoop · six phases111pending batch · round save2tool_use blocks3 aexecute · ToolCallProcessor → scope · policy · schema34allowed · safety level5PreToolUse · PostToolUse6approval request7 denied before execution · tool_executor/executor.py → ToolCallProcessor78effect admit · commit9handler call10 MCP call · resource lock · dispatch → MCPServerManager1011 tools/call · MCPServerManager → MCP servers1112 file · git · process changes · tool handlers · bash · computer → Files · git · processes1213 result · post-dispatch error · tool_executor/executor.py → ToolCallProcessor1314tool_result15call · result observation1pending batch · round save2resume restore3turn record4completion check5PostVerify · Stop6evidence rows · best-effort7cognitive · lifecycle events1channel message2 create_session(DAEMON) · messenger pollers → SharedServices.create_session23arun(message)4run_agent(prompt)5headless one-shot loop

Request → model call

A terminal request arrives over IPC, a session is composed, and the loop calls the model with the system prompt, conversation and tool schemas.

  1. Terminal userprompt · cli.sockCLIPoller · IPC socketcore/server

    The thin CLI sends the request to the serve daemon’s IPC socket (~/.geode/cli.sock). The REPL runs the same session composition in-process.

  2. CLIPoller · IPC socketcore/servercreate_session(IPC)SharedServices.create_sessionsupervised/services.py

    Each connection composes a session. The mode sets the HITL level, time budget and denied tools, and projects the BoundToolPlan onto the chosen provider.

  3. CLIPoller · IPC socketcore/serverlane per requestLaneQueue · session · globalsupervised/services.py

    Before running a request, the session lane and the global lane are both held, which limits concurrent runs.

  4. SharedServices.create_sessionsupervised/services.pyToolExecutor · AgenticLoopAgenticLoop · six phasescore/agent/loop

    Builds the executor and the loop as one pair that shares the hooks, MCP, skills and resource locks.

  5. LaneQueue · session · globalsupervised/services.pyarun(prompt)AgenticLoop · six phasescore/agent/loop

    Runs one user turn in six phases: prepare input, prepare the call, call the provider, process tools, observe and compact, terminate.

  6. system prompt · declared sourcescore/agent/loopsystem promptadapter.acomplete · error classescore/llm/adapters

    Built each turn from declared sources such as selected GEODE.md sections and rules. ContextAssembler’s five-tier facade is used only when called explicitly; it is not the default loop’s input.

  7. messages · ConversationContextcore/agent/loopmessagesadapter.acomplete · error classescore/llm/adapters

    The conversation and earlier tool results travel separately from the system prompt.

  8. BoundToolPlan · immutablecore/tools/plan.pytool schemasadapter.acomplete · error classescore/llm/adapters

    Only the tools of the BoundToolPlan bound to this step are visible to the model. It is an immutable snapshot with a generation and a content hash.

  9. AgenticLoop · six phasescore/agent/loopStepSnapshot · requestadapter.acomplete · error classescore/llm/adapters

    The StepSnapshot fixes this call’s model, tools and correlation IDs. LLM middleware cannot swap a bound adapter.

  10. adapter.acomplete · error classescore/llm/adaptersHTTPSLLM providers

    A per-provider adapter makes the call. Failures are classified and retried only within a set limit, or end the turn with a termination reason.

  11. adapter.acomplete · error classescore/llm/adaptersresponse · tool_useAgenticLoop · six phasescore/agent/loop

    Text alone goes to termination; tool_use goes to tool processing.

Tool authority → effect → result

A tool_use proposal runs only after every check passes; denials, results and errors all return from the executor and become the next model input.

  1. AgenticLoop · six phasescore/agent/looppending batch · round saveSQLite messages · state.jsonmemory/session_checkpoint.py

    In a session with checkpointing configured (a checkpoint and a session id), the proposed batch is saved before any tool runs, and the batch does not run if it cannot be saved. The completed batch is saved again. Callers without a checkpoint do not get this guarantee.

  2. AgenticLoop · six phasescore/agent/looptool_use blocksToolCallProcessortool_executor/processor.py

    A model proposal is not permission. Each call gets a ToolContext carrying the loop’s model and adapter identity.

  3. ToolCallProcessortool_executor/processor.pyaexecutescope · policy · schematool_executor/executor.py

    Checks session scope, request-middleware rewrites, policy and schema in turn. A rewrite that lowers the safety level or the personal-data class is denied.

  4. BoundToolPlan · immutablecore/tools/plan.pyallowed · safety levelscope · policy · schematool_executor/executor.py

    Executable handlers and safety levels come from the BoundToolPlan projected for the session.

  5. PreToolUse · PostToolUsetool_executor/executor.pyPreToolUse · PostToolUseHookRegistry · decisionscore/hooks

    Public hooks decide block, argument rewrite or permission request, and a rewrite is followed by scope, policy and schema checks again. After execution, a hook may add context or withhold the result.

  6. approval · HITLtool_executor/executor.pyapproval requestTerminal user

    In an IPC session the approval request is relayed to the thin CLI. Modes without a person apply the deny policy by default; the one exception is DAEMON computer use, when an operator separately enables it (blocked otherwise).

  7. tool_executor/executor.pydenied before executionToolCallProcessortool_executor/processor.py

    A scope, policy or schema rejection, a PreToolUse block or a refused approval returns as an error result without dispatch. In that case no effect of this call began.

  8. effect receipttool_executor/executor.pyeffect admit · commitEffectReceiptStorememory/effect_receipts.py

    Effects such as file changes, outbound messages or administrative actions are admitted before they run. An uncertain outcome is not run again; it asks for reconciliation.

  9. resource lock · dispatchtool_executor/executor.pyhandler calltool handlers · bash · computercore/tools

    Dispatches to the bound handler after locking its resource keys. A call aborted at its deadline may still be running outside.

  10. resource lock · dispatchtool_executor/executor.pyMCP callMCPServerManagercore/mcp/manager.py

    Only MCP tools with a declared resource policy are called.

  11. MCPServerManagercore/mcp/manager.pytools/callMCP servers

    The server catalog comes from global settings and from project settings that passed the trust check; that check applies to project entries only. The MCP manager applies its extension and resource policy.

  12. tool handlers · bash · computercore/toolsfile · git · process changesFiles · git · processes

    Executed changes stay as outside state. The checkpoint recovers the conversation only and does not undo them.

  13. tool_executor/executor.pyresult · post-dispatch errorToolCallProcessortool_executor/processor.py

    After dispatch, normal results and errors (including timeouts and uncertain outcomes) return through PostToolUse. An error or timeout does not mean the outside work stopped or was undone.

  14. ToolCallProcessortool_executor/processor.pytool_resultmessages · ConversationContextcore/agent/loop

    Results, denials and errors alike are serialized as tool_result and become messages in the next model input.

  15. ToolCallProcessortool_executor/processor.pycall · result observationSessionTimeline · append-onlyobservability/session_timeline.py

    Writes the call and its result (ok or error) to the timeline, including calls denied before execution. The record is observation; it does not prove that an outside effect began or succeeded.

Records · recovery · completion

The checkpoint, timeline and evidence rows are written separately. There is no shared transaction, and the checkpoint recovers the conversation only.

  1. AgenticLoop · six phasescore/agent/looppending batch · round saveSQLite messages · state.jsonmemory/session_checkpoint.py

    In a session with checkpointing configured (a checkpoint and a session id), the proposed batch is saved before any tool runs, and the batch does not run if it cannot be saved. The completed batch is saved again. Callers without a checkpoint do not get this guarantee.

  2. SQLite messages · state.jsonmemory/session_checkpoint.pyresume restoreAgenticLoop · six phasescore/agent/loop

    One restore path brings back messages, cognitive state and guard counters. The process-local TaskGraph is not recovered.

  3. AgenticLoop · six phasescore/agent/loopturn recordSessionTimeline · append-onlyobservability/session_timeline.py

    An append-only execution history, never replayed as state.

  4. AgenticLoop · six phasescore/agent/loopcompletion checkverify_turn_asynccore/agent/verify.py

    The model’s proposal to stop becomes completion only through Verify.

  5. verify_turn_asynccore/agent/verify.pyPostVerify · StopHookRegistry · decisionscore/hooks

    Public hook decisions say whether to continue with a repair, and repairs happen only within a set budget (two by default).

  6. AgenticLoop · six phasescore/agent/loopevidence rows · best-effortEvidenceLedger · JSONLagent/evidence_ledger.py

    Redacted diagnostic rows. Hashes support correlation; a row does not prove an effect happened, and it is not written in one transaction with the timeline or checkpoint.

  7. AgenticLoop · six phasescore/agent/loopcognitive · lifecycle eventsHookSystem · observationcore/hooks

    Observation hooks receive and record events; they do not decide execution.

Other entry paths

Messengers enter as DAEMON sessions of the serve daemon; an external MCP host’s run_agent enters a separately built headless one-shot loop.

  1. Messenger channelchannel messagemessenger pollerscore/server

    The serve daemon’s pollers handle messages from bound channels only.

  2. messenger pollerscore/servercreate_session(DAEMON)SharedServices.create_sessionsupervised/services.py

    A mode with no person to approve: the default deny policy and a time budget apply. Only computer use can be separately enabled by an operator; without that it stays blocked.

  3. messenger pollerscore/serverarun(message)AgenticLoop · six phasescore/agent/loop

    A thread keeps one fixed session id and continues one checkpoint chain.

  4. External MCP hostrun_agent(prompt)run_agent · one-shotcore/mcp_server.py

    An external MCP host calls GEODE as a tool.

  5. run_agent · one-shotcore/mcp_server.pyheadless one-shot loopAgenticLoop · six phasescore/agent/loop

    A separately built headless executor and loop that bypass SharedServices. The default denylist applies as is, so tools such as run_bash, delegate_task and computer are removed; the DAEMON computer-use exception does not exist here.

Every connection at the same weight. Pick a flow to highlight only its path, with numbered steps.

  • Solid · the direction requests, messages and tool results flow
  • Dashed · session composition, authority or verdict; not a data path
  • Long dash-dot · records and observation; never replayed as state
  • Short dash · denial before execution, no effect
  • Heavy black line · the selected flow; numbers give the order
  • Box · a code-owning boundary, its source path in the header
  • Inner chip · a component inside that boundary
  • Dashed box · outside the runtime process
  • Orange outline · where a model decides
  • Run loop
  • Authority · verdicts
  • Record stores
  • Entry · connection · execution

Only connections whose calls were confirmed are drawn. ContextAssembler’s five-tier facade, the TaskGraph and research experiments such as Jev, SIL and Crucible are not on this runtime path. Async cancellation does not stop synchronous work already started or undo effects that happened.

Supported models · by provider

The code’s catalog choices and shipped defaults, not a list in which every model passed a live API call. Configured fallback chains are empty by default, and exact IDs are never upgraded to newer versions automatically.

  • Anthropic

    API

    • PrimaryClaude Opus 5.5claude-opus-5-5Default
    • SecondaryClaude Sonnet 5claude-sonnet-5Default
    • BudgetClaude Haiku 4.5claude-haiku-4-5-20251001Default
    Show all 12 catalog IDs

    API

    • claude-fable-5-1
    • claude-opus-5-5default
    • claude-opus-5
    • claude-sonnet-5default
    • claude-haiku-4-5-20251001default
    • claude-fable-5
    • claude-opus-4-8
    • claude-opus-4-7
    • claude-opus-4-6
    • claude-opus-4-5
    • claude-sonnet-4-6
    • claude-sonnet-4-5-20250929

    The code rejects the subscription OAuth route.

  • OpenAI

    API · Codex subscription

    • API and Codex defaultGPT-6 Solgpt-6-solDefault
    Show all 11 catalog IDs

    API · Codex subscription

    • gpt-6-astra
    • gpt-6-soldefault
    • gpt-6-luna
    • gpt-5.6-sol
    • gpt-5.6-terra
    • gpt-5.6-luna

    API only

    • gpt-5.5
    • gpt-5.3-codex
    • gpt-5.4
    • gpt-5.4-mini
    • gpt-5.4-nano

    Two access routes to one provider; the catalog sets which routes each model allows.

  • Z.ai / GLM

    PAYG

    • DefaultGLM-5.3glm-5.3Default
    Show all 9 catalog IDs

    PAYG

    • glm-5.3default
    • glm-5.3-flash
    • glm-5.3-flashx
    • glm-5.2
    • glm-5.1
    • glm-5
    • glm-4.7
    • glm-4.7-flashx
    • glm-4.7-flash

    The code does not admit the GLM Coding Plan route.

  • OpenRouter

    Routing service

    • PickerFree (smoke)openrouter/openrouter/freeRouter
    • PickerAuto (variable)openrouter/openrouter/autoRouter

    Router selections, not one fixed model. Explicitly configured IDs can also be kept.

  • TypeSafe / Jev

    Decision-only · separate from text generation

    • Directjev-1.13.0Decision-only
    • Through OpenRoutertypesafe/jev-1.13Decision-only

    An optional adapter that only makes judgments; it is not a root text-generation model. The default judgment engine is llm, and Jev has to be selected. The Jev study’s own configurations follow the Jev view’s records.

SourceGEODE main 373d420Public commit October 7, 2026 · checked October 8, 2026

Experiments

Models and routes as recorded at the time, not current defaults or a complete compatibility list.