AI coding has evolved from simple file-level completions to sophisticated project-wide assistance. As these tools become more capable, they need more context - not just about individual files, but about your project's architecture, history, and design decisions.
dotcontext emerged from a common pattern: developers repeatedly sharing README files with AI assistants to help them understand projects before starting tasks. We've standardized this approach into a structured system that helps AI coding agents grasp your codebase's full context from the start.
%%{init: { 'theme': 'dark' } }%%
sequenceDiagram
participant Dev as Developer
participant DC as .context/
participant MCP as MCP Server
participant AI as AI Assistant
rect rgba(50, 50, 50, 0.5)
Note over Dev,AI: Initial Setup
Dev->>DC: Create context structure
Dev->>DC: Add documentation
Dev->>DC: Create diagrams
end
rect rgba(50, 50, 50, 0.5)
Note over Dev,AI: Development Flow
Dev->>AI: Start new task
AI->>MCP: Request context
MCP->>DC: Read context
DC-->>MCP: Project context
MCP-->>AI: Structured information
Note over AI: AI processes<br/>complete context
AI-->>Dev: Informed assistance
Dev->>DC: Update context
end
rect rgba(50, 50, 50, 0.5)
Note over Dev,AI: Continuous Learning
loop Project Evolution
Dev->>DC: Update documentation
AI->>MCP: Get fresh context
MCP->>DC: Read updates
DC-->>AI: Latest context
end
end
Note over Dev,AI: Project Evolution
MCP is a communication standard that lets AI Coding Agents understand your codebase better. Think of it like a translator between your documentation and AI assistants. When an AI tool supports MCP, it can:
- Read and understand your project's documentation
- Parse architectural diagrams
- Make informed suggestions about your code
- Validate documentation structure
# Navigate to your project root
cd your-project
# Create your first context directory
npx dotcontext init
# Validate your context structure
npx dotcontext validate{
"mcpServers": {
"dotcontext": {
"command": "npx",
"args": ["-y", "-p", "dotcontext", "dotcontext-mcp"],
"disabled": false,
"alwaysAllow": []
}
}
}{
"mcpServers": {
"dotcontext": {
"command": "node",
"args": ["C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js", "-y", "-p", "dotcontext", "dotcontext-mcp"],
"disabled": false,
"alwaysAllow": []
}
}
}init: Create new context directoriesvalidate: Check documentation structure- 💡
context: Get project documentation and insightsAI Assistant Tip: Use this command to understand a project before starting tasks!
Custom Instruction: "use dotcontext's context to understand this project before starting on your task" diagrams: View architectural diagrams
All tools automatically work from your project root, looking for a .context directory.
Your .context directory organizes project knowledge:
index.md: Main entry point for AI toolsdocs/: Documentation and referencesdiagrams/: Architectural and flow diagrams.contextignore: Excludes irrelevant information
- Initialize context directories (
dotcontext init) - Validate documentation structure (
dotcontext validate) - List architectural diagrams (
dotcontext diagrams) - Lint context files for consistency
- Legacy Projects: Document historical context and system changes
- Architecture Decisions: Explain design patterns and trade-offs
- Tribal Knowledge: Capture team conventions and practices
- Migration Notes: Track system transitions (e.g., queue system → topic system)
- Built with TypeScript for type safety
- Automated versioning via Semantic Release
- Modular architecture for extensibility
- Comprehensive test coverage
# Install dependencies
npm install
# Build project
npm run build
# Link for local development
npm link# Run tests
npm test
# Run with coverage
npm run test:coverageWe welcome contributions! Please check our contribution guidelines and maintain test coverage for new features.
MIT