Claude Habitat

An MCP (Model Context Protocol) server that provides persistent project context, workflow management, and knowledge capture for AI coding agents.

What It Does

Claude Habitat gives AI agents structured memory across sessions:

• Project Context — track project profile, conventions, tech stack, and document chain architecture for flexible context management
• Workflow Management — 8-phase workflows with gate checks, records, and phase transitions
• Knowledge Base — persistent patterns, lessons, insights, and preferences across projects
• Skill System — 23 executable skill protocols with shared knowledge modules and @import resolution
• Technical Debt — automated scanning, scoring, trend analysis, and remediation tracking
• Language Support — detect project languages and set communication preferences

Key Numbers

• 34 MCP tools across 9 namespaces
• 23 skills with 111 shared knowledge modules
• 6 behavior rules (auto-injected)
• 6 custom slash commands
• 6 debt detectors with weighted scoring

Installation

Prerequisites

• Node.js 18+
• npm or pnpm
• Claude Code CLI (for MCP integration)

Setup

# Clone the repository
git clone <repo-url> claude-habitat
cd claude-habitat

# Install and register (builds, installs assets, registers MCP server, installs hooks)
node scripts/install.mjs

Manual Setup

If you prefer manual setup:

npm install
npm run build
npx tsx packages/mcp/src/index.ts

Register as MCP Server

The installer registers automatically. For manual registration, add to ~/.claude.json:

{
  "mcpServers": {
    "habitat-mcp": {
      "command": "node",
      "args": ["/path/to/claude-habitat/packages/mcp/dist/index.js"]
    }
  }
}

Initialize a Project

Once the MCP server is running, initialize your project:

/habitat-init

This scans the current directory, detects the tech stack, and creates a project profile with a .claude-habitat/marker.json marker file.

Configuration

Data Directory

All persistent data is stored in ~/.claude-habitat/ by default. Override with the HABITAT_DATA_DIR environment variable:

export HABITAT_DATA_DIR=/path/to/custom/data

Directory Structure

~/.claude-habitat/
├── projects/{project_id}/
│   ├── profile.json          # Project profile (name, path, tech stack)
│   └── conventions.json      # Project conventions
├── workflows/{workflow_id}.json  # Workflow state and records
├── knowledge/{category}/{id}.json  # Knowledge entries
├── lang/{project_id}.json    # Language preferences
└── debt/{project_id}/reports/    # Debt scan reports

{project_dir}/docs/context/   # Document chain (project-local)
├── .chain-index.json         # Link metadata
└── {dimension}/{doc}.md      # Document nodes

Project Marker File

Each initialized project has a .claude-habitat/marker.json marker file in its project directory:

{
  "project_id": "e9939649-364b-464c-b1d9-0253fd8cc748",
  "created_at": "2026-02-07T..."
}

This file is the single source of truth for project identity. Never hardcode or cache project_id across sessions.

MCP Tools Reference

Claude Habitat exposes 34 tools across 9 namespaces via the Model Context Protocol.

Project Namespace (5 tools)

project_init

Initialize a project by scanning its directory.

Returns: Project profile with detected tech stack, directory structure, and generated project_id.

project_get_context

Get full project context including profile and conventions.

project_set_convention

Set a convention for a project.

project_get_conventions

Get all conventions for a project.

project_update_profile

Update a project profile.

updates object fields (at least one required):

• name (string) — project name
• description (string) — project description
• tech_stack (string[]) — technology stack entries

Workflow Namespace (6 tools)

workflow_start

Start a new workflow for a project.

Returns: New workflow with generated workflow_id, initial phase set by type.

workflow_get_status

Get the current status of a workflow.

workflow_transition

Transition a workflow to a new phase.

Each gate checklist item: { item: string, passed: boolean, evidence?: string }

workflow_record

Add a record to a workflow.

workflow_list

List workflows for a project.

workflow_complete

Complete a workflow.

Knowledge Namespace (5 tools)

knowledge_save

Save a knowledge entry.

knowledge_recall

Recall knowledge entries by ID or filter. At least one of knowledge_id, category, or tags is required.

knowledge_search

Search knowledge entries by text query.

knowledge_list

List knowledge entries.

knowledge_forget

Delete a knowledge entry.

Lang Namespace (4 tools)

lang_detect

Detect programming languages in a project directory.

lang_translate

Translate text to a target language.

lang_set_preference

Set language preference for a project.

lang_get_preference

Get language preference for a project.

Skill Namespace (1 tool)

skill_resolve

Resolve a skill file with all @import directives linked into a single document.

Returns: Fully resolved skill protocol with all imported shared modules inlined.

Context Namespace (2 tools)

context_bundle

Concatenate multiple files into a single response with separators.

convention_check

Check if a file follows project conventions.

Doc Namespace (7 tools)

doc_link

Create a bidirectional link between two documents in the document chain.

doc_unlink

Remove a link between two documents.

doc_read

Read a document and its metadata from the document chain.

Returns: Document content, metadata, and outbound links.

doc_write

Write or update a document in the document chain.

doc_traverse

Traverse the document chain from a starting document.

Returns: Graph of connected documents with their links and metadata.

doc_init_dimension

Initialize a dimension in the document chain with root doc and scaffold.

doc_sync

Scan project facts and sync auto-generated docs (README sections, CLAUDE.md counts).

Returns: Facts summary, list of updated/stale files, and update counts.

Prompt Namespace (1 tool)

prompt_assemble

Assemble a prompt from document chains with intelligent ordering and deduplication.

Returns: Assembled prompt text with documents ordered by dependency and relevance.

Debt Namespace (3 tools)

debt_scan

Scan project for technical debt and produce a quantified report.

Returns: Quantified report with score (0-100), item counts by severity, and individual debt items.

debt_report

Query historical debt scan reports with comparison.

debt_trend

Analyze debt score trends, detect convergence/divergence, identify stubborn items.

Returns: Trend direction (converging/stable/diverging), score trajectory, and stubborn items that persist across scans.

Skill System

Claude Habitat includes 23 executable skill protocols and 111 shared knowledge modules. Skills define structured execution steps for specific task types.

How Skills Work

1. Agent identifies the matching skill based on task type
2. Calls skill_resolve(skill_name) to load the full protocol
3. The resolver recursively inlines all @import directives (max depth 5)
4. Agent follows the loaded protocol step by step

Each skill has a modular structure: SKILL.md (entry, <30 lines) + protocol.md + context.md + gates.md, linked via @import.

Skill Categories

Workflow Skills (7)

Operational Skills (5)

Debt Management Skills (3)

Infrastructure Skills (5)

Knowledge & Docs Skills (2)

Hook-Driven Skills (1)

Shared Knowledge Modules (111)

Skills reference shared modules via @import shared/path/to/module. The skill_resolve tool recursively inlines all imports.

• 28 core modules (coding principles, patterns, delegation, design)
• 83 language-specific modules across 14 languages
• Languages: cpp, csharp, dart, go, java, kotlin, php, python, ruby, rust, scala, shell, swift, typescript

Architecture

Overview

Claude Habitat is an MCP (Model Context Protocol) server built with TypeScript. It runs as a stdio-based server process that AI coding agents connect to for persistent project context.

Entry Point

packages/mcp/src/index.ts — Registers all tools with the MCP server, wraps each handler with wrapHandler() for consistent error boundaries, and starts the stdio transport.

Source Layout

packages/
├── mcp/                    # MCP server (core)
│   ├── src/
│   │   ├── index.ts              # MCP server entry point
│   │   ├── constants.ts          # Shared constants (phases, categories, patterns)
│   │   ├── types/index.ts        # Core TypeScript interfaces
│   │   ├── storage/
│   │   │   ├── file-store.ts     # readJSON, writeJSON, exists, listFiles, removeFile
│   │   │   └── paths.ts          # Data directory path resolution
│   │   ├── validation/
│   │   │   └── schemas.ts        # Zod schemas for all tools
│   │   └── tools/
│   │       ├── project/          # init, get-context, set-convention, get-conventions, update-profile
│   │       ├── workflow/         # start, get-status, transition, record, list, complete
│   │       ├── knowledge/        # save, recall, search, list, forget
│   │       ├── lang/             # detect, translate, set-preference, get-preference
│   │       ├── skill/            # resolve
│   │       ├── context/          # bundle, convention-check
│   │       ├── doc/              # link, unlink, read, write, traverse, init-dimension, sync
│   │       ├── prompt/           # assemble
│   │       └── debt/             # scan, report, trend + scoring + detectors/
│   └── tests/
│       ├── unit/{namespace}/     # Unit tests per handler
│       └── integration/          # Cross-namespace integration tests
├── prompt-restructure/     # CLI tool for hook-driven prompt optimization
│   └── index.mjs
scripts/                    # install.mjs, uninstall.mjs
assets/.claude/             # skills/, commands/, rules/, hooks.json

Request Flow

1. MCP client sends a tool call via stdio
2. McpServer routes to the registered handler
3. wrapHandler() catches errors and normalizes responses
4. Handler validates input with Zod schema
5. Handler reads/writes JSON files via file-store.ts
6. Response returned as { content: [{ type: 'text', text }], isError? }

Storage Layer

All data persists as JSON files under ~/.claude-habitat/ (configurable via HABITAT_DATA_DIR).

• Atomic writes: writeJSON writes to a .tmp file then renames for crash safety
• Path safety: All project paths validated to be under $HOME or /tmp
• No database: Pure filesystem storage, no external dependencies

Workflow Engine

8-phase lifecycle with gate checks between transitions:

Requirements → Design → Prototype → Test Construction → Production Implementation → Full Test Suite → Audit → Release

• Workflows are typed: feature, bugfix, refactor, chore
• Each type has a shortcut starting phase (e.g. chore starts at Production Implementation)
• Phase transitions require a gate checklist with evidence
• All decisions, findings, and blockers are recorded as workflow records

Document Chain Architecture

Flexible graph-based context management:

• Documents are nodes in a directed graph with bidirectional links
• @import (downward) and @referenced-by (upward) — both updated atomically
• Any document is an entry point — traverse up or down from anywhere
• Dynamic dimensions configured via doc_init_dimension
• 8 MCP tools: doc_link, doc_unlink, doc_read, doc_write, doc_traverse, doc_init_dimension, doc_sync, prompt_assemble