# LLM Context User Guide
## Table of Contents
1. [Installation & Setup](#installation--setup)
2. [Core Workflow](#core-workflow)
3. [Rule System](#rule-system)
4. [AI-Assisted Rule Creation](#ai-assisted-rule-creation)
5. [Integration Options](#integration-options)
6. [Command Reference](#command-reference)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#troubleshooting)
## Installation & Setup
### Prerequisites
- Python 3.10+
- Project with `.gitignore` file
### Installation
```bash
uv tool install "llm-context>=0.5.0"
```
### Project Initialization
```bash
cd /path/to/your/project
lc-init
```
Creates `.llm-context/` directory with default configuration and rules.
## Core Workflow
### Human Workflow (Daily Development)
```bash
# 1. Select files (smart defaults based on active rule)
lc-select
# 2. Generate context
lc-context # For MCP environments
lc-context -nt # For manual workflows
# 3. Paste into AI chat
# 4. AI can access additional files via MCP as needed
```
### Agent Workflow (Context Provisioning)
**CLI (Claude Code, Cursor, etc.):**
```bash
# Validate rule effectiveness
lc-preview tmp-prm-auth
# Generate focused context
lc-context tmp-prm-auth
```
**MCP (Chat interfaces):**
```python
# Validate rule
preview = lc_preview(root_path, rule_name)
# Generate context
context = lc_outlines(root_path)
# Fetch additional files
files = lc_missing(root_path, "f", "['/proj/file.py']", timestamp)
```
## Rule System
### Systematic Organization
Rules use a five-category system with kebab-case prefixes:
- **Prompt Rules (`prm-`)**: Generate project contexts
- **Filter Rules (`flt-`)**: Control file inclusion/exclusion
- **Instruction Rules (`ins-`)**: Provide guidance and frameworks
- **Style Rules (`sty-`)**: Enforce coding standards
- **Excerpt Rules (`exc-`)**: Configure content extraction
### Rule Structure
Rules are Markdown files with YAML frontmatter:
```yaml
---
description: "Brief description"
instructions: [lc/ins-developer, lc/sty-python]
compose:
filters: [lc/flt-base, custom-filters]
excerpters: [lc/exc-base]
gitignores:
full-files: ["*.tmp", "/build"]
also-include:
full-files: ["/important.config"]
overview: "full" # or "focused"
---
## Rule Content
Markdown content providing additional context.
```
### Key Built-in Rules
**Prompt Rules:**
- `lc/prm-developer` - Standard development context
- `lc/prm-rule-create` - Full context for rule creation
**Filter Rules:**
- `lc/flt-base` - Standard exclusions (binaries, build artifacts)
- `lc/flt-no-files` - Exclude everything (use with `also-include`)
- `lc/flt-no-full` - Exclude all full files
- `lc/flt-no-outline` - Exclude all excerpted files
**Instruction Rules:**
- `lc/ins-developer` - Developer persona and guidelines
- `lc/ins-rule-framework` - Rule creation framework
- `lc/ins-rule-intro` - Chat-based rule creation intro
**Style Rules:**
- `lc/sty-code` - Universal programming principles
- `lc/sty-python` - Python-specific guidelines
- `lc/sty-javascript` - JavaScript-specific guidelines
**Excerpt Rules:**
- `lc/exc-base` - Base excerpting configuration
### Rule Composition Patterns
**Standard Development:**
```yaml
---
description: "Main development rule"
instructions: [lc/ins-developer, lc/sty-python]
compose:
filters: [lc/flt-base, project-filters]
excerpters: [lc/exc-base]
---
```
**Focused Task:**
```yaml
---
description: "Debug authentication"
compose:
filters: [lc/flt-no-files]
excerpters: [lc/exc-base]
also-include:
full-files: ["/src/auth/**", "/tests/auth/**"]
---
```
**Code Structure Only:**
```yaml
---
description: "Review architecture"
compose:
filters: [lc/flt-no-full]
excerpters: [lc/exc-base]
also-include:
excerpted-files: ["/src/**/*.py"]
---
```
### Path Format
All paths relative to project root, starting with `/`:
```yaml
# ✓ Correct
also-include:
full-files: ["/src/main.py", "/config/**"]
# ✗ Wrong - includes project name
also-include:
full-files: ["/myproject/src/main.py"]
```
**Pattern Examples:**
```yaml
also-include:
full-files:
- "/src/main.py" # Specific file
- "/config/**" # Directory contents
- "**/*.py" # All Python files
- "**/tests/**" # Test directories anywhere
- "**/*.{js,ts,jsx,tsx}" # Multiple extensions
```
## AI-Assisted Rule Creation
Let AI analyze your codebase and create focused rules. Two approaches:
### Claude Skill (Interactive)
**Setup:**
```bash
lc-init # Installs to ~/.claude/skills/
# Restart Claude Desktop or Claude Code
```
**Usage:**
```bash
# 1. Share project context (overview required)
lc-context
# 2. Paste into Claude, then ask:
# "Create a rule for refactoring authentication to JWT"
# "I need a rule to debug payment processing"
```
Claude examines your codebase via `lc-missing`, asks clarifying questions, and generates optimized rules saved to `.llm-context/rules/tmp-prm-<task>.md`.
**Skill Files** (progressively disclosed):
- `Skill.md` - Quick workflow and patterns
- `PATTERNS.md` - Common rule patterns
- `SYNTAX.md` - Detailed syntax reference
- `EXAMPLES.md` - Complete walkthroughs
- `TROUBLESHOOTING.md` - Problem solving
### Instruction Rules (Works Anywhere)
**Usage:**
```bash
# 1. Load framework
lc-set-rule lc/prm-rule-create
lc-select
lc-context -nt
# 2. Paste into any LLM and describe task
# "I need a rule for adding OAuth integration"
# 3. Use generated rule
lc-set-rule tmp-prm-oauth
lc-select
lc-context
```
**Included:**
- `lc/ins-rule-intro` - Introduction and overview
- `lc/ins-rule-framework` - Complete decision framework
### Comparison
| Aspect | Skill | Instruction Rules |
| ---------------- | ------------------------------ | ------------------------ |
| **Setup** | Automatic with `lc-init` | Already available |
| **Interaction** | Interactive, examines files | Static documentation |
| **Best for** | Claude Desktop/Code | Any LLM, any environment |
Both require project context first. Both produce equivalent results.
### Naming Conventions
- **Temporary tasks**: `tmp-prm-<task>` (e.g., `tmp-prm-api-debug`)
- **Permanent project**: `prm-<name>` (e.g., `prm-code`, `prm-api`)
- **System rules**: `lc/<category>-<name>` (e.g., `lc/flt-base`)
## Integration Options
### MCP Integration (Recommended)
**Setup:**
```jsonc
// claude_desktop_config.json
{
"mcpServers": {
"llm-context": {
"command": "uvx",
"args": ["--from", "llm-context", "lc-mcp"]
}
}
}
```
**Benefits:**
- AI accesses additional files automatically
- Track changes during conversation
- No manual file operations
**MCP Tools:**
- `lc_outlines` - Generate excerpted context
- `lc_preview` - Validate rule effectiveness
- `lc_missing` - Fetch files/implementations
- `lc_changed` - Track modifications
### Manual Workflow (Fallback)
When LLM requests additional files:
```bash
lc-missing -f "[file1, file2]" -t <timestamp>
lc-missing -i "[[file, def], ...]" -t <timestamp>
lc-missing -e "[file1, file2]" -t <timestamp>
```
### Deployment Patterns
| Pattern | Command | Use Case |
| -------------------------- | -------------------- | ------------------- |
| System Message | `lc-context -p` | AI Studio |
| Single User Message | `lc-context -p -m` | Grok |
| Separate Messages | `lc-prompt` + `lc-context -m` | Flexible |
| Project Files (included) | `lc-context` | Claude Projects |
| Project Files (searchable) | `lc-context -m` | Force into context |
## Command Reference
### Core Commands
**lc-init**
```bash
lc-init # Initialize project
```
**lc-set-rule**
```bash
lc-set-rule prm-code # Custom rule
lc-set-rule lc/prm-developer # System rule
lc-set-rule tmp-prm-my-task # Temporary task
```
**lc-select**
```bash
lc-select # Select files based on active rule
```
**lc-context**
```bash
lc-context # Generate context (MCP optimized)
lc-context -p # Include prompt
lc-context -u # Include user notes
lc-context -m # Separate message mode
lc-context -nt # No tools (manual workflow)
lc-context -f out.md # Write to file
```
**lc-preview**
```bash
lc-preview prm-code # Preview active rule
lc-preview tmp-prm-my-task # Preview temporary rule
```
**lc-outlines**
```bash
lc-outlines # Get code structure excerpts
```
### Utility Commands
**lc-missing**
```bash
lc-missing -f "[file1, file2]" -t <timestamp> # Files
lc-missing -i "[[file, def], [file, def]]" -t <ts> # Implementations
lc-missing -e "[file1, file2]" -t <timestamp> # Excluded sections
```
**lc-changed**
```bash
lc-changed # List modified files since last generation
```
**lc-prompt**
```bash
lc-prompt # Generate instructions only
```
**lc-rule-instructions**
```bash
lc-rule-instructions # Rule creation guidance
```
## Best Practices
### Rule Organization
**Permanent Rules** (`.llm-context/rules/`):
```
flt-repo-base.md # Project-specific filters
prm-code.md # General development
prm-api.md # API-focused work
prm-frontend.md # Frontend development
```
**Temporary Rules**:
```
tmp-prm-oauth-integration.md
tmp-prm-bug-investigation.md
tmp-prm-performance-debug.md
```
### Context Efficiency
**Typical Reductions:**
- Bug fixes: 70-90% reduction
- Feature development: 40-70% reduction
- Code review: 30-50% reduction
- Architecture changes: May need broader context
**Selection Strategy:**
- **Full content**: Files you'll modify, small configs, key logic
- **Excerpted content**: Large files where structure matters
- **Exclude**: Documentation (unless relevant), tests (unless debugging)
### Rule Composition
**Start with decisions:**
- Need guidelines? Include `lc/sty-*` rules
- Need minimal context? Start with `lc/flt-no-files`
- Need standard exclusions? Use `lc/flt-base`
- Need excerpting? Compose with `lc/exc-base`
**Layer compositions:**
```yaml
instructions: [lc/ins-developer, lc/sty-python]
compose:
filters: [lc/flt-base, project-filters]
excerpters: [lc/exc-base]
```
## Code Excerpting
Extracts structure while reducing tokens. Supports 15+ languages including C, C++, C#, Elixir, Go, Java, JavaScript, PHP, Python, Ruby, Rust, TypeScript, Vue, Svelte.
**Configuration:**
```yaml
compose:
excerpters: [lc/exc-base]
also-include:
full-files: ["/src/main.py"] # Complete content
excerpted-files: ["/src/utils/**"] # Structure only
```
## Troubleshooting
### No files selected
- Check paths start with `/` without project name
- Verify composed rules exist (e.g., `lc/flt-base`)
- Try `lc-set-rule lc/prm-developer` to test defaults
- Validate YAML syntax
### Context too large
- Use `lc/flt-no-files` with selective `also-include`
- Add exclusions to rule's `gitignores`
- Switch to `overview: "focused"`
- Create focused rule with `tmp-prm-` prefix
- Use excerpting via `lc/exc-base`
### Rule composition errors
- Verify referenced rules exist
- Use correct category prefixes (`lc/flt-base`, not `lc/base`)
- Check rule names match filenames exactly
### MCP not working
- Restart Claude Desktop after config changes
- Verify `lc-mcp` exists: `which lc-mcp`
- Check Claude Desktop logs
- Use manual workflow: `lc-context -nt`
### Rule Debugging
```bash
cat .llm-context/curr_ctx.yaml # See selected files
lc-changed # Check recent changes
lc-preview <rule> # Validate rule selection
```
### Recovery
```bash
# Backup custom rules
cp -r .llm-context/rules/*.md /tmp/backup/
# Reset to defaults
rm -rf .llm-context
lc-init
# Restore custom rules
cp /tmp/backup/*.md .llm-context/rules/
```
