AI coding agents are powerful but forgetful. They lose context between sessions, can't see the full codebase, don't know what other agents are doing, and have no systematic way to catch quality regressions.

HIEF is a local-first MCP server that gives any AI coding agent — Claude Code, Cursor, Copilot, Windsurf, Goose, and more — persistent, searchable codebase context, lightweight task coordination, and automated quality evaluation. All from a single Rust binary. Zero external services. Your code never leaves your machine.

HIEF is a sidecar, not an agent. It has no LLM, doesn't execute code, and doesn't make decisions. The host agent provides reasoning; HIEF provides memory.

Agent (Claude Code / Cursor / Copilot / Windsurf / Goose)
  │
  │  MCP (stdio or HTTP)
  ▼
HIEF Server
  ├── INDEX:   AST-aware search (keyword + structural + semantic)
  ├── INTENTS: Lightweight task coordination + provenance
  ├── EVAL:    Golden-set quality guardrails
  └── DOCS:    Documentation scaffolding + drift/sync workflows

• AST-aware chunking via tree-sitter (Rust, Python, TypeScript/JavaScript)
• Keyword search via FTS5 full-text search
• Structural search via ast-grep pattern matching (e.g., find every $X.unwrap())
• Semantic search via LanceDB vector embeddings (in development)
• Incremental updates via blake3 content hashing — only re-indexes what changed

• DAG-based task graph with status workflow (draft → in_progress → in_review → approved → done)
• Dependency tracking prevents conflicting concurrent work
• Provenance records which agent made each change and when
• Lightweight by design — not a project manager, just enough coordination

• Golden sets define project-specific quality criteria in TOML
• Literal checks — must_contain / must_not_contain via substring matching
• Structural checks — structural_must_not_contain via ast-grep patterns
• Differential eval — diff_only = true checks only changed files
• Score history with regression detection that can block merge

• Spec-Driven Development (SDD): Scaffold new feature specs from embedded or custom templates.
• Harness-Driven Development (HDD): Generate test harnesses and simulation playbooks.
• Auto-population: Templates can automatically inject project name, index statistics, and more.
• Template Overrides: Customize any default template by placing an override in .hief/templates/.

• Place any markdown/YAML recipe in .hief/skills/ and HIEF will expose it as a dynamic MCP tool named execute_skill_<filename> (hyphens become underscores).
• The tool returns the full file contents when invoked, allowing agents to load instructions on demand and follow project‑specific procedures.
• Skills can be listed (hief skills list) and inspected (hief skills show).

• Rust stable toolchain (MSRV 1.85+)
• Git (for blame and hooks integration)

git clone https://github.com/hiranp/hief.git
cd hief
cargo build --release

# Optional: symlink to PATH for global access
mkdir -p ~/bin
ln -sf "$(pwd)/target/release/hief" ~/bin/hief

# Initialize HIEF in your project
cd /path/to/your/project
hief init

# Build the code index
hief index build

# Start the MCP server (agents connect here)
hief serve

Configure your AI coding agent to connect to HIEF's MCP server:

Claude Code / Claude Desktop — add to your MCP settings:

{
  "mcpServers": {
    "hief": {
      "command": "hief",
      "args": ["serve"]
    }
  }
}

HTTP transport (for agents that support it):

hief serve --transport http --port 3100

HIEF exposes the following tools via the Model Context Protocol:

Dynamic skills: Any .md or .yaml file placed in .hief/skills/ is automatically advertised as a custom MCP tool named execute_skill_<filename> (hyphens converted to underscores). Calling create_intent with a skill parameter injects the recipe content directly into the response — giving the agent executable context before it starts work.

hief init                                    # Initialize HIEF in current project
hief index build                             # Build/rebuild the code index
hief index search "query"                    # Search indexed code
hief index structural '$X.unwrap()' -l rust  # AST pattern search
hief serve                                   # Start MCP server (stdio)
hief serve --transport http --port 3100      # Start MCP server (HTTP)
hief check                                   # Run drift checker suite
hief sync --backend none                     # Generate targeted sync prompt
hief sync --backend codex --apply            # Generate prompt + run fixer backend
hief watch --agent local-a                   # Watch filesystem + conflict warnings
hief patterns list                           # List project patterns
hief patterns create fix-api --title "Fix API"  # Create/update a pattern
hief eval run                                # Run golden set evaluation
hief eval report                             # Show eval score history
hief doctor --fix                            # Health check + auto-fix
hief hooks install                           # Install git hooks for auto-indexing
hief hooks watch                             # Alias for hooks install
hief docs init                               # Initialize standard docs structure
hief docs generate spec --name "feature"     # Scaffold a new feature spec
hief docs generate harness --name "feature"  # Scaffold a new test harness
hief skills init                              # Create skills directory for recipes
hief skills list                              # List available skill files
hief skills show create_database_migration    # Print a specific skill

.hief/
├── hief.db              # SQLite database (FTS5 index, intents, eval scores)
├── vectors/             # LanceDB directory (semantic embeddings)
├── conventions.toml     # Machine-readable project rules
├── context/             # Agent-maintained context docs (architecture/setup/etc.)
├── patterns/            # Project-specific task patterns + INDEX.md
└── router.toml          # Task-to-context routing table

golden/
└── *.toml               # Golden set evaluation criteria

src/
├── cli/                 # CLI commands (clap)
├── context/             # Context file read/write/list logic
├── docs/                # Doc scaffolding engine (MiniJinja templates)
├── drift/               # Drift checkers + scoring
├── eval/                # Golden set evaluation engine
├── graph/               # Intent dependency graph (DAG)
├── index/               # AST-aware code indexing + search
│   ├── chunker.rs       # tree-sitter based chunking
│   ├── search.rs        # FTS5 keyword search
│   ├── structural.rs    # ast-grep pattern matching
│   ├── vectors.rs       # LanceDB semantic search
│   └── walker.rs        # File system walker
├── mcp/                 # MCP server (rmcp)
│   ├── tools.rs         # Tool implementations
│   └── resources.rs     # Resource definitions
├── patterns/            # Pattern library and index sync
├── router/              # Session routing table loader/defaults
├── watcher/             # Filesystem watcher + conflict warnings
├── config.rs            # TOML configuration (hief.toml)
├── db.rs                # Database initialization (libsql)
├── errors.rs            # Error types (thiserror)
└── main.rs              # Entry point

hief.toml                # Project-level configuration
templates/               # Doc scaffolding templates
vscode-hief/             # VS Code extension (Kanban, search, dashboard)

HIEF's unique combination: local-first + MCP protocol + quality evaluation + open source.

A companion VS Code extension provides a Kanban board, intent list, dashboard, and code search view. See vscode-hief/ for details.

cd vscode-hief && npm install && npm run build

cargo build --release       # Compile release binary
cargo test                  # Run unit tests
cargo fmt -- --check        # Check formatting
cargo clippy --all-targets  # Run linter

Or use the Justfile:

just build                  # cargo build --release
just test                   # cargo test
just lint                   # cargo clippy
just fmt                    # cargo fmt --check
just install                # Build + symlink to ~/bin/hief

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to get started, the development workflow, and how to submit pull requests.

HIEF is built for developers who care about security and privacy.

• Local-First: All data stays on your machine. HIEF uses an embedded SQLite database (.hief/hief.db) and a local vector store.
• No Cloud Required: HIEF does not make any external network calls to process your code. Your source code never leaves your local environment.
• Sandboxed Execution: HIEF does not execute your code; it only parses it via tree-sitter or performs structural searches via ast-grep.
• Path Sanitization: All CLI and MCP tool inputs are strictly validated to prevent path traversal or flag injection attacks.

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure instructions. Do not open a public issue.

HIEF is dual-licensed under MIT or Apache-2.0 at your option.

HIEF builds on excellent open-source projects:

• tree-sitter — AST parsing
• ast-grep — Structural search
• libsql — Embedded database
• rmcp — MCP server framework
• LanceDB — Vector database