Getting Started

Installation

Install contextd globally via npm:

npm install -g contextd

Or run it directly with npx:

npx contextd init

Initialize a project

Navigate to your project root and run:

contextd init

This creates a .context/ directory with starter templates:

.context/
  project.md       ← Project overview, goals, and tech stack
  architecture.md  ← System architecture and data flow
  conventions.md   ← Coding standards and patterns
  decisions/       ← Architecture decision records (ADRs)
  modules/         ← Module-specific context files

For a minimal setup with only project.md:

contextd init --minimal

Edit your context files

Open each .md file and fill in the details about your project. The frontmatter at the top of each file provides metadata:

---
title: Project Overview
updated: 2026-05-03
---
 
# Project Overview
 
## What is this?
A web application for managing...
 
## Tech Stack
- **Language**: TypeScript
- **Framework**: Next.js
- **Database**: PostgreSQL

Export to AI tools

Once your context files are populated, export them for your AI tool of choice:

# Export to CLAUDE.md (default)
contextd export
 
# Export to .cursorrules
contextd export --format cursorrules
 
# Export raw text to stdout
contextd export --format raw

The exported file is placed at your project root and will be automatically picked up by Claude Code, Cursor, or any other AI assistant that reads these files.

Check context health

Validate that your context files are complete and well-formed:

contextd check

This checks for missing core files, empty templates, stale content, and module coverage gaps.

Set up remote sync (optional)

For team context sharing, authenticate and subscribe to shared collections:

# Authenticate with the remote service
contextd auth login
 
# Subscribe to a shared context collection
contextd sync add contextd://my-org/shared
 
# Fetch remote contexts
contextd sync now
 
# Publish your local contexts to the remote
contextd sync publish

Remote contexts are automatically merged into exports, with local files taking precedence. See Remote Sync for details.

Set up the MCP server (optional)

Run contextd as an MCP server so AI agents can query context programmatically:

contextd serve

This prints an .mcp.json configuration to add to your project. See the MCP Server guide for details.

Install the VS Code extension (optional)

Install the contextd extension from the VS Code Marketplace for a visual interface to manage context, view health scores, and export with one click.

See the VS Code Extension guide for details.

What’s next

Learn about each CLI command
Set up the MCP server for real-time context
Install the VS Code extension
Understand the context file format
Set up remote sync for team sharing

Introduction Init