Context Files

Context Files

contextd stores all project context in a .context/ directory at your project root.

Directory structure

.context/
├── project.md          # Required: project overview
├── architecture.md     # Recommended: system design
├── conventions.md      # Recommended: coding standards
├── decisions/          # Architecture Decision Records (ADRs)
│   ├── 001-why-typescript.md
│   └── 002-api-design.md
├── modules/            # Per-directory/module context
│   ├── api.md          # scope: src/api
│   └── ui.md           # scope: src/components
├── remote/             # Cached remote contexts (gitignored)
│   └── org/
│       └── collection/
│           └── *.md
└── sources.json        # Remote source configuration

Root-level files

project.md

A high-level overview of your project. Should cover:

  • What the project does
  • Tech stack (language, framework, database)
  • Key goals and non-goals
  • Things to avoid

architecture.md

Documents the system architecture:

  • System overview and component diagram description
  • Directory structure explanation
  • Data flow patterns
  • External services and integrations

conventions.md

Coding standards and patterns the team follows:

  • Naming conventions
  • File organization
  • Design patterns used or avoided
  • Error handling approach
  • Testing strategy

Decisions

The decisions/ directory contains Architecture Decision Records (ADRs). Each file follows the naming pattern NNN-slug.md and contains:

  • Title and date
  • Status (proposed, accepted, deprecated)
  • Context describing the issue
  • The decision made
  • Consequences
  • Alternatives considered

Create new ADRs with:

contextd decision add "Why we use tRPC"

List all decisions with:

contextd decision list

Modules

The modules/ directory contains context for specific directories or areas of your codebase. Each file describes:

  • The purpose of the module
  • Key patterns used
  • Gotchas, rules, or conventions specific to that area

Module files should be named after the directory they cover (e.g., api.md for the src/api/ directory) and include a scope field in the frontmatter.

Remote contexts

The remote/ directory caches contexts synced from remote collections. These files are merged into exports and MCP responses alongside local contexts, with local files taking precedence on conflicts. The directory is gitignored — it’s populated by contextd sync now.

Sources configuration

.context/sources.json tracks which remote collections you subscribe to:

{
  "sources": [
    {
      "name": "my-org/shared",
      "url": "contextd://my-org/shared",
      "filters": { "type": "conventions", "tags": ["backend"] },
      "last_synced": "2026-05-03T12:00:00.000Z"
    }
  ]
}

Manage sources with the sync command.

File format

All context files use Markdown with YAML frontmatter.

Core fields

FieldTypeRequiredDescription
titlestringYesDisplay title
updatedstringYesISO date (YYYY-MM-DD)

Optional fields

FieldTypeDescription
tagsstring[]Tags for filtering (used by decisions and sync filters)
prioritystringPriority level: high, medium, low, normal
scopestringDirectory scope for module contexts (e.g., src/api)

Decision-specific fields

FieldTypeDescription
statusstringaccepted, deprecated, or proposed
datestringCreation date (YYYY-MM-DD)

Example: core context file

---
title: Project Overview
updated: 2026-05-03
tags: [backend, api]
priority: high
---
 
# Project Overview
 
## What is this?
...

Example: decision file

---
title: "Why we use tRPC instead of REST"
date: 2026-05-03
status: accepted
tags: ["api", "architecture"]
---
 
# ADR-001: Why we use tRPC instead of REST
 
## Context
...

Example: module context file

---
title: API Module
scope: src/api
updated: 2026-05-03
---
 
# API Module
 
...
VS Code ExtensionExport Formats