Tutorial: From Zero to AI-Powered Coding¶

Name: Tenets
Author: manic.agency

This tutorial walks you through using Tenets to supercharge your AI coding workflow. By the end, you'll be able to:

Build optimal context for any coding task
Use sessions to maintain state across prompts
Add tenets to keep AI responses consistent
Integrate with Claude, Cursor, or any MCP client

Time required: ~15 minutes

Prerequisites¶

Python 3.9+
A codebase to work with (or use any open-source project)
MCP-ready client: Cursor, Claude Desktop, Windsurf/VS Code MCP extension

Step 1: Installation (MCP-first)¶

Bash

pip install tenets[mcp]
tenets-mcp --version
# tenets-mcp v0.7.1

Add to your IDE:

Cursor (~/.cursor/mcp.json)

JSON

{ "mcpServers": { "tenets": { "command": "tenets-mcp" } } }

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
JSON
```
{ "mcpServers": { "tenets": { "command": "tenets-mcp" } } }
```

Windsurf / VS Code MCP

JSON

{ "tenets": { "command": "tenets-mcp" } }

Prefer to start from CLI only? Install without MCP:

Bash

pip install tenets
tenets --version
# tenets v0.7.1

Step 2: Your First Distill¶

Navigate to any codebase and run:

Bash

cd /path/to/your/project

tenets distill "how does authentication work"

What happens:

Tenets scans all files in the directory
Ranks them by relevance to "authentication"
Aggregates the most relevant code
Outputs token-optimized context

Example output:

Markdown

# Context for: how does authentication work

## Relevant Files (5 of 127 scanned)

### src/auth/login.py (relevance: 0.92)
```python
def authenticate_user(username: str, password: str) -> User:
    """Authenticate user with username and password."""
    user = User.query.filter_by(username=username).first()
    if user and user.check_password(password):
        return user
    raise AuthenticationError("Invalid credentials")

src/auth/middleware.py (relevance: 0.87)¶

...

Text Only

---

## Step 3: Understanding Ranking Modes

Tenets offers three ranking modes:

### Fast Mode (~1 second)

```bash
tenets distill "find payment code" --mode fast

Uses keyword matching and path analysis. Best for quick exploration.

Balanced Mode (~3 seconds, default)¶

Bash

tenets distill "find payment code" --mode balanced

Adds BM25 scoring, structure analysis, and git signals. Best for most tasks.

Thorough Mode (~10 seconds)¶

Bash

tenets distill "refactor the database layer" --mode thorough

Adds ML embeddings and deep semantic analysis. Best for complex refactoring.

Step 4: Working with Sessions¶

Sessions let you maintain state across multiple prompts.

Create a Session¶

Bash

tenets session create auth-refactor

Pin Important Files¶

Bash

# Pin a specific file
tenets session pin src/auth/login.py --session auth-refactor

# Pin an entire folder
tenets session pin src/auth/ --session auth-refactor

Use the Session¶

Bash

tenets distill "add OAuth2 support" --session auth-refactor

Pinned files are always included in context, regardless of ranking.

List Sessions¶

Bash

tenets session list

Step 5: Adding Tenets (Guiding Principles)¶

Tenets prevent AI "drift" by injecting consistent rules into every context.

Add Security Rules¶

Bash

tenets tenet add "Always validate and sanitize user input" --priority critical --category security

Add Code Style Rules¶

Bash

tenets tenet add "Use type hints for all function parameters and returns" --priority high --category style

Add Architecture Rules¶

Bash

tenets tenet add "All database access must go through the repository layer" --priority high --category architecture

View Your Tenets¶

Bash

tenets tenet list

Activate Tenets¶

Bash

tenets instill

Now every distill command will include your tenets at the top of the context.

Step 6: Output Formats¶

Markdown (default)¶

Bash

tenets distill "find auth" --format markdown

Human-readable with headers and code blocks.

XML (Claude-optimized)¶

Bash

tenets distill "find auth" --format xml

XML

<context>
  <file path="src/auth/login.py" relevance="0.92">
    <content>def authenticate_user(...)...</content>
  </file>
</context>

JSON (programmatic)¶

Bash

tenets distill "find auth" --format json

JSON

{
  "files": [
    {"path": "src/auth/login.py", "relevance": 0.92, "content": "..."}
  ],
  "token_count": 4500,
  "mode": "balanced"
}

Step 7: MCP Integration¶

Configure Claude Desktop¶

Open Claude Desktop settings
Add to claude_desktop_config.json:

JSON

{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp"
    }
  }
}

Restart Claude Desktop

Configure Cursor¶

Open Settings → MCP Servers
Add configuration:

JSON

{
  "tenets": {
    "command": "tenets-mcp"
  }
}

Restart Cursor

Using with AI¶

Now you can ask Claude or Cursor:

"Use tenets to find code related to user authentication"

The AI will call the distill tool and receive optimized context automatically.

Step 8: Advanced Patterns¶

Filter by File Type¶

Bash

# Only Python files
tenets distill "find utilities" --include "*.py"

# Exclude tests
tenets distill "find utilities" --exclude "test_*"

Include Test Files¶

Bash

tenets distill "debug the login test" --include-tests

Set Token Budget¶

Bash

# Small context for quick questions
tenets distill "what does X do" --max-tokens 10000

# Large context for complex refactoring
tenets distill "refactor authentication" --max-tokens 150000

Copy to Clipboard¶

Bash

tenets distill "find auth" --copy

Save to File¶

Bash

tenets distill "find auth" --output context.md

Step 9: Examine Your Codebase¶

Get insights about your codebase structure:

Bash

tenets examine

Output includes:

File count by language
Complexity hotspots
Code health score
Ownership analysis (from git)

Focus on Complexity¶

Bash

tenets examine --hotspots

Check Code Ownership¶

Bash

tenets examine --ownership

Step 10: Track Development Velocity¶

See what's changing in your codebase:

Bash

tenets chronicle --since "1 week ago"

Check Momentum¶

Bash

tenets momentum

Shows activity trends, hot files, and velocity metrics.

Putting It All Together¶

Here's a complete workflow for a new feature:

Bash

# 1. Create a session
tenets session create new-feature

# 2. Add guiding principles
tenets tenet add "Follow existing patterns in the codebase" --priority high
tenets tenet add "Add tests for all new functions" --priority high

# 3. Pin relevant code
tenets session pin src/features/ --session new-feature

# 4. Build context for your AI
tenets distill "implement user notifications feature" \
  --session new-feature \
  --mode balanced \
  --max-tokens 50000 \
  --copy

# 5. Paste into Claude/Cursor and start coding!

Next Steps¶

MCP Documentation — Deep dive into MCP server features
CLI Reference — Complete command documentation
Configuration — Customize Tenets for your workflow
Architecture — Understand how Tenets works

Get Help¶

Discord: Join our community
GitHub: Report issues
Email: team@tenets.dev

Built by manic.agency

Need custom AI tooling for your team?

Let's Talk →