# AGENTS.md

> Code-root navigation map for AI agents (Claude Code, Cursor, Codex CLI,
> etc.) working in this repository. The pattern is adapted from OpenClaw's
> `AGENTS.md` convention.
>
> Human-oriented documentation lives under:
> - `docs/` — internal design notes
> - `site/src/app/docs/` — public site (`mangowhoiscloud.github.io/geode/docs`)
>
> This file is the LLM entry point. Read this first when changing code.

## Project at a glance

- **What**: a self-hosting autonomous-agent harness on top of LangGraph.
- **Language**: Python 3.12+, type-hinted, uv-managed.
- **Layout**: two top-level packages.
  - `core/` — domain-agnostic runtime.
  - `plugins/` — domain extensions (currently `petri_audit`).
- **Quality bar**: ruff, mypy, pytest plus a prompt-hash ratchet. CI breaks on red.
- **Public site**: `site/` (Next.js 16 static export, deployed to GitHub Pages).

For SOT metrics (version, module count, tests, releases), read
`site/src/data/geode/sot.ts` (auto-generated by `npm run sync-stats`) or
`CLAUDE.md` (development scaffold).

## Module map

Read the module you are about to change. If a section says "read this first",
do it. Cross-cutting changes require reading all related modules.

### `core/agent/`

The agentic loop. `while(tool_use)` primitive that drives every turn.

- `loop/agent_loop.py` — `AgenticLoop`. No round limit by default
  (`DEFAULT_MAX_ROUNDS = 0` → unlimited; time-budget controlled),
  5 termination paths (`model_action_required`,
  `user_clarification_needed`, etc.). Auto-escalation was removed in
  v0.90.0. The model itself emits the termination signal.
- `system_prompt.py` — `build_system_prompt()`. Inserts the
  `__GEODE_PROMPT_CACHE_BOUNDARY__` marker between STATIC and DYNAMIC blocks.
  Since v0.93 the DYNAMIC block is wrapped in `<dynamic_context>` XML.
- `subagent.py` — `MAX_CONCURRENT=5`, `SessionLane` slot allocation.

Read this first when changing termination paths, loop bounds, or system prompt
assembly.

### `core/llm/`

LLM router, providers, prompt assembly, hashing.

- `prompt_assembler.py` — `PromptAssembler.assemble()`. Six-step assembly
  producing an immutable `AssembledPrompt`. Emits `PROMPT_ASSEMBLED` hook.
- `providers/anthropic.py` — `messages.stream()` async context (v0.95+).
- `providers/openai.py` — Responses API, HTML data-URL guard (v0.94+),
  `prompt_cache_key` auto-derivation (v0.94+).
- `providers/glm.py` — GLM 5.x family. Context window 202_752 (not 200_000).
  Thinking gate (`thinking.type="off"|"none"`).
- `providers/codex.py` — OAuth + reasoning sidecar.
- `prompts/__init__.py` — `_PINNED_HASHES` (18 entries). Karpathy P4 ratchet.
- `prompts/*.md` — 6 base templates plus 9 extended templates and 3 axes datasets.
- `postprocess/html_output.py` — strips OpenAI data-URL HTML.

Read this first when changing prompt content (will break the hash ratchet),
adding a provider, or touching cache/tool-choice/streaming behaviour.

### `core/tools/`

57 tools. Deferred-loading registry.

- `base.py:35` — `Tool` Protocol.
- `registry.py:209-218` — `ALWAYS_LOADED_TOOLS` frozenset (6 tools).
- `definitions.json` — single SOT for tool metadata.
- Category modules: `file_tools.py`, `memory_tools.py`, `data_tools.py`,
  `computer_use.py`, `web_tools.py`, `profile_tools.py`, etc.

Read this first when adding a tool: define handler in a category module,
register in `registry.py`, expose schema in `definitions.json`.

### `core/mcp/`

MCP server adapters plus 25K result guard.

- `manager.py` — `MCPManager`.
- `stdio_client.py` — STDIO transport.
- Calendar / Steam / etc. adapters.

### `core/memory/`

5-tier context hierarchy. Vault. Bidirectional learning.

- `context.py:46` — `ContextAssembler`. Five tiers: Identity / Profile / Org /
  Project / Session.
- `vault/` — agent-produced artifact storage.

Read this first when changing memory tiers, context budgets, or the 200K
absolute token guard.

### `core/hooks/`

69 lifecycle events across 14 categories.

- `system.py:28` — `HookEvent` enum.
- `system.py:200` — `HookSystem` class. Three trigger modes:
  `trigger`, `trigger_with_result`, `trigger_interceptor`.

Read this first when adding an event or wiring an interceptor.

### `core/wiring/`

Bootstrap, serve, shutdown. Renamed from `core/lifecycle/` in v0.87.

- Manages ContextVar injection order.
- Cold-start lazy loading (cumulative −258ms, warm −86%, v0.85-89).

### `core/server/`

IPC daemon. Thin CLI ↔ daemon protocol.

- `ipc_server/poller.py` — receives `client_capability` messages (v0.84).
  Includes `{is_tty, width}` so the daemon can suppress ANSI escapes for
  non-TTY clients.
- `ipc_client.py` — thin-CLI side. Calls `_send_client_capability()` on connect.

### `core/audit/`

Per-call diagnostics for Petri audits (v0.92+).

- `diagnostics.py` — `CallDiagnostic` dataclass. cache_read/write, cost
  breakdown, latency, audit_mode flag.

### `core/automation/`

Sidecar between agent and runtime. Drift detection, model promotion, expert
panel voting.

- `model_registry.py:36` — `PromotionStage` (development, staging, production).
- `feedback_loop.py` — phase FSM.
- `drift.py` — correlation + severity analysis.
- `expert_panel.py` — junior / senior / principal voting tiers.
- `outcome_tracking.py` — long-tail outcome recording.

### `core/skills/`

Runtime SkillRegistry. Distinct from scaffold `.claude/skills/`.

- `skill_registry.py` — 5-tier discovery (bundled → user → org → project → session).
- `reports/` — report templates are not bundled in GEODE core.

### `core/verification/`

Schema, Range, Grounding, Coherence guardrails (G1-G4). Specialized bias and
calibration checks belong in external packages.

### `core/scheduler/`, `core/orchestration/`

Natural-language scheduling, LangGraph StateGraph.

### `core/cli/`

Typer commands and thin CLI surface. Slash commands.

### `core/gateway/`

Slack / Discord / Telegram adapters. Lane queue concurrency.

### `plugins/petri_audit/`

Petri × GEODE alignment audit (v0.92+).

- `cli_audit.py` — `geode audit` Typer wrapper.
- `seeds/` — 22 GEODE-specific seeds organised across 3 tiers
  (critical / auxiliary / info), spanning autonomy, calibration,
  compute_use, efficiency, exploratory, reasoning, research.
- `judge_dims/` — judge dimension catalog. Default `subset`
  (`geode_judge_subset.yaml`, 22 dim = 19 default-38 string subset +
  3 PR-0 context-management JudgeDimension dicts) or `full` (38 dim).
- `runner.py`, `audit_mode.py`, `judge_schema.py`, `optimize.py`.

## Workflow constraints

These are absolute. They live in `CLAUDE.md` under "CANNOT". Highlights:

- **Worktree required**: never commit directly on `main` or `develop`. Use
  `git worktree add .claude/worktrees/<name> -b feature/<name> develop`.
- **No CHANGELOG omission**: every functional commit updates `CHANGELOG.md`
  under `[Unreleased]`. The bilingual convention is documented at the top of
  CHANGELOG.md.
- **Prompt hashes are pinned**: changing any prompt under `core/llm/prompts/`
  requires updating `_PINNED_HASHES` in the same commit.
- **No `# type: ignore` proliferation**: fix the type error.

## Where to look for things

| Question | File |
|---|---|
| What does a tool do? | `core/tools/definitions.json` and the category module |
| What models can I use? | `core/llm/providers/<provider>.py` |
| Why a layer? | `core/agent/loop/agent_loop.py` plus `docs/architecture/` |
| How are hooks wired? | `core/hooks/system.py` plus `core/runtime/bootstrap.py` |
| How is cost tracked? | `~/.geode/usage/*.jsonl` plus `core/audit/diagnostics.py` |
| Petri audit run? | `plugins/petri_audit/cli_audit.py` |
| Site docs? | `site/src/app/docs/**` |

## Tests

Each subsystem has `tests/test_<name>.py`. Live tests are marked `-m live`.

Total: 4608 standard plus 24 live (see `site/src/data/geode/sot.ts`).

## Frontier sources

These external systems shape GEODE's design. When you change something here,
verify whether the new shape still echoes its source.

- Claude Code (Anthropic). While-tool-use loop, CLAUDE.md scaffolding, 4-tier
  memory.
- OpenClaw. Gateway-centric routing, Lane Queue, Session isolation,
  Policy Chain, plugin discovery.
- Karpathy autoresearch (2026-03). Fixed wall-budget, frozen scoreboard, git
  monotone ratchet, token-economic loop, simplicity criterion.
- Hermes Agent (NousResearch). llms.txt / llms-full.txt dual index pattern.
- Diátaxis. Documentation 4-quadrant model.

## See also

- `CLAUDE.md` — development workflow scaffold.
- `GEODE.md` — runtime identity and conventions.
- `site/DESIGN.md` — public site visual system.
- `site/src/app/docs/reference/external-references` — cited frontier systems
  with applied patterns.
