{"id":47794973,"url":"https://github.com/mrap/hex","last_synced_at":"2026-05-21T04:04:46.878Z","repository":{"id":342893604,"uuid":"1174840543","full_name":"mrap/hex","owner":"mrap","description":"Persistent AI agent workspace for Claude Code. Accumulates context, learns your patterns, self-improves. Install in 30 seconds.","archived":false,"fork":false,"pushed_at":"2026-04-25T23:44:25.000Z","size":1460,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T01:21:28.768Z","etag":null,"topics":["ai-agent","ai-native","anthropic","claude","claude-code","compound-engineering","developer-tools","productivity"],"latest_commit_sha":null,"homepage":"https://github.com/mrap/hex-foundation#quick-start","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T22:40:35.000Z","updated_at":"2026-04-26T00:13:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mrap/hex","commit_stats":null,"previous_names":["mrap/hexagon-base","mrap/hex","mrap/hex-foundation"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mrap/hex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrap%2Fhex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrap%2Fhex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrap%2Fhex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrap%2Fhex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrap","download_url":"https://codeload.github.com/mrap/hex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrap%2Fhex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32451481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-native","anthropic","claude","claude-code","compound-engineering","developer-tools","productivity"],"created_at":"2026-04-03T16:12:21.281Z","updated_at":"2026-05-21T04:04:46.870Z","avatar_url":"https://github.com/mrap.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- # sync-safe --\u003e\n# hex-foundation\n\nA 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.\n\n**For:** engineers on Claude Code who are tired of their agent starting from zero every session.\n\n---\n\n## Quick start\n\n```bash\ngit clone https://github.com/mrap/hex-foundation /tmp/hex-setup \u0026\u0026 bash /tmp/hex-setup/install.sh \u0026\u0026 cd ~/hex \u0026\u0026 claude\n```\n\nYour agent walks you through setup on first run. Three questions, then you're working.\n\n### Already running hex v1? Migrate to v2\n\nIf 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:\n\n```bash\nbash \u003c(curl -fsSL https://raw.githubusercontent.com/mrap/hex-foundation/v0.2.2/bootstrap-migrate.sh)\n```\n\nFull guide: [docs/migrate-v1-to-v2.md](./docs/migrate-v1-to-v2.md).\n\n### Prerequisites\n\n- Python 3.9+\n- git\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code) (`claude`) — warning-only; install separately\n- Rust / cargo ([rustup.rs](https://rustup.rs)) — required to build the `hex` binary from source; without it, install attempts a pre-built binary download\n\nThe installer sets up `~/.boi` (BOI worker fleet) and deploys hex-events from `system/events/` to `~/.hex-events`. BOI version pinned in [`VERSIONS`](./VERSIONS).\n\n### Install options\n\n```bash\nbash install.sh              # installs to ~/hex\nbash install.sh ~/my-hex     # custom location\n```\n\nTo use a fork of BOI, set `HEX_BOI_REPO` before running install. hex-events ships inline at `system/events/` — no external repo needed.\n\n---\n\n## What you get\n\nAfter install, `~/hex/` contains:\n\n```\n~/hex/\n├── CLAUDE.md         Operating model for Claude Code (system zone + your zone)\n├── AGENTS.md         Operating model for other agents (Codex, Cursor, etc.)\n├── todo.md           Your priorities and action items\n├── me/               About you — me.md (stable), learnings.md (observed patterns)\n├── projects/         Per-project context, decisions, meetings, drafts\n├── people/           Profiles and relationship notes\n├── evolution/        Self-improvement engine — observations, suggestions, changelog\n├── landings/         Daily outcome targets\n├── raw/              Transcripts, handoffs, unprocessed input\n├── specs/            BOI spec drafts\n├── .hex/             System files (scripts, skills, memory.db) — managed\n└── .claude/commands/ Claude Code slash commands — managed\n```\n\nCompanion systems installed alongside:\n\n- **[`~/.boi`](https://github.com/mrap/boi)** — parallel Claude Code worker dispatch\n- **`~/.hex-events`** — reactive event policies (deployed from `system/events/` — no external repo)\n\n### Auto-configured by install.sh\n\n- **Claude Code hooks** — `install.sh` writes `PreToolUse`, `PostToolUse`, `Stop`, and `SessionStart` hooks into `.claude/settings.json` automatically. No manual hook setup required.\n- **Shell completions** — `install.sh` and `upgrade.sh` automatically install shell completions for your current shell (zsh, bash, or fish) after the binary is in place. Idempotent: re-running produces no diff. See [Shell completions](#shell-completions) for manual setup or bespoke paths.\n- **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).\n\n---\n\n## Core ideas\n\n**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.\n\n**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.\n\n**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.\n\n```markdown\n\u003c!-- hex:system-start — DO NOT EDIT BELOW THIS LINE --\u003e\n... managed by hex\n\u003c!-- hex:system-end --\u003e\n\n\u003c!-- hex:user-start — YOUR CUSTOMIZATIONS GO HERE --\u003e\n- Always check Jira before starting feature work\n- Prefer rebase over merge\n\u003c!-- hex:user-end --\u003e\n```\n\n**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.\n\n---\n\n## Slash commands (inside a Claude Code session)\n\nThese are Claude Code slash commands, not shell CLIs. Use them inside a `claude` session running in your hex directory.\n\n| Command | What it does |\n|---------|--------------|\n| `/hex-startup` | Session init. Loads priorities, today's landings, pending reflection fixes. Triggers onboarding on first run. |\n| `/hex-checkpoint` | Mid-session save. Distill pass, handoff file, landings update. |\n| `/hex-shutdown` | Session close. Quick distill, deregister session. |\n| `/hex-reflect` | Session reflection. Extract learnings, identify failures, propose standing order candidates. |\n| `/hex-debrief` | Weekly walk-through of projects, org signals, relationships, career. |\n| `/hex-decide` | Structured decision framework — context, options, reasoning, impact. |\n| `/hex-triage` | Route untriaged content from `raw/` to the right files. |\n| `/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 doctor consolidate` audits for contradictions, staleness, and orphaned refs. |\n| `/hex-upgrade` | Pull latest system files from hex-foundation. Handles v1→v2 layout migration. Runs doctor after. |\n\n---\n\n## Upgrading\n\nInside your hex instance directory:\n\n```bash\nbash .hex/scripts/upgrade.sh\n```\n\nOptions:\n\n- `--dry-run` — show what would change\n- `--local PATH` — use a local hex-foundation checkout instead of fetching\n- `--skip-boi` / `--skip-events` — skip a companion\n\nWhat it does:\n\n1. Backs up `.hex/` to `.hex-upgrade-backup-YYYYMMDD/`\n2. Detects source layout (v1 `dot-claude/` or v2 `system/`) and maps paths accordingly\n3. Replaces `.hex/` (preserving `memory.db`)\n4. Deletion pass: removes files no longer present in foundation (backed up before deletion)\n5. Rebuilds the `hex` binary if the Cargo.toml version changed; verifies the installed binary matches\n6. Merges `CLAUDE.md`: system zone replaced, user zone preserved\n7. Runs `doctor.sh`\n\nYour data (`me/`, `projects/`, `people/`, `evolution/`, `landings/`, `raw/`, `todo.md`) is never touched.\n\nYou can also run the upgrade from inside Claude Code via `/hex-upgrade`.\n\n---\n\n## Multi-agent support\n\n`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.\n\n---\n\n## Supported Runtimes\n\n| Runtime | Status | Notes |\n|---------|--------|-------|\n| Claude Code | Full support | Primary development runtime |\n| Codex (OpenAI) | Partial | Core scripting and agent wakes are broken; see below |\n\n### Codex Limitations\n\n**Broken (will not work without code changes):**\n- **Agent wakes / headless invocation**: the harness (`harness/src/claude.rs`) resolves the `claude` binary via `$CLAUDE_BIN` env var, then `$HOME/.local/bin/claude`, then PATH. Set `CLAUDE_BIN=/path/to/claude` to override (useful for headless/daemon contexts). Codex uses `codex exec --json`. No runtime abstraction for the `--output-format json` flag exists yet.\n- **Hook installation**: `doctor.sh` only writes hooks to `.claude/settings.json`. Codex reads `~/.codex/config.toml` (TOML format). Hooks are silently uninstalled for Codex users.\n- **Wake scripts**: generated by `hex-agent-spawn.sh`, call `claude` directly — they will fail on a system where only `codex` is installed.\n\n**Partial (works differently):**\n- **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.\n- **Skills**: skill format (SKILL.md) is compatible. Discovery path differs: Codex looks in `.codex/skills/`, hex installs to `.hex/skills/`.\n- **Slash commands**: Codex supports custom commands from `.claude/commands/*.md` but does not auto-invoke them — users must type `/commandname` manually. Claude Code auto-invocation does not apply.\n- **Memory**: Codex has a memory feature (`memories = true` in `config.toml`) stored at `~/.codex/memory/` globally. Claude Code auto-populates `~/.claude/projects/\u003cdir\u003e/` per project. Different opt-in model and path.\n- **MCP servers**: both runtimes support MCP. Config format differs: hex uses `.mcp.json` (JSON), Codex uses `[mcp_servers]` in `config.toml` (TOML).\n- **Session resume**: supported on both; Codex uses `codex resume \u003cSESSION_ID\u003e` or `--last`.\n- **`CLAUDE.md`**: Codex reads it as a fallback when no `AGENTS.md` is present. `AGENTS.md` (included in this repo) is the preferred file for Codex.\n\n**Works without changes:**\n- `CLAUDE.md` / `AGENTS.md` operating model\n- `doctor.sh` LLM preference detection and `.codex/config.toml` creation\n- Hook event names are identical across both runtimes\n- All file-based memory and project context\n\n---\n\n## Architecture\n\n`hex` is a unified Rust binary — **core infrastructure**, not optional. As of v0.16.0, the full Python scripting layer (130 files → ~22) has been ported to native Rust subcommands. The hex-events daemon runs in Rust. One binary handles everything:\n\n- **Agent harness** (`hex agent`) — fleet management, wakes, cost tracking, gate validation, initiative execution\n- **Event engine** (`hex events`) — native Rust event daemon with hot-reload, multi-cadence scheduler, shell/emit/notify/update-file actions (replaces Python hex_eventd.py)\n- **Claude Code hooks** (`hex hook`) — session-start, post-tool-use, backup-session hook runners (replaces .sh hook scripts)\n- **HTTP/SSE server** (`hex server`) — serves all web surfaces, real-time event bus with namespaced topics\n- **Asset registry** (`hex asset`) — unified `{type}:{id}` namespace for all hex artifacts\n- **Message routing** (`hex message`) — unified messaging: comments, agent messages, notifications\n- **System health** (`hex doctor`) — 55+ checks across env, memory, structure, config, companions; `hex doctor consolidate` audits operating model for contradictions, staleness, orphaned refs (native Rust, replaces consolidate.legacy.sh)\n- **Integration lifecycle** (`hex integration`) — native Rust integration bundle management\n\n43 subcommands:\n\n```\nhex agent        — agent fleet management (wake, fleet, status, message, list, evolution, reset-periods)\nhex server       — HTTP/SSE server (port 8880)\nhex events       — event engine (start, status, emit, list, tail — native Rust daemon)\nhex hook         — Claude Code hook runners (session-start, post-tool-use, backup-session)\nhex doctor       — system health checks (55+ checks, --fix, --json)\nhex asset        — asset registry (resolve, list, search, types)\nhex message      — unified messaging (send, list, comments, notifications)\nhex sse          — SSE bus operations (publish, topics)\nhex integration  — integration bundle lifecycle (install, check-all, telemetry)\nhex memory       — behavioral and indexed memory operations\nhex health       — agent health checks (run-tier, fleet-pulse, stalled-initiative)\nhex metrics      — user-outcome metrics\nhex session      — session lifecycle (start, resume, stop)\nhex startup      — session startup checklist\nhex checkpoint   — checkpoint current session\nhex shutdown     — close current session\nhex upgrade      — upgrade hex installation (port of upgrade.sh)\nhex capture      — zero-friction context capture\nhex synthesis    — weekly and on-demand synthesis pipeline\nhex initiative   — initiative CRUD\nhex learnings    — learnings analysis and promotion\nhex route        — message routing and comment classification\nhex validate     — BOI spec, extension, and E2E guard validation\nhex telemetry    — telemetry file rotation and management\nhex picker       — interactive workspace picker\nhex fleet        — fleet manager service management\nhex boi-pm       — BOI process manager service management\nhex boi-web      — BOI live status web view\nhex pulse        — pulse server lifecycle\nhex workspace    — hex tmux workspace launcher\nhex env          — environment setup utilities\nhex alert        — iMessage alert sender\nhex path-map     — v1→v2 path translation\nhex mcp          — MCP utilities\nhex extension    — extension management\nhex router       — hex-router reverse proxy\nhex spec-tool    — spec-tool server\nhex kalshi       — Kalshi prediction market integration\nhex mirofish     — Mirofish VM health\nhex today        — print today's date\nhex version      — print version\nhex completions  — shell completions (zsh, bash, fish)\n```\n\nBackward compatibility: `hex-agent` is a symlink to `hex`. Existing scripts and policies that call `hex-agent` continue to work unchanged.\n\nRequirements: Rust toolchain (for building from source) or a supported platform for pre-built binaries (macOS arm64/x86_64, Linux x86_64).\n\nThe 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.\n\n### Version\n\n`system/harness/Cargo.toml` is the single source of truth. `env!(\"CARGO_PKG_VERSION\")` embeds the version at compile time. Git tags must match — enforced by `release.sh`. See [docs/versioning.md](./docs/versioning.md).\n\n### SSE bus\n\nThe 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.\n\n---\n\n## Quality assurance — gaming detection\n\nhex ships a Quality Antagonist: an adversarial checker that validates completed work is real, not gamed.\n\n**What it detects:**\n- Metric commands that are trivially rewritten (`echo 0` → `echo 1`) rather than measuring real behavior\n- KRs marked \"met\" where the independent measurement disagrees with the claimed value\n- Math errors (`lower_is_better` KRs where `current \u003e target` yet `status = met`)\n- Specs that complete suspiciously fast relative to their described scope\n- File-existence proxies (script exists ≠ script runs)\n\n**How it works:**\n\n```\nboi.spec.completed → quality-spec-audit policy → hex doctor quality-check --spec \u003cid\u003e\ninitiative.kr.met  → quality-kr-check policy   → hex doctor quality-check --kr \u003cinit\u003e/\u003ckr\u003e\ntimer.tick.6h      → quality-sweep policy       → hex doctor quality-check --sweep\n                                                     ↓\n                                          hex.quality.gaming.detected\n                                          hex.quality.kr.reverted\n                                          hex.quality.suspect\n```\n\nThe 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`.\n\n**CLI:**\n\n```bash\nhex doctor quality-check --spec q-123      # audit one spec\nhex doctor quality-check --kr init-foo/kr-1 # reality-check a KR\nhex doctor quality-check --sweep           # scan last 24h\n```\n\n---\n\n## Project layout (this repo)\n\n```\nhex-foundation/\n├── install.sh           Single install entrypoint\n├── VERSIONS             Pinned boi version (hex-events is now inline)\n├── system/              → becomes ~/hex/.hex/ on install\n│   ├── harness/         ← hex binary Rust source (43 subcommands — full scripting layer ported)\n│   │   ├── src/main.rs     unified CLI (all 43 subcommands)\n│   │   ├── src/events.rs   native Rust event daemon (replaces hex_eventd.py)\n│   │   ├── src/hook.rs     Claude Code hook runners (session-start, post-tool-use, backup-session)\n│   │   ├── src/server.rs   HTTP server + reverse proxy\n│   │   ├── src/sse.rs      SSE bus (topics, subscriptions, publish)\n│   │   ├── src/wake.rs     agent wake cycle\n│   │   ├── src/doctor.rs   DoctorCheck trait + 55+ checks (replaces doctor.sh)\n│   │   ├── src/upgrade.rs  upgrade pipeline (replaces upgrade.sh)\n│   │   └── build.rs        injects git SHA; Cargo.toml is version source\n│   ├── events/          ← hex-events policy definitions and default policies\n│   │   ├── policies/       built-in default policies (boi-lifecycle, capture, etc.)\n│   │   └── docs/           hex-events documentation\n│   │   (daemon, emitter, CLI now native in hex binary — `hex events start/status/emit/list/tail`)\n│   ├── sse/\n│   │   └── topics/      ← SSE topic manifests (content.comments, system.agents, etc.)\n│   ├── scripts/         startup.sh, doctor.sh, upgrade.sh, quality-check.py,\n│   │                    route-comment.py, hex-asset.py, hex-asset-discover.py, ...\n│   │   ├── health/      fleet self-driving scripts (fleet-pulse, stalled-initiative,\n│   │   │                mike-pending, budget-period-reset, backlog-promote,\n│   │   │                agent-performance-review, fleet-scorecard-aggregate)\n│   │   ├── comments-service/  comment widget (widget.js) + Python fallback server\n│   │   └── sse-bus/           hex-events → SSE bridge script\n│   ├── commands/        → copied to ~/hex/.claude/commands/ (Claude Code) and ~/hex/.hex/commands/ (doctor/tooling)\n│   ├── skills/          memory/ (index+search+save), landings, hex-reflect, hex-decide,\n│   │                    hex-debrief, hex-consolidate, hex-doctor, hex-checkpoint,\n│   │                    hex-shutdown, hex-startup, hex-triage, hex-event, hex-save,\n│   │                    hex-switch, x-twitter, imessage, mirofish, remodeling,\n│   │                    conjecture-criticism, vibe-to-prod\n│   ├── events/policies/ quality-spec-audit, quality-kr-check, quality-sweep,\n│   │                    quality-gaming-alert — event-driven quality gates\n│   └── reference/       core-agents/ — quality-antagonist and fleet agent charters\n├── adapter/\n│   └── policy-templates/  Installable hex-events policy templates for fleet health\n│                          (fleet-pulse, stalled-initiative-monitor, mike-pending-escalator,\n│                          budget-period-reset, agent-performance-review-weekly, ...)\n├── templates/           Seeds for CLAUDE.md, AGENTS.md, me.md, todo.md, decision-template.md\n├── docs/architecture.md System overview\n└── tests/\n    ├── events/          hex-events unit and integration tests\n    └── ...              E2E, layout, and memory tests\n```\n\n---\n\n## Testing\n\nThe test suite verifies installation, migration, skill discovery, and Codex parity. See [`docs/testing.md`](./docs/testing.md) for the full matrix and how to run locally.\n\nKey test files:\n\n| Test | What it verifies |\n|------|-----------------|\n| `tests/agent-harness/Dockerfile` | Agent harness E2E — charter discovery, wake, fleet, core drift, messages (43 tests) |\n| `tests/agent-harness/Dockerfile.initiative` | Initiative E2E — auto-seeding, watchdog, scheduled promotion (10 tests) |\n| `tests/agent-harness/Dockerfile.migration` | v0.8.0 migration — binary rename, symlink, backward compat, version (17 tests) |\n| `tests/contract-verification/Dockerfile` | Schema contracts across hex components (22 tests) |\n| `tests/feedback-loops/Dockerfile` | All 4 feedback loops — pivots, escalation, redesign (30 tests) |\n| `tests/codex-parity/Dockerfile` | Codex runtime parity — hooks, skills, memory, agent wake |\n| `tests/test_skill_frontmatter.sh` | Every SKILL.md has valid YAML frontmatter |\n| `tests/test_skill_refs.sh` | All paths referenced inside SKILL.md resolve |\n| `tests/test_e2e.sh` | Full install + doctor + upgrade lifecycle |\n| `tests/migrate/test-migrate.sh` | v1 → v2 migration correctness |\n| `tests/core-e2e/run-all.sh` | Hex primitives + BOI integration (containerized; CI-gated) |\n\nTo run the full suite locally:\n\n```bash\n# Static tests (no API key needed)\nbash tests/test_skill_frontmatter.sh\nbash tests/test_skill_refs.sh\n\n# Core E2E (requires Docker; ANTHROPIC_API_KEY for BOI suites)\nbash tests/core-e2e/run-all.sh                    # all suites\nbash tests/core-e2e/run-all.sh --exclude boi       # skip BOI (no Docker-in-Docker)\nbash tests/core-e2e/run-all.sh --include boi       # BOI suites only (host runner)\n\n# Live eval tests (requires ~/.hex-test.env with ANTHROPIC_API_KEY)\nbash tests/eval/run_eval_docker.sh --live    # Linux Docker\nbash tests/eval/run_eval_macos.sh            # macOS Tart\n```\n\n---\n\n## Roadmap\n\nv0.17.3: **Act evidence verification.**\n- **Mechanical act evidence gate**: harness now verifies `detail.evidence` on every `act` trail entry that claims a mechanical operation (git push, BOI dispatch, file write, etc.). Unverifiable claims are recorded as `UNVERIFIED` — they do not count as done.\n- **Agent prompt hardened**: agents are now explicitly instructed that mechanical acts without verifiable evidence are not accepted. Prevents claim-without-action loops.\n\nv0.17.2: **Doctor ports + release.rs native module.**\n- **4 doctor commands native**: `hex doctor introspect`, `goal-alignment`, `cleanup-projects`, `tech-scout` ported to Rust. 4 `.legacy.sh` stubs removed.\n- **`release.rs` native module**: deterministic LLM-free release command replaces manual `release.sh` steps. The tool that ships hex is now Rust.\n- **Quality policies migrated**: `system/policies/` → `system/events/policies/`. Commands repointed to `hex doctor quality-check`.\n\nv0.17.1: **Doctor consolidate + startup cleanup.**\n- **`hex doctor consolidate` native**: consolidation subcommand ported to Rust. `/hex-consolidate` command deleted.\n- **Startup shell-out removal**: startup sequence no longer shells out to Python scripts. Regression test added.\n\nv0.17.0: **TriggerSpec unification + truncation recovery.**\n- **Bare-string trigger syntax**: charter YAML now accepts `\"timer.tick.6h\"` directly — no struct wrapper required. Both forms valid. Same for `BlockedItem`. Every existing policy continues to work.\n- **`hex events emit --source`**: tag emitted events with a source label for traceability.\n- **Events disk-backed status**: `hex events status` survives daemon restarts; state is readable offline.\n- **Truncated response recovery**: harness salvages complete leading elements from truncated agent JSON responses. Every truncation emits a loud audit entry + `hex.agent.response.truncated` event (S6 compliance — no more silent failures).\n\nv0.16.0: **Full rustification + S1 skills sync.**\n- **43 subcommands, zero Python required**: `hex events`, `hex hook`, `hex doctor`, `hex upgrade`, `hex agent evolution`, and 20+ more ported from Python/shell. 130 Python files reduced to ~22.\n- **S1 skills sync**: 9 new skills + `bet-status` command promoted from personal instance to foundation.\n- See [CHANGELOG.md](./CHANGELOG.md) for full details.\n\nv0.15.0: **Harness messaging + binary resolution fix.**\n- **Agent messaging deadlock fixed**: `cli_send()` now writes to per-agent JSONL inbox (`.hex/messages/{agent}.jsonl`). Prior behavior wrote only to `messages.json`, which the harness wake cycle doesn't read — messages were silently dropped.\n- **Daemon binary resolution**: `claude::invoke()` resolves the binary via `$CLAUDE_BIN` env var, then `$HOME/.local/bin/claude`, then PATH. Fixes \"No such file or directory\" on LaunchAgent/daemon wakes where `~/.local/bin` is not in PATH.\n\nv0.14.0: **Slack/cc-connect deprecation + upgrade.sh cleanup.**\n- **Slack/cc-connect fully removed**: hex no longer requires or references Slack. Removed `--slack` flag from `hex-vitals.py`, Slack posting code (~155 LOC), dead `check-slack-alert-roundtrip` module from `hex-doctor`, `/api/messages` Slack-fetch endpoint from pulse dashboard, and `slack` surface from `telemetry-ratio.py`. `slack-bot.sh` and `secrets-pipeline.sh` archived.\n- **upgrade.sh simplified**: dropped legacy hex-events standalone install path. hex-events ships as `hex events` subcommand — no separate Python install or LaunchAgent needed.\n\nv0.13.3 fixes: **Health scripts + messaging.receive + wake crash-recovery.**\n- **New health scripts**: `check-hex-events-policy-load.sh` surfaces POLICY LOAD/VALIDATION ERROR entries from the hex-events daemon log (previously silent). `check-vector-search.sh` verifies sqlite-vec is loadable and memory.db has vectors.\n- **wake.rs crash recovery**: `messaging.receive()` transitions inbox messages to `in_progress` atomically — messages survive `claude::invoke` errors and are re-delivered on the next wake. Legacy JSONL inbox drained in parallel.\n\nv0.13.2 fixes: **Session-start checkpoint resume, integration-check emit fix, and memory leak fix.**\n- **Channel checkpoint resume**: `session-start.sh` now surfaces `projects/\u003ctopic\u003e/checkpoint.md` for `hex-\u003ctopic\u003e` channels. Sessions pick up where they left off automatically. Generalized blocker-flag scan (`.hex/state/blockers/*.flag`) and topic-regex sanitization included.\n- **Integration-check emit fix**: `export _error_raw` bug — 11,948+ events/day were emitted with `error: null` because the env var wasn't propagating into the command-substitution subshell. Fixed. Emit-throttle added for persistent fail streaks (heartbeat every 60 checks; no more event spam for a single dead probe).\n- **Memory vector leak fixed**: `memory_index.py` now cascade-deletes `vec_chunks` orphans on re-index. 82,377 orphan rows (58% of the vec table) had accumulated because FTS5 chunk deletion didn't cascade to the `vec0` virtual table. Fixed.\n- **Honest hybrid search**: `memory_search.py` documents `_rrf_merge` as FTS-only (KNOWN GAP) — `--hybrid` was paying embedding+vec-query cost without fusing vec results into the score.\n- **Doctor: two new health modules**: Memory Vector Search (surfaces sqlite-vec drift) and hex-events Policy Load Errors (surfaces broken policies that were previously invisible to doctor).\n\nv0.13.1 fixes: **Doctor reliability and skip_llm WakeConfig.**\n- **Doctor streaming**: Doctor command streams output live via `Stdio::inherit` (was buffered — appeared to hang on slow modules). `hex-doctor` bash script also switched to `tee | tail -n +5` streaming with full PIPESTATUS capture.\n- **Path bug fix**: 3 orchestration scripts had stale `CLAUDE_DIR=$HEX_DIR/.claude` (should be `.hex`). Caused 5 spurious doctor ERRORs on standard installs. Fixed.\n- **BOI daemon detection**: LaunchAgent-aware detection replaces `pgrep`-based check.\n- **`skip_llm` WakeConfig**: Agents that exercise wake plumbing without needing LLM reasoning (e.g. health probes) can set `wake.skip_llm: true`. Harness bypasses shift loop and self-assessment; inbox still loads and `mark_delivered` fires. `state.json` inbox drain prevents unbounded growth on high-frequency skip_llm wakes.\n\nv0.13.0 adds: **Fleet self-driving mechanisms and agent performance review.**\n- **Fleet pulse watchdog**: `check-fleet-pulse.sh` emits `hex.agent.needs-attention` events for dormant agents. Composite liveness score with WARN/ERROR escalation tiers. Suppresses during budget lockout.\n- **Stalled initiative monitor**: `check-stalled-initiatives.sh` detects initiatives with no progress signal in 48h (commit, act trail, or KR update). Sends drive-or-close directives to initiative owners. Anti-spam guard prevents re-fire within 24h.\n- **Mike-pending board monitor**: `check-mike-pending.sh` tracks Mike-blocked items with tier labels (quiet/digest/direct-ping). Coalesced per-run alerts with DM fallback.\n- **Budget period auto-reset**: `budget-period-reset.py` rolls `cost.current_period.start` forward when a period expires. 5x runaway safety gate emits ERROR alert instead of clearing an out-of-control agent.\n- **Agent performance review**: `agent-performance-review.py` produces per-agent quality/velocity/autonomy scorecards from critic reviews, BOI DB, audit trail, and Mike-pushback signals. Composite geometric mean (0.0–1.0) with cold-start handling.\n- **Fleet scorecard aggregate**: `fleet-scorecard-aggregate.py` runs per-agent reviews and produces fleet-wide top/bottom 5, biggest movers, and Mike-pushback heatmap. Outputs a single coalesced digest — no per-agent pings.\n- **Policy templates**: `adapter/policy-templates/` gains fleet-pulse, stalled-initiative-monitor, mike-pending-escalator, budget-period-reset, and agent-performance-review-weekly templates for out-of-the-box fleet health wiring.\n- **Note**: Backlog auto-promotion (`wake.rs`) was staged but reverted — supporting modules incomplete. Tracked for v0.14.0.\n\nv0.12.0 adds: **Upgrade reliability, shell completions, failure-revive protocol, and doctor improvements.**\n- **Shell completions**: `hex completions bash|zsh|fish` generates completion scripts for all subcommands. Install snippets in README.\n- **Upgrade reliability**: 5-bug patch to `/hex-upgrade` — stale-symlink cleanup, RC file detection, hex-binary version sync via Cargo.toml. Docker E2E 101/101.\n- **Doctor enhanced**: hex events daemon status absorbed into health checks; hex-binary version-sync check added (catches binary/Cargo.toml divergence).\n- **Failure-revive protocol**: three-strike detection + spec-owner-resolver + build-failure-brief for automated BOI failure analysis.\n- **Policy validator**: `dagu` added to VALID_ACTION_TYPES, fixing false-positive validation errors.\n- **AGENTS.md**: Quick Start, Gotchas, and How to Modify sections; Layer 2 Mechanisms condensed to compact table. Cross-repo navigation links added.\n- **Cleanup**: cc-connect/slack-bot scripts removed (7 files). Attack surface reduced.\n\nv0.10.0 adds: **BOI v1.1.0 integration + containerized BOI E2E.**\n- **BOI v1.1.0**: pipeline-v2 phases (clean spec-pre / task / spec-post separation), interactive `boi dashboard` TUI, spec-critique↔spec-improve quality loop, deterministic phases (commit/merge/cleanup) that skip Claude. Upgrade: run `install.sh` again.\n- **Containerized BOI E2E**: `tests/core-e2e/` suites cover fresh install, upgrade (catches stale-symlink bugs), and doctor runtime checks. CI-gated via GitHub Actions core-e2e workflow.\n- **Doctor expanded**: `check_17` now runs `boi --help`, `boi --version`, and `boi status` instead of file-existence checks. Each failure includes a repair hint.\n\nv0.11.0 adds: **Full hex sync sweep — 93 atomic units.**\n- **New subsystems**: spec-tool (spec browsing + critic-loop UI), vibe-to-prod skill, conjecture-criticism skill, hex-fleet (system health monitor + LaunchAgent), boi-pm (BOI process monitor + LaunchAgent), hex-overseer (self-tuning monitor layer), pulse dashboard with E2E test harness, comments-service, sse-bus.\n- **Improvements**: shared `hex_utils.py` library; 7 metrics scripts (continuity, done-claim, frustration, loop-waste, etc.); 6 doctor-checks; 16 health-checks (agent memory, BOI dispatch, cc-connect, MCP servers, etc.); skills: memory, hex-event, hex-save, hex-switch, x-twitter, hex-ideate, hex-triage, hex-upgrade, hex-sync-base, secret-intake, boi-delegation; 30+ MCP integration health-check wrappers.\n\nv0.10.1 fixes: **Releaser auto-unblock regression.**\n- **Harness queue.rs**: `check_unblock_condition` now handles `message_reply` blocks — previously only `telemetry` and `timer` arms existed, so releaser blocks were silently permanent.\n- **Harness wake.rs**: `blocked_since` is now stamped with the server clock on apply, preventing LLM-hallucinated future timestamps from corrupting SLA math.\n- **Tests**: 4 new tests in `tests/queue_test.rs` covering the unblock path. Build break fixes: `hex_bytes::encode` alias and `hex_agent` → `hex` rename in integration tests.\n\nv0.9.0 adds: **BOI v1.0.0 Rust binary + doctor runtime checks.**\n- **BOI rewrite**: BOI is now a compiled Rust binary at `~/.boi/bin/boi`. Install clones and builds from source; `VERSIONS` pins `BOI_VERSION`.\n- **Doctor runtime checks**: `check_17` now validates `boi --help`, `boi --version` (against `VERSIONS`), `boi status` (DB queryable), dangling-symlink detection, and the full wrapper chain (`~/.boi/boi --help`). Each failure includes a repair hint.\n- **Doctor unit tests**: `tests/test_doctor.bats` covers all new BOI checks (missing binary, dangling symlink, broken wrapper, version mismatch, status failure).\n\nv0.8.0 adds: **Unified `hex` binary + 3 new primitives + hex-events merged inline.**\n- **Unified binary**: `hex-agent` replaced by `hex` — single Rust binary with subcommands for agent fleet, HTTP/SSE server, asset registry, and comment system. `hex-agent` preserved as symlink for backward compat.\n- **Asset registry**: unified `{type}:{id}` namespace for all hex artifacts (posts, proposals, specs, decisions, projects). Auto-discovery, periodic re-scan, CLI + HTTP API.\n- **Unified comments**: single comment store, embeddable widget, LLM-classified routing to agents, action log with related assets.\n- **SSE bus**: real-time event streaming with namespaced topics (`content.*`, `system.*`), wildcard subscriptions, topic manifests as self-documenting contract. hex-events bridged to SSE.\n- **Telemetry**: append-only JSONL for all server requests and events, same pattern as agent harness.\n- **hex-events merged**: standalone [hex-events](https://github.com/mrap/hex-events) repo (v0.2.0) merged into `system/events/`. hex-events repo archived.\n- **Version system**: `Cargo.toml` is single source of truth, `env!(\"CARGO_PKG_VERSION\")` embeds version at compile time. (v0.11.3 removed the `version.txt` sidecar.)\n- **Migration**: install.sh handles upgrading from pre-0.8.0 (standalone `hex-agent` → `hex` + symlink). 122/122 E2E tests pass in Docker.\n\nv0.3.0 adds: **Modular integration bundles + `hex-integration` CLI.** Every external surface (API, MCP, system service, refresh flow) lives in one directory under `integrations/\u003cname\u003e/` — 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/\u003cname\u003e-\u003cstem\u003e.yaml` with `# generated_from:` audit headers. See `docs/integrations.md` and `templates/integrations/_template/`.\n\nv0.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.\n\nv0.2.3 adds: Codex bake in Docker image + Codex onboarding eval case.\n\nv0.2.2 adds: `bootstrap-migrate.sh` one-liner for v1 → v2 layout migration, generic migrator with rollback + idempotency, synthetic v1 fixtures + test suite.\n\nv0.2.1 fixed: Hindsight removal, install.sh doctor-clean on fresh install, hidden sync-safe markers.\n\nv0.2.0 shipped: hybrid memory search, 20-check doctor, layout-aware upgrade, decision template, 11 skills.\n\nNext up:\n\n- Hooks pack: transcript backup, reflection dispatch\n- Session lifecycle automation (warming → hot → checkpoint transitions)\n\nOpen an issue or PR — the system is meant to evolve.\n\n---\n\n## Shell completions\n\n`hex` can generate shell completions for bash, zsh, fish, elvish, and PowerShell.\n\n```bash\n# bash — add to ~/.bashrc\neval \"$(hex completions bash)\"\n\n# zsh — add to ~/.zshrc\neval \"$(hex completions zsh)\"\n\n# fish — add to ~/.config/fish/completions/hex.fish\nhex completions fish \u003e ~/.config/fish/completions/hex.fish\n```\n\nOr source on-the-fly:\n\n```bash\nsource \u003c(hex completions bash)   # bash\nsource \u003c(hex completions zsh)    # zsh\n```\n\n---\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrap%2Fhex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrap%2Fhex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrap%2Fhex/lists"}