https://github.com/hendryavila/hoofy

Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.
https://github.com/hendryavila/hoofy

ai ai-assistant ai-coding ai-development ai-tools code-quality developer-tools go golang hoofy knowledge-graph mcp mcp-server model-context-protocol persistent-memory requirements-engineering spec-driven-development sqlite

Last synced: 20 days ago
JSON representation

Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.

Host: GitHub
URL: https://github.com/hendryavila/hoofy
Owner: HendryAvila
License: mit
Created: 2026-02-20T13:35:10.000Z (30 days ago)
Default Branch: main
Last Pushed: 2026-02-26T23:33:46.000Z (23 days ago)
Last Synced: 2026-02-27T03:24:31.620Z (23 days ago)
Topics: ai, ai-assistant, ai-coding, ai-development, ai-tools, code-quality, developer-tools, go, golang, hoofy, knowledge-graph, mcp, mcp-server, model-context-protocol, persistent-memory, requirements-engineering, spec-driven-development, sqlite
Language: Go
Homepage: https://hendrycode.xyz/blog/2026/2/25/hoofy-tu-companion-de-desarrollo-con-ia-que-no-te-deja-cortar-camino/
Size: 2.13 MB
Stars: 5
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

Hoofy

The AI coding assistant that remembers everything and never hallucinates specs.

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 ·

🐴 Explore the Interactive Documentation →

---

## What Is Hoofy? — AI Development Companion for MCP

Hoofy is an AI coding tool that solves the three biggest problems with AI-assisted development: **memory loss between sessions**, **hallucinated implementations**, and **unstructured AI workflows**. It's a single [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server written in Go — one binary, zero dependencies — that works with Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode, and any MCP-compatible AI tool.

Hoofy is four systems in one MCP server:

| System | What it does | Tools |
|---|---|---|
| **Memory** | Persistent context across sessions using SQLite + FTS5 full-text search. Decisions, bugs, patterns, discoveries — your AI remembers what happened yesterday. | 19 `mem_*` tools |
| **Change Pipeline** | Adaptive workflow for ongoing dev. Picks the right stages based on change type × size (12 flow variants). Includes mandatory **context-check** and **artifact guard** stages. | 5 `sdd_change*` + `sdd_adr` |
| **Project Pipeline** | Full greenfield specification — from vague idea to validated architecture with a Clarity Gate and **business rules extraction** that blocks hallucinations. | 11 `sdd_*` tools |
| **Bootstrap** | Reverse-engineer existing codebases into SDD artifacts. Scans project structure, configs, conventions, schemas, and tests — then generates requirements, business rules, and design docs. | `sdd_reverse_engineer` + `sdd_bootstrap` |

One binary. Zero external dependencies. SQLite embedded at compile time. Works with **any** MCP-compatible AI coding assistant — Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode. **38 tools + 6 on-demand prompts.**

### Why Hoofy?

AI coding assistants are powerful but forgetful and overconfident. Studies show experienced developers are [19% slower with unstructured AI](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) (METR 2025), and AI adoption without structure causes [7.2% delivery instability](https://dora.dev/research/2025/dora-report/) (DORA 2025). Hoofy fixes this by making your AI assistant remember context, follow specifications, and prove it understood before writing code.

### Key Features

**Hot/Cold Instruction Architecture** — Server instructions are kept minimal (~160 lines of "constitution") to reduce token overhead. Detailed guidance for specific workflows is loaded on-demand via 6 MCP prompts (`/sdd-start`, `/sdd-status`, `/sdd-stage-guide`, `/sdd-memory-guide`, `/sdd-change-guide`, `/sdd-bootstrap-guide`). The AI requests the right prompt when it needs it — like loading a manual chapter instead of carrying the entire book. Inspired by research showing that compact constitutions with on-demand retrieval reduce token consumption by ~17%.

**Spec-Aware Code Review** — `sdd_review` runs a code review against your project's specifications, not just generic best practices. It parses requirements (FR-XXX), business rules (BRC-XXX constraints), design decisions, and ADRs from memory to generate a review checklist. Works standalone — no active pipeline needed. Give it a task description and it tells you what to verify.

**Ad-Hoc Context Suggestion** — `sdd_suggest_context` bridges the gap for sessions that don't use a formal pipeline. Give it a task description and it scans your specs, completed changes, memory observations, and project conventions to recommend what context to read before starting. Works without `sdd.json` or an active change.

**Existing Project Bootstrap** — Got an existing codebase with no specs? `sdd_reverse_engineer` scans your project (directory structure, package manifests, configs, entry points, conventions, schemas, API definitions, ADRs, tests) and produces a structured report. Then `sdd_bootstrap` writes the missing SDD artifacts — requirements, business rules, and design docs — so the change pipeline works intelligently from day one. Medium/large changes are **blocked** without artifacts; small changes get a warning.

**Knowledge Graph** — Memory observations aren't flat notes. You can connect them with typed, directional relations (`depends_on`, `caused_by`, `implements`, `supersedes`, `relates_to`, `part_of`) to build a navigable web of project knowledge. Use `mem_build_context` to traverse the graph from any observation and pull in related decisions, bugs, and patterns automatically.

```
Decision: "Switched to JWT" →(caused_by)→ Discovery: "Session storage doesn't scale"
↑(implements) ↑(relates_to)
Bugfix: "Fixed token expiry" Pattern: "Retry with backoff"
```

**Context Check** — Every change pipeline flow now starts with a mandatory context-check stage. Before writing a single spec or line of code, Hoofy scans your existing specs, completed changes, memory observations, and convention files (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, etc.) to detect conflicts and ambiguities. Zero issues = green light. Issues found = must resolve before proceeding. Even a one-line fix can break an existing business rule.

**Business Rules** — In the greenfield project pipeline, a dedicated business-rules stage extracts declarative rules from your requirements using BRG taxonomy (Definitions, Facts, Constraints, Derivations) and DDD Ubiquitous Language — before the Clarity Gate evaluates them. Rules inform the gate, not the other way around.

**Pre-pipeline Exploration** — Before committing to a pipeline, use `sdd_explore` to capture unstructured thinking — goals, constraints, tech preferences, unknowns, decisions. It saves structured context to memory via topic key upsert (call it multiple times as your thinking evolves — it updates, never duplicates). It also suggests a change type and size based on keywords, so you start the right pipeline.

**Wave Assignments** — When creating tasks (in either pipeline), the AI can group them into parallel execution waves derived from the dependency graph. Wave 1 has no dependencies, Wave 2 depends only on Wave 1, and so on. This tells you exactly which tasks can run in parallel and which must wait — useful for team coordination or just knowing the critical path.

### How it flows

```mermaid
flowchart TB
explore["sdd_explore\n(goals, constraints, unknowns)"]

subgraph project ["New Project (greenfield)"]
direction LR
P1[Init] --> P2[Propose] --> P3[Requirements] --> P3b["Business\nRules"]
P3b --> P4{Clarity Gate}
P4 -->|Ambiguous| P3
P4 -->|Clear| P5[Design] --> P6[Tasks] --> P7[Validate]
end

subgraph bootstrap ["Existing Project (no specs)"]
direction LR
B1["sdd_reverse_engineer\n(scan codebase)"] --> B2["AI analyzes\nreport"] --> B3["sdd_bootstrap\n(write artifacts)"]
end

subgraph change ["Existing Project (changes)"]
direction LR
C1["sdd_change\n(type × size)"] --> C1b["Context\nCheck"]
C1b --> C2["Opening Stage\n(describe/propose/scope)"]
C2 --> C3["Spec + Design\n(if needed)"]
C3 --> C4[Tasks] --> C5[Verify]
end

subgraph memory ["Memory (always active)"]
direction LR
M1[Session Start] --> M2["Work + Save Discoveries"]
M2 --> M3["Connect with Relations"]
M3 --> M4[Session Summary]
end

style explore fill:#8b5cf6,stroke:#7c3aed,color:#fff
style P4 fill:#f59e0b,stroke:#d97706,color:#000
style P3b fill:#e879f9,stroke:#c026d3,color:#000
style C1b fill:#e879f9,stroke:#c026d3,color:#000
style B1 fill:#06b6d4,stroke:#0891b2,color:#fff
style B3 fill:#06b6d4,stroke:#0891b2,color:#fff
style P7 fill:#10b981,stroke:#059669,color:#fff
style C5 fill:#10b981,stroke:#059669,color:#fff
```

> **[Full workflow guide with step-by-step examples](docs/workflow-guide.md)** · **[Complete tool reference (38 tools)](docs/tool-reference.md)**

---

## Quick Start

### 1. Install the binary

macOS (Homebrew)

```bash
brew install HendryAvila/hoofy/hoofy
```

macOS / Linux (script)

```bash
curl -sSL https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.sh | bash
```

Windows (PowerShell)

```powershell
irm https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.ps1 | iex
```

Go / Source

```bash
# Go install (requires Go 1.25+)
go install github.com/HendryAvila/Hoofy/cmd/hoofy@latest

# Or build from source
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build
```

### 2. Connect to your AI tool

> **MCP Server vs Plugin — what's the difference?**
>
> The **MCP server** is Hoofy itself — the binary you just installed. It provides 38 tools and 6 on-demand prompts (memory, change pipeline, project pipeline, bootstrap, standalone) and works with **any** MCP-compatible AI tool.
>
> The **Plugin** is a Claude Code-only enhancement that layers additional capabilities on top of the MCP server:
>
> | Component | What it does |
> |---|---|
> | **Agent** | A custom personality (Hoofy the horse-architect) that teaches through concepts, not code dumps. Enforces SDD discipline — the AI won't skip specs. |
> | **Skills** | Loadable instruction sets for specific domains (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). The agent auto-detects context and loads the right skill before writing code. |
> | **Hooks** | Lifecycle automation — `PreToolCall` and `PostToolCall` hooks that trigger memory operations automatically (e.g., saving session context, capturing discoveries after tool use). |
>
> The plugin is optional — you get full Hoofy functionality with just the MCP server. The plugin just makes the experience smoother in Claude Code.

Claude Code

**MCP Server** — one command, done:

```bash
claude mcp add --scope user hoofy hoofy serve
```

**Plugin** (optional, Claude Code only) — adds agent + skills + hooks on top of the MCP server:

```
/plugin marketplace add HendryAvila/hoofy-plugins
/plugin install hoofy@hoofy-plugins
```

Cursor

Add to your MCP config:

```json
{
"mcpServers": {
"hoofy": {
"command": "hoofy",
"args": ["serve"]
}
}
}
```

VS Code Copilot

Add to `.vscode/mcp.json`:

```json
{
"servers": {
"hoofy": {
"type": "stdio",
"command": "hoofy",
"args": ["serve"]
}
}
}
```

OpenCode

Add to `~/.config/opencode/opencode.json` inside the `"mcp"` key:

```json
{
"mcp": {
"hoofy": {
"type": "local",
"command": ["hoofy", "serve"],
"enabled": true
}
}
}
```

Gemini CLI

Add to your MCP config:

```json
{
"mcpServers": {
"hoofy": {
"command": "hoofy",
"args": ["serve"]
}
}
}
```

### 3. Use it

Just talk to your AI. Hoofy's built-in instructions tell the AI when and how to use each system.

### 4. Update

```bash
hoofy update
```

Auto-checks on startup, updates when you say so.

### 5. Reinforce the behavior (recommended)

Hoofy already includes built-in server instructions, but adding a short block to your agent's instructions file reinforces the habit — the AI will think about specs *before* it even sees the tools.

Claude Code — CLAUDE.md (only needed for MCP-only setup)

> **Using the plugin?** Skip this — the plugin's hooks and agent already enforce SDD behavior automatically.