A minimal, installable template for the hex agent system — a persistent AI workspace for Claude Code that accumulates context, learns your patterns, and improves itself over time.
For: engineers on Claude Code who are tired of their agent starting from zero every session.
git clone https://github.com/mrap/hex-foundation /tmp/hex-setup && bash /tmp/hex-setup/install.sh && cd ~/hex && claudeYour agent walks you through setup on first run. Three questions, then you're working.
If your existing hex instance has .claude/scripts/, .claude/skills/, etc., you're on the v1 layout. /hex-upgrade won't cleanly pull foundation v0.2.1+ content until you migrate. One line from your hex dir:
bash <(curl -fsSL https://raw.githubusercontent.com/mrap/hex-foundation/v0.2.2/bootstrap-migrate.sh)Full guide: docs/migrate-v1-to-v2.md.
- Python 3.9+
- git
- Claude Code CLI (
claude) — warning-only; install separately - Rust / cargo (rustup.rs) — required to build the
hexbinary from source; without it, install attempts a pre-built binary download
The installer sets up ~/.boi (BOI worker fleet) and deploys hex-events from system/events/ to ~/.hex-events. BOI version pinned in VERSIONS.
bash install.sh # installs to ~/hex
bash install.sh ~/my-hex # custom locationTo use a fork of BOI, set HEX_BOI_REPO before running install. hex-events ships inline at system/events/ — no external repo needed.
After install, ~/hex/ contains:
~/hex/
├── CLAUDE.md Operating model for Claude Code (system zone + your zone)
├── AGENTS.md Operating model for other agents (Codex, Cursor, etc.)
├── todo.md Your priorities and action items
├── me/ About you — me.md (stable), learnings.md (observed patterns)
├── projects/ Per-project context, decisions, meetings, drafts
├── people/ Profiles and relationship notes
├── evolution/ Self-improvement engine — observations, suggestions, changelog
├── landings/ Daily outcome targets
├── raw/ Transcripts, handoffs, unprocessed input
├── specs/ BOI spec drafts
├── .hex/ System files (scripts, skills, memory.db) — managed
└── .claude/commands/ Claude Code slash commands — managed
Companion systems installed alongside:
~/.boi— parallel Claude Code worker dispatch~/.hex-events— reactive event policies (deployed fromsystem/events/— no external repo)
- Claude Code hooks —
install.shwritesPreToolUse,PostToolUse,Stop, andSessionStarthooks into.claude/settings.jsonautomatically. No manual hook setup required. - Default event policies — a starter set of hex-events policies is deployed to
~/.hex-events/policies/during install, enabling out-of-the-box reactivity (agent lifecycle, scheduler, BOI completion events).
Persistent memory. Every observation, decision, and learning gets written to a file — not summarized into a chat bubble that disappears. A SQLite FTS5 index at .hex/memory.db makes all of it searchable. With fastembed + sqlite-vec installed, the indexer upgrades to hybrid semantic + keyword search automatically; FTS5-only is the default when those libraries aren't present.
Operating model. CLAUDE.md ships with 20 core standing orders, a learning engine that records observations to me/learnings.md with evidence and dates, and an improvement engine that detects friction, proposes fixes after 3+ occurrences, and tracks what ships.
Two-zone CLAUDE.md. The system zone is managed by upgrades; your zone is preserved byte-for-byte. Add your own rules without losing them on every update.
<!-- hex:system-start — DO NOT EDIT BELOW THIS LINE -->
... managed by hex
<!-- hex:system-end -->
<!-- hex:user-start — YOUR CUSTOMIZATIONS GO HERE -->
- Always check Jira before starting feature work
- Prefer rebase over merge
<!-- hex:user-end -->Decision records. Every decision gets logged to me/decisions/ (or projects/{project}/decisions/) with date, context, reasoning, and impact. A template ships at .hex/templates/decision-template.md. The /hex-decide command walks through the full framework.
These are Claude Code slash commands, not shell CLIs. Use them inside a claude session running in your hex directory.
| Command | What it does |
|---|---|
/hex-startup |
Session init. Loads priorities, today's landings, pending reflection fixes. Triggers onboarding on first run. |
/hex-checkpoint |
Mid-session save. Distill pass, handoff file, landings update. |
/hex-shutdown |
Session close. Quick distill, deregister session. |
/hex-reflect |
Session reflection. Extract learnings, identify failures, propose standing order candidates. |
/hex-consolidate |
System hygiene. Audit operating model for contradictions, staleness, orphaned refs. |
/hex-debrief |
Weekly walk-through of projects, org signals, relationships, career. |
/hex-decide |
Structured decision framework — context, options, reasoning, impact. |
/hex-triage |
Route untriaged content from raw/ to the right files. |
/hex-doctor |
Health check. 20-point validation across env, memory, structure, config, and companions. Use --fix to repair auto-fixable issues, --json for machine-readable output. |
/hex-upgrade |
Pull latest system files from hex-foundation. Handles v1→v2 layout migration. Runs doctor after. |
Inside your hex instance directory:
bash .hex/scripts/upgrade.shOptions:
--dry-run— show what would change--local PATH— use a local hex-foundation checkout instead of fetching--skip-boi/--skip-events— skip a companion
What it does:
- Backs up
.hex/to.hex-upgrade-backup-YYYYMMDD/ - Detects source layout (v1
dot-claude/or v2system/) and maps paths accordingly - Replaces
.hex/(preservingmemory.db) - Merges
CLAUDE.md: system zone replaced, user zone preserved - Runs
doctor.sh
Your data (me/, projects/, people/, evolution/, landings/, raw/, todo.md) is never touched.
You can also run the upgrade from inside Claude Code via /hex-upgrade.
AGENTS.md ships for Codex, Cursor, Gemini CLI, Aider, or any agent that reads a markdown operating-model file. Slash commands are Claude Code-specific.
| Runtime | Status | Notes |
|---|---|---|
| Claude Code | Full support | Primary development runtime |
| Codex (OpenAI) | Partial | Core scripting and agent wakes are broken; see below |
Broken (will not work without code changes):
- Agent wakes / headless invocation: the harness (
harness/src/claude.rs) andenv.shhardcode theclaudebinary and--output-format jsonflag. Codex usescodex exec --json. No runtime abstraction exists yet. - Hook installation:
doctor.shonly writes hooks to.claude/settings.json. Codex reads~/.codex/config.toml(TOML format). Hooks are silently uninstalled for Codex users. - Wake scripts: generated by
hex-agent-spawn.sh, callclaudedirectly — they will fail on a system where onlycodexis installed.
Partial (works differently):
- Hooks: event names (
PreToolUse,PostToolUse,Stop,SessionStart) match, but the config file is~/.codex/config.toml(TOML), not.claude/settings.json(JSON). Hook contents transfer; the installer doesn't write them for Codex. - Skills: skill format (SKILL.md) is compatible. Discovery path differs: Codex looks in
.codex/skills/, hex installs to.hex/skills/. - Slash commands: Codex supports custom commands from
.claude/commands/*.mdbut does not auto-invoke them — users must type/commandnamemanually. Claude Code auto-invocation does not apply. - Memory: Codex has a memory feature (
memories = trueinconfig.toml) stored at~/.codex/memory/globally. Claude Code auto-populates~/.claude/projects/<dir>/per project. Different opt-in model and path. - MCP servers: both runtimes support MCP. Config format differs: hex uses
.mcp.json(JSON), Codex uses[mcp_servers]inconfig.toml(TOML). - Session resume: supported on both; Codex uses
codex resume <SESSION_ID>or--last. CLAUDE.md: Codex reads it as a fallback when noAGENTS.mdis present.AGENTS.md(included in this repo) is the preferred file for Codex.
Works without changes:
CLAUDE.md/AGENTS.mdoperating modeldoctor.shLLM preference detection and.codex/config.tomlcreation- Hook event names are identical across both runtimes
- All file-based memory and project context
hex is a unified Rust binary — core infrastructure, not optional. One binary handles:
- Agent harness (
hex agent) — fleet management, wakes, cost tracking, gate validation, initiative execution - HTTP/SSE server (
hex server) — serves all web surfaces, real-time event bus with namespaced topics - Asset registry (
hex asset) — unified{type}:{id}namespace for all hex artifacts - Comment system (
hex comment) — feedback on any asset, routed to agents via LLM classification
Subcommands:
hex agent wake/fleet/status/message/list — agent fleet management
hex server start — HTTP server + SSE bus (port 8880)
hex asset resolve/list/search/types — asset registry
hex comment respond/list — comment management
hex sse publish/topics — SSE bus operations
hex version — print version
Backward compatibility: hex-agent is a symlink to hex. Existing scripts and policies that call hex-agent continue to work unchanged.
Requirements: Rust toolchain (for building from source) or a supported platform for pre-built binaries (macOS arm64/x86_64, Linux x86_64).
The binary is built or downloaded automatically by install.sh. If it cannot be built or downloaded, install warns and continues — core scripting still works, but agent wakes, the server, and fleet management require the binary. Run hex-doctor to verify status after install.
version.txt at the repo root is the single source of truth. build.rs injects it at compile time. Cargo.toml must match. Git tags must match. See docs/versioning.md.
The server includes a real-time event bus with namespaced topics (content.comments, system.agents, system.boi, content.assets). Clients subscribe via GET /events/stream?topics=content.*. Topic manifests at .hex/sse/topics/*.yaml define the contract — adding a topic means adding a YAML file, not editing bus code. hex-events are bridged to SSE via a policy, so any backend event becomes observable in real time.
hex ships a Quality Antagonist: an adversarial checker that validates completed work is real, not gamed.
What it detects:
- Metric commands that are trivially rewritten (
echo 0→echo 1) rather than measuring real behavior - KRs marked "met" where the independent measurement disagrees with the claimed value
- Math errors (
lower_is_betterKRs wherecurrent > targetyetstatus = met) - Specs that complete suspiciously fast relative to their described scope
- File-existence proxies (script exists ≠ script runs)
How it works:
boi.spec.completed → quality-spec-audit policy → quality-check.py --spec <id>
initiative.kr.met → quality-kr-check policy → quality-check.py --kr <init>/<kr>
timer.tick.6h → quality-sweep policy → quality-check.py --sweep
↓
hex.quality.gaming.detected
hex.quality.kr.reverted
hex.quality.suspect
The antagonist runs independently — it does not trust the metric command the worker used. It re-runs the metric, checks the math, and reverts KR status if fraud is confirmed. The charter lives at system/reference/core-agents/quality-antagonist.yaml.
CLI:
python3 .hex/scripts/quality-check.py --spec q-123 # audit one spec
python3 .hex/scripts/quality-check.py --kr init-foo/kr-1 # reality-check a KR
python3 .hex/scripts/quality-check.py --sweep # scan last 24hhex-foundation/
├── install.sh Single install entrypoint
├── version.txt Repo-level version (read by Rust build.rs)
├── VERSIONS Pinned boi version (hex-events is now inline)
├── system/ → becomes ~/hex/.hex/ on install
│ ├── harness/ ← hex binary Rust source (agent + server + SSE + assets + comments)
│ │ ├── src/main.rs unified CLI (hex agent/server/asset/comment/sse)
│ │ ├── src/server.rs HTTP server + reverse proxy
│ │ ├── src/sse.rs SSE bus (topics, subscriptions, publish)
│ │ ├── src/comments.rs comment API handler
│ │ ├── src/assets.rs asset registry handler
│ │ ├── src/telemetry.rs request + event telemetry (append-only JSONL)
│ │ ├── src/wake.rs agent wake cycle
│ │ └── build.rs reads version.txt at compile time
│ ├── events/ ← hex-events daemon, emitter, CLI (merged from hex-events repo)
│ │ ├── hex_eventd.py main daemon
│ │ ├── hex_emit.py event emitter
│ │ ├── hex_events_cli.py CLI
│ │ ├── actions/ action handlers (shell, emit, notify, render, update_file)
│ │ ├── adapters/ scheduler and timer adapters
│ │ ├── policies/ built-in default policies (boi-lifecycle, capture, etc.)
│ │ └── docs/ hex-events documentation
│ ├── sse/
│ │ └── topics/ ← SSE topic manifests (content.comments, system.agents, etc.)
│ ├── scripts/ startup.sh, doctor.sh, upgrade.sh, quality-check.py,
│ │ route-comment.py, hex-asset.py, hex-asset-discover.py, ...
│ │ ├── comments-service/ comment widget (widget.js) + Python fallback server
│ │ └── sse-bus/ hex-events → SSE bridge script
│ ├── commands/ → copied to ~/hex/.claude/commands/ (Claude Code slash commands)
│ ├── skills/ memory/ (index+search+save), landings, hex-reflect, hex-decide,
│ │ hex-debrief, hex-consolidate, hex-doctor, hex-checkpoint,
│ │ hex-shutdown, hex-startup, hex-triage
│ ├── policies/ quality-spec-audit, quality-kr-check, quality-sweep,
│ │ quality-gaming-alert — event-driven quality gates
│ ├── reference/ core-agents/ — quality-antagonist and fleet agent charters
│ └── version.txt
├── templates/ Seeds for CLAUDE.md, AGENTS.md, me.md, todo.md, decision-template.md
├── docs/architecture.md System overview
└── tests/
├── events/ hex-events unit and integration tests
└── ... E2E, layout, and memory tests
The test suite verifies installation, migration, skill discovery, and Codex parity. See docs/testing.md for the full matrix and how to run locally.
Key test files:
| Test | What it verifies |
|---|---|
tests/agent-harness/Dockerfile |
Agent harness E2E — charter discovery, wake, fleet, core drift, messages (43 tests) |
tests/agent-harness/Dockerfile.initiative |
Initiative E2E — auto-seeding, watchdog, scheduled promotion (10 tests) |
tests/agent-harness/Dockerfile.migration |
v0.8.0 migration — binary rename, symlink, backward compat, version (17 tests) |
tests/contract-verification/Dockerfile |
Schema contracts across hex components (22 tests) |
tests/feedback-loops/Dockerfile |
All 4 feedback loops — pivots, escalation, redesign (30 tests) |
tests/codex-parity/Dockerfile |
Codex runtime parity — hooks, skills, memory, agent wake |
tests/test_skill_frontmatter.sh |
Every SKILL.md has valid YAML frontmatter |
tests/test_skill_refs.sh |
All paths referenced inside SKILL.md resolve |
tests/test_e2e.sh |
Full install + doctor + upgrade lifecycle |
tests/migrate/test-migrate.sh |
v1 → v2 migration correctness |
To run the full suite locally:
# Static tests (no API key needed)
bash tests/test_skill_frontmatter.sh
bash tests/test_skill_refs.sh
# Live tests (requires ~/.hex-test.env with ANTHROPIC_API_KEY)
bash tests/eval/run_eval_docker.sh --live # Linux Docker
bash tests/eval/run_eval_macos.sh # macOS Tartv0.8.0 adds: Unified hex binary + 3 new primitives + hex-events merged inline.
- Unified binary:
hex-agentreplaced byhex— single Rust binary with subcommands for agent fleet, HTTP/SSE server, asset registry, and comment system.hex-agentpreserved as symlink for backward compat. - Asset registry: unified
{type}:{id}namespace for all hex artifacts (posts, proposals, specs, decisions, projects). Auto-discovery, periodic re-scan, CLI + HTTP API. - Unified comments: single comment store, embeddable widget, LLM-classified routing to agents, action log with related assets.
- SSE bus: real-time event streaming with namespaced topics (
content.*,system.*), wildcard subscriptions, topic manifests as self-documenting contract. hex-events bridged to SSE. - Telemetry: append-only JSONL for all server requests and events, same pattern as agent harness.
- hex-events merged: standalone hex-events repo (v0.2.0) merged into
system/events/. hex-events repo archived. - Version system:
version.txtis single source of truth,build.rsinjects at compile time. - Migration: install.sh handles upgrading from pre-0.8.0 (standalone
hex-agent→hex+ symlink). 122/122 E2E tests pass in Docker.
v0.3.0 adds: Modular integration bundles + hex-integration CLI. Every external surface (API, MCP, system service, refresh flow) lives in one directory under integrations/<name>/ — manifest, probe, runbook, secrets schema, maintenance scripts, event policies, tests. hex-integration install/uninstall/update/list/validate/status/probe/rotate manages the lifecycle. Compile-step policy coupling: bundle event YAMLs compile into ~/.hex-events/policies/<name>-<stem>.yaml with # generated_from: audit headers. See docs/integrations.md and templates/integrations/_template/.
v0.2.4 adds: Containerized skill discovery tests — static frontmatter validation, internal reference audit, Claude Code skill discovery (all 11 skills), Codex parity test. Both Docker and macOS Tart eval harnesses wired up.
v0.2.3 adds: Codex bake in Docker image + Codex onboarding eval case.
v0.2.2 adds: bootstrap-migrate.sh one-liner for v1 → v2 layout migration, generic migrator with rollback + idempotency, synthetic v1 fixtures + test suite.
v0.2.1 fixed: Hindsight removal, install.sh doctor-clean on fresh install, hidden sync-safe markers.
v0.2.0 shipped: hybrid memory search, 20-check doctor, layout-aware upgrade, decision template, 11 skills.
Next up:
- Hooks pack: transcript backup, reflection dispatch
- Session lifecycle automation (warming → hot → checkpoint transitions)
Open an issue or PR — the system is meant to evolve.
MIT. See LICENSE.