HendryAvila/Hoofy

The AI coding assistant that remembers context and reduces spec hallucinations.
An MCP server that gives your AI persistent memory, structured specifications,
and adaptive change management — so it builds what you actually want.
Blog Post ·
Workflow Guide ·
Tool Reference ·
Research Foundations ·
---
Start Here (TL;DR)
If the README felt overwhelming, use this section first.
- **Hoofy is an MCP server** that gives your AI persistent memory + spec-driven workflow.
- It prevents the classic AI failure modes: forgetting context, hallucinating requirements, and skipping planning.
- It works with Claude Code, Cursor, VS Code Copilot, OpenCode, Gemini CLI (and any MCP-compatible tool).
- You can use it for **new projects**, **ongoing changes**, or **existing projects without specs**.
- Install, connect MCP, and start with a small change.
60-Second Quick Start
1. Install Hoofy: brew install HendryAvila/hoofy/hoofy (or use the install script below).
2. Connect MCP: claude mcp add --scope user hoofy hoofy serve (or use your editor's MCP config).
3. Ask your AI to implement a change — Hoofy guides planning + memory automatically.
What Is Hoofy? — AI Development Companion for MCP
Hoofy solves three recurring AI-dev problems: **memory loss between sessions**, **hallucinated implementations**, and **unstructured workflows**. It's a single MCP (Model Context Protocol) server written in Go — one binary, zero external runtime dependencies.
Choose your path
- **New project** → run the full project pipeline (sdd_init_project → ... → sdd_validate)
- **Existing project, adding/fixing something** → start with sdd_change
- **Existing project with no specs yet** → sdd_reverse_engineer + sdd_bootstrap
- **Just need context/review quickly** → sdd_suggest_context, sdd_review, sdd_audit
Core systems (at a glance)
| System | What it does | Tools |
|---|---|---|
| **Memory** | Persistent context across sessions using SQLite + FTS5 full-text search. | mem_* tools |
| **Change Pipeline** | Adaptive flow for ongoing work based on change type × size (12 variants). | sdd_change*, sdd_adr |
| **Project Pipeline** | Full greenfield specification flow with Clarity Gate (9 stages). | sdd_* project tools |
| **Bootstrap** | Reverse-engineer existing codebases into requirements, rules, and design artifacts. | sdd_reverse_engineer, sdd_bootstrap |
Key features (most important)
- **Principles-first pipeline** — define non-negotiables before requirements.
- **Clarity Gate** — blocks vague specs before implementation starts.
- **Context-check on every change** — catches conflicts early.
- **Spec-aware review/audit** — compare code against requirements and rules.
- **Persistent memory + knowledge graph** — decisions and fixes remain searchable.
- **Hot/cold instructions** — lightweight core instructions + on-demand guides.
See full feature details
- **Project Charter** — The old "proposal" stage is now a **charter** with domain context, stakeholders, vision, boundaries, success criteria, existing systems, and constraints.
- **Spec-vs-Code Audit** — sdd_audit compares specifications against source code to detect missing implementations and drift.
- **Auto-Generated Agent Instructions** — sdd_init_project injects SDD instructions into CLAUDE.md/AGENTS.md (idempotent).
- **Unified ADR Storage** — ADRs are always written to docs/adrs/NNN-slug.md.
- **Spec-Aware Code Review** — sdd_review generates a checklist tied to FR/NFR/business rules/ADRs.
- **Ad-Hoc Context Suggestion** — sdd_suggest_context recommends what to read before implementation.
- **Existing Project Bootstrap** — sdd_reverse_engineer + sdd_bootstrap create missing artifacts for legacy codebases.
- **Knowledge Graph** — relate observations with typed edges (depends_on, caused_by, implements, etc.).
- **Facade-First Tooling** — unified memory entry points: mem_save and mem_session.
- **Business Rules Stage** — BRG + DDD extraction before Clarity Gate.
- **Pre-pipeline Exploration** — sdd_explore captures goals/constraints/unknowns before formal pipeline work.