Claude Habitat

Claude Habitat is an MCP server that provides persistent project context, workflow management, and knowledge capture to AI coding agents, enabling memory across sessions and structured collaboration on software projects.

How to use

You connect an MCP client to Claude Habitat to access per-project context, define workflows, manage knowledge, and resolve skills. Start by initializing a project, then create and track workflows, store patterns and lessons, and leverage shared skill protocols to automate common tasks. All data persists locally under a dedicated data directory and is accessed through a standard set of MCP tools across namespaces.

Key patterns you’ll use often include: creating a project profile from your directory, outlining conventions, detecting the project’s tech stack and languages, starting and progressing through 8-phase workflows with gate checks, saving reusable patterns and preferences, and resolving skills that automate tasks end to end. You can also scan for technical debt, generate reports, and compare debt trends over time. All actions are exposed through well-defined MCP tools within their respective namespaces.

How to install

Prerequisites you need before installing Claude Habitat are Node.js 18 or newer, a package manager (npm or pnpm), and the Claude Code CLI for MCP integration.

# 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

Additional setup and starting the server

If you prefer manual setup, you can install dependencies, build the project, and run the MCP server directly.

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

Configuring the MCP server in your environment

The MCP server can register automatically, or you can add a manual entry for the server in your Claude config. The following example demonstrates how to register the habitat MCP server in your local Claude JSON configuration.

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

Initialize a project and marker file

Once the MCP server is running, initialize your project. Claude Habitat will scan the current directory, detect the tech stack, and create a project profile with a marker file placed at .claude-habitat/marker.json in the project directory.

/habitat-init

Security and data location notes

All persistent data is stored by default in a dedicated data directory under your home folder, unless you override it with the HABITAT_DATA_DIR environment variable. This ensures a clear separation between project data and local environment.

Available tools

project_init

Initialize a project by scanning its directory to generate a project profile with detected tech stack.

project_get_context

Retrieve the full project context including profile and conventions.

project_set_convention

Define a convention for a project, such as naming or testing rules.

project_get_conventions

List all conventions defined for a project.

project_update_profile

Update fields in a project profile such as name, description, or tech stack.

workflow_start

Start a new workflow for a project with type, title, and optional description.

workflow_get_status

Query the current status of a workflow.

workflow_transition

Move a workflow to a new phase with a gate checklist and evidence.

workflow_record

Add a record to a workflow documenting decisions, findings, or progress.

workflow_list

List workflows for a project with optional status filtering.

workflow_complete

Mark a workflow as completed or abandoned with a summary.

knowledge_save

Save a knowledge entry including content and tags for later retrieval.

knowledge_recall

Recall knowledge entries by ID, category, or tags.

knowledge_search

Search knowledge entries by text query.

knowledge_list

List knowledge entries with optional category and limit.

knowledge_forget

Delete a knowledge entry by its ID.

lang_detect

Detect programming languages in a project to tailor communication.

lang_translate

Translate text between languages using the server's translation capabilities.

lang_set_preference

Set a language preference for a project.

lang_get_preference

Get the current language preference for a project.

skill_resolve

Resolve a skill by name to its fully inlined protocol with all imports.

context_bundle

Concatenate multiple files into a single response with separators.

convention_check

Check if a file follows project conventions.

doc_link

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

doc_unlink

Remove a link between two documents in the document chain.

doc_read

Read a document and its metadata from the document chain.

doc_write

Write or update a document in the document chain.

doc_traverse

Traverse the document chain from a starting document.

doc_init_dimension

Initialize a dimension in the document chain with a root document.

doc_sync

Scan project facts and synchronize auto-generated docs.

prompt_assemble

Assemble a prompt from document chains with intelligent ordering.

debt_scan

Scan project for technical debt and generate a quantified report.

debt_report

Query historical debt scan reports with comparison.

debt_trend

Analyze debt score trends and identify persistent items.