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

Features

🔍 Code Index — "What code exists?"

• 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 with TTL-bounded caching
• Incremental updates via blake3 content hashing — only re-indexes what changed
• Response Budgeting — automatically truncates oversized search responses while preserving metadata and snippets
• Query Routing — deterministic routing across lexical, semantic, and hybrid lanes
• Retrieval Weight Learning — dynamically optimizes query retrieval weights from historical groundedness feedback in shadow mode

📋 Intent Graph — "Who's doing what?"

• 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
• Multi-Tenant / Worktree Isolation — partitions session telemetry and cognitive memory dynamically by git worktree ID
• Intent Soft-Locks — lease-based soft locks preventing competing worktree ownership on concurrent transitions
• Task Tracking Web UI — HITL controls and review panels for active asynchronous worktrees
• SQL-Native Observability — built-in session telemetry and active evaluation loop
• Lightweight by design — not a project manager, just enough coordination

✅ Quality Evaluation — "Is the output good enough?"

• 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
• Fail-Closed Wave Gates — programmatically blocks intent pipeline promotion unless the latest evaluation run passes successfully

🌐 MCP Server & Protocol — "Connect to any agent"

• Adaptive Protocol Routing — dynamically routes workloads across mcp, progressive-mcp, and cli lanes based on token pressure and capabilities
• Robust Validation & Security — strict parameter validation with typed error shapes and path traversal rejection
• Dry-Run Installation — hief install scaffolds and previews agent registration payloads safely

📝 Documentation Scaffolding — "How do we start?"

• 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/.

🧠 Custom Skills & Dynamic Tools — "Teach the agent new workflows"

• 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).

Getting Started

Prerequisites

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

Install from Source

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

Quick Start

# 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

Connect Your Agent

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

MCP Tools

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.

🛠️ Scaffolding Commands

CLI Reference

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 session-cost --session-id <id>          # Print human-readable session summary and telemetry
hief doctor --fix                            # Health check + auto-fix
hief hooks install                           # Install git hooks for auto-indexing
hief hooks watch                             # Alias for hooks install
hief install                                 # Scaffolds installation with validated dry-run preview
hief ui --port 3190                          # Start the local task-tracking web UI
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

Project Structure

.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

What Makes HIEF Different

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

Documentation

Building from Source

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

Contributing

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

Security & Privacy

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.

Security

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

License

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

Acknowledgments

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