# Tenets - Complete Documentation for AI Assistants
> MCP server for context that feeds your prompts
## Overview
Tenets is a free, open-source tool that helps AI coding assistants understand codebases better. It runs 100% locally - your code never leaves your machine.
## Installation Options
```bash
# MCP server (recommended)
pip install tenets[mcp]
# Core only (CLI + Python library)
pip install tenets
# Everything (MCP + ML + visualization)
pip install tenets[all]
```
Python 3.9-3.13 supported. Python 3.11+ recommended.
---
## The Two Core Features
### 1. Intelligent Code Context Aggregation
Tenets uses multi-factor NLP ranking to find the most relevant files for any task:
**Ranking Factors:**
- BM25/TF-IDF text similarity
- Keyword extraction and matching
- Import centrality (PageRank on dependency graph)
- Git signals (recency, frequency, authorship)
- Path relevance (filename matches query)
- Complexity metrics
**Modes:**
- `fast`: ~1s, keyword matching
- `balanced`: ~3s, BM25 + structure analysis (default)
- `thorough`: ~10s, ML embeddings when enabled
### 2. Automatic Tenets Injection
Define guiding principles that are automatically injected into every context:
```bash
# Add tenets
tenets tenet add "Always validate user input" --priority critical --category security
tenets tenet add "Use type hints in Python" --priority high --category style
tenets tenet add "Prefer small, safe diffs" --priority medium --category workflow
# Activate tenets
tenets instill
```
This prevents "context drift" in long AI conversations where the model forgets project conventions.
---
## MCP Server Usage
### Starting the Server
```bash
tenets-mcp # stdio transport (default)
tenets-mcp --sse # SSE transport
tenets-mcp --http # HTTP transport
```
### IDE Configuration
**Cursor** (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"tenets": {
"command": "tenets-mcp"
}
}
}
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"tenets": {
"command": "tenets-mcp"
}
}
}
```
**Windsurf**: Settings → Extensions → MCP, add the same config.
### MCP Tools Reference
| Tool | Purpose | Example |
|------|---------|---------|
| `distill` | Build optimized code context | "Find auth implementation" |
| `rank_files` | Preview relevance without content | "Which files handle payments?" |
| `examine` | Analyze structure and complexity | Identify hotspots, tech debt |
| `chronicle` | Git history analysis | Recent changes, contributors |
| `momentum` | Development velocity metrics | Team productivity trends |
| `session_create` | Create named session | Persistent context across prompts |
| `session_pin_file` | Pin file to session | Guarantee inclusion in context |
| `tenet_add` | Add guiding principle | Coding standards, security rules |
| `tenet_instill` | Activate pending tenets | Enable injection |
| `set_system_instruction` | Set system prompt | AI persona, output format |
---
## CLI Reference
### Context Building
```bash
# Basic distill
tenets distill "implement OAuth2 login"
# With options
tenets distill "fix payment bug" \
--mode thorough \
--max-tokens 80000 \
--format markdown \
--include "*.py" \
--exclude "**/tests/**"
# Copy to clipboard
tenets distill "add caching" --copy
```
### File Ranking
```bash
# Preview relevant files
tenets rank "authentication" --top 20
# With explanations
tenets rank "database queries" --explain
```
### Code Analysis
```bash
# Examine codebase
tenets examine . --complexity --hotspots
# Git analysis
tenets chronicle --since "1 week"
# Team velocity
tenets momentum --team --since "last month"
```
### Sessions
```bash
# Create session
tenets session create auth-refactor
# Pin files
tenets session pin src/auth/ --session auth-refactor
# Use session
tenets distill "add MFA support" --session auth-refactor
```
### Tenets (Guiding Principles)
```bash
# Add tenet
tenets tenet add "Never log sensitive data" --priority critical --category security
# List tenets
tenets tenet list
# Instill (activate)
tenets instill
# System instruction
tenets system-instruction set "You are a senior engineer. Be concise." --enable
```
---
## Python API
```python
from tenets import Tenets
# Initialize
t = Tenets()
# Build context
result = t.distill(
prompt="implement user registration",
max_tokens=100000,
mode="balanced",
format="markdown"
)
print(f"Found {len(result.files)} files")
print(f"Token count: {result.token_count}")
print(result.context)
# Rank files
ranking = t.rank_files("payment processing", top_n=10)
for file in ranking.files:
print(f"{file.path}: {file.score:.2f}")
# Sessions
t.session_create("feature-x")
t.session_pin_file("feature-x", "src/core/handler.py")
result = t.distill("extend handler", session="feature-x")
# Tenets
t.tenet_add("Use async/await for I/O", priority="high", category="performance")
t.tenet_instill()
```
---
## Architecture
### NLP Pipeline
1. **Input Parsing**: Extract intent, temporal refs, external links
2. **File Scanning**: Parallel traversal respecting .gitignore
3. **Analysis**: AST parsing, import extraction (15+ languages)
4. **Ranking**: Multi-factor scoring with configurable weights
5. **ML (Optional)**: Semantic embeddings via `tenets[ml]`
6. **Tenets Injection**: Add guiding principles to context
7. **Output**: Token-optimized, model-specific formatting
### Supported Languages
Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, Scala, C#, and more.
### Output Formats
- `markdown`: Human-readable with headers
- `xml`: Claude-optimized with tags
- `json`: Structured for programmatic use
- `html`: Interactive report
---
## Configuration
Create `tenets.toml` in project root:
```toml
[ranking]
mode = "balanced"
max_tokens = 100000
[ranking.weights]
bm25 = 0.3
keywords = 0.2
imports = 0.2
git = 0.15
path = 0.15
[output]
format = "markdown"
copy_on_distill = true
[filters]
include = ["*.py", "*.js", "*.ts"]
exclude = ["**/node_modules/**", "**/dist/**"]
```
---
## Links
- **Website**: https://tenets.dev
- **GitHub**: https://github.com/jddunn/tenets
- **PyPI**: https://pypi.org/project/tenets/
- **Discord**: https://discord.gg/DzNgXdYm
## License
MIT License - 100% free and open source. No usage limits, no API costs.
