Skip to content

user-guide.md

Latest commit

 

History

History
489 lines (377 loc) · 11.5 KB

user-guide.md

File metadata and controls

489 lines (377 loc) · 11.5 KB

LLM Context User Guide

Table of Contents

  1. Installation & Setup
  2. Core Workflow
  3. Rule System
  4. AI-Assisted Rule Creation
  5. Integration Options
  6. Command Reference
  7. Best Practices
  8. Troubleshooting

Installation & Setup

Prerequisites

  • Python 3.10+
  • Project with .gitignore file

Installation

uv tool install "llm-context>=0.5.0"

Project Initialization

cd /path/to/your/project
lc-init

Creates .llm-context/ directory with default configuration and rules.

Core Workflow

Human Workflow (Daily Development)

# 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.):

# Validate rule effectiveness
lc-preview tmp-prm-auth

# Generate focused context
lc-context tmp-prm-auth

MCP (Chat interfaces):

# 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:

---
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:

---
description: "Main development rule"
instructions: [lc/ins-developer, lc/sty-python]
compose:
  filters: [lc/flt-base, project-filters]
  excerpters: [lc/exc-base]
---

Focused Task:

---
description: "Debug authentication"
compose:
  filters: [lc/flt-no-files]
  excerpters: [lc/exc-base]
also-include:
  full-files: ["/src/auth/**", "/tests/auth/**"]
---

Code Structure Only:

---
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 /:

# ✓ Correct
also-include:
  full-files: ["/src/main.py", "/config/**"]

# ✗ Wrong - includes project name
also-include:
  full-files: ["/myproject/src/main.py"]

Pattern Examples:

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:

lc-init  # Installs to ~/.claude/skills/
# Restart Claude Desktop or Claude Code

Usage:

# 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:

# 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:

// 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:

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

lc-init  # Initialize project

lc-set-rule

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

lc-select  # Select files based on active rule

lc-context

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

lc-preview prm-code           # Preview active rule
lc-preview tmp-prm-my-task    # Preview temporary rule

lc-outlines

lc-outlines  # Get code structure excerpts

Utility Commands

lc-missing

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

lc-changed  # List modified files since last generation

lc-prompt

lc-prompt  # Generate instructions only

lc-rule-instructions

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:

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:

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

cat .llm-context/curr_ctx.yaml  # See selected files
lc-changed                      # Check recent changes
lc-preview <rule>               # Validate rule selection

Recovery

# 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/