AI Context Manager 🤖

Intelligent context management system for Claude Code that provides focused, project-specific knowledge to AI assistants.

Why AI Context Manager?

When working with AI assistants like Claude Code on complex projects, providing the right context is crucial for getting accurate, helpful responses. This tool helps you:

• 🎯 Focus AI attention on specific parts of your codebase
• 📚 Organize project knowledge with dependencies and guidelines
• 🚀 Speed up development with instant context loading
• 💰 Save costs by providing only relevant information

Installation

npm install -g ai-context-manager

Quick Start

1. Initialize in your project

cd your-project
ai-context init

This creates:

• .claude-context/ directory with example contexts
• .claude.json with /load-context slash command for Claude Code

2. Generate contexts in Claude Code

# Analyze entire codebase and suggest contexts
/generate-contexts

# Generate specific context with hints
/generate-context payment --hint "Stripe integration, webhooks" --files "PaymentController.php"

# Load existing context
/load-context auth

Claude now has focused knowledge and can intelligently generate contexts!

CLI Commands

Initialize Context Management

ai-context init

• Creates .claude-context/ directory
• Sets up example contexts (auth, database, frontend)
• Configures Claude Code slash command

Create New Context

# Basic context
ai-context add api

# With description and files
ai-context add api -d "REST API endpoints" -f "src/api/**" "routes/**"

# With dependencies
ai-context add frontend -d "React components" --deps auth api

Add Files to Context

# Add specific files
ai-context add-file auth src/middleware/auth.js types/user.ts

# Add multiple files
ai-context add-file api controllers/UserController.php controllers/AuthController.php routes/api.php

Auto-Generate Contexts

# Analyze codebase and generate contexts automatically
ai-context generate --dry-run  # Preview what will be created
ai-context generate            # Actually create the contexts

Test Context Loading

ai-context load auth

Context Structure

Each context lives in .claude-context/<name>/:

.claude-context/
├── auth/
│   ├── config.js          # Required configuration
│   ├── guidelines.md      # Optional detailed guidelines  
│   └── examples/          # Optional code examples
│       ├── login-flow.js
│       └── middleware.js
├── database/
│   └── config.js
└── api/
    ├── config.js
    ├── guidelines.md
    └── examples/
        └── endpoint-pattern.js

config.js Schema

export default {
  description: "Authentication and authorization system",
  dependencies: ["database", "security"],
  files: [
    "src/auth/**",           // Glob patterns supported
    "middleware/auth.js",     // Specific files
    "types/auth.ts"
  ],
  quickGuidelines: "Always hash passwords, validate tokens, check permissions"
};

Usage Examples

Automatic Generation (Recommended)

# Let AI analyze your codebase and generate contexts
ai-context init
ai-context generate --dry-run  # Preview generated contexts
ai-context generate            # Create them

# Result: Automatically detects and creates contexts like:
# - database (models, migrations)
# - auth (authentication files) 
# - api (API controllers, routes)
# - frontend (views, templates)
# - admin (admin interface files)

# Load context in Claude Code
/load-context auth

Manual Context Creation

# Initialize
ai-context init

# Create API context manually
ai-context add api -d "REST API layer" -f "src/api/**" "routes/**" --deps database

# Create frontend context  
ai-context add frontend -d "React components" -f "src/components/**" --deps auth api

# Add specific controller files
ai-context add-file api controllers/UserController.php controllers/PostController.php

# Load context in Claude Code
/load-context frontend

Microservice Context

# User service context
ai-context add user-service -d "User management microservice" -f "services/user/**"

# Payment service context
ai-context add payment-service -d "Payment processing" -f "services/payment/**" --deps user-service

# Load payment context (automatically includes user-service dependency)
/load-context payment-service

Advanced Features

Dependency Resolution

Contexts automatically load their dependencies:

// frontend/config.js
export default {
  dependencies: ["auth", "api"]
};

When you run /load-context frontend, it loads:

1. auth context + its files & guidelines
2. api context + its files & guidelines
3. frontend context + its files & guidelines

Guidelines & Examples

guidelines.md - Detailed documentation:

# Authentication Guidelines

## Security Best Practices
- Always hash passwords using bcrypt
- Validate JWT tokens on protected routes
- Implement proper session management

## Code Patterns
\`\`\`javascript
const validateToken = (token) => {
  return jwt.verify(token, process.env.JWT_SECRET);
};
\`\`\`

examples/ - Code samples in natural formats:

examples/
├── login-flow.js      # Complete login implementation
├── middleware.ts      # Auth middleware example
└── validation.php     # Input validation patterns

File Pattern Matching

Supports powerful glob patterns:

files: [
  "src/auth/**",           // All files in auth directory
  "**/*.{js,ts}",         // All JS/TS files  
  "controllers/*Auth*",    // Files containing 'Auth'
  "!tests/**"             // Exclude tests
]

Integration with Claude Code

Once initialized, you have powerful slash commands available:

Context Generation Commands

# Analyze entire codebase and generate contexts
/generate-contexts

# Generate targeted context with hints
/generate-context payment --hint "Stripe integration, webhooks, subscriptions"
/generate-context auth --hint "JWT, 2FA, password reset" --files "AuthController.php,middleware/auth.js"
/generate-context api --hint "REST endpoints, validation" --guidelines "Use rate limiting, validate all inputs"

Context Loading Commands

# Load specific context
/load-context auth

# List available contexts
/load-context

Context Generation Features:

• 🔍 Intelligent Analysis - Detects technologies, patterns, and relationships
• 🎯 Targeted Generation - Specify hints, files, and guidelines
• 📁 File Preview - Shows relevant code during generation
• 🔗 Auto-Dependencies - Suggests logical dependencies
• 💡 Best Practices - Generates appropriate guidelines

Loaded Context Includes:

• 📋 Context description & dependencies
• 📝 Guidelines and best practices
• 📁 Relevant file contents (up to 10 files)
• 💡 Code examples
• 🔗 Dependency context information

Best Practices

Context Organization

• Keep contexts focused - One concern per context
• Use dependencies - Break down complex systems
• Add examples - Show intended patterns
• Update regularly - Keep file lists current

File Selection

• Be specific - Target exact files needed
• Use patterns wisely - src/auth/** vs **/*auth*
• Exclude tests - Usually not needed for context
• Limit scope - Too many files = token overflow

Guidelines

• Write clear guidelines - Explain the "why", not just "what"
• Include code examples - Show expected patterns
• Update with learnings - Capture new insights
• Keep it actionable - Focus on practical advice

Troubleshooting

Context not found

Error: Context "auth" not found

Solution: Check .claude-context/auth/config.js exists

File patterns not matching

Warning: Could not resolve pattern "src/auth/**"

Solution: Verify file paths exist and pattern syntax

Circular dependencies

The system automatically prevents infinite loops in dependency chains.

Too many files loading

Limit to essential files or use more specific patterns:

files: [
  "src/auth/AuthService.js",     // Specific files
  "src/auth/types.ts",           // Key type definitions
  "!src/auth/tests/**"           // Exclude tests
]

Examples Repository

Check out complete examples at: ai-context-examples

• E-commerce application contexts
• Microservice architecture
• Full-stack web app
• Mobile app backend

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Made with ❤️ for better AI-assisted development