Agentlens

AgentLens - Codebase Navigation

Before Working on Any Codebase

Always start by reading .agentlens/INDEX.md for the project map.

Navigation Hierarchy

Navigation Flow

INDEX.md → Find module → MODULE.md → outline.md/memory.md → Source file

When To Read What

Best Practices

1. Don't read source files directly for large codebases - use outline.md first 2. Check memory.md before modifying code to see warnings and TODOs 3. Use outline.md to locate symbols, then read only the needed source sections 4. Regenerate docs with agentlens command if they seem stale

For detailed navigation patterns, see references/navigation.md For structure explanation, see references/structure.md

Navigation Patterns

Pattern 1: Exploring a New Codebase

1. Read .agentlens/INDEX.md
   → Get list of all modules
   → Note entry points and hub modules

2. Pick relevant module from INDEX
   → Read modules/{slug}/MODULE.md
   → Understand module purpose and files

3. Need specific symbol?
   → Read modules/{slug}/outline.md
   → Find line number of function/class

4. Check for issues first?
   → Read modules/{slug}/memory.md
   → See TODOs, warnings before editing

Pattern 2: Finding Where Something Is Defined

1. Start with INDEX.md
2. Search for keyword in module descriptions
3. Go to matching MODULE.md
4. Check outline.md for symbol locations
5. Read only the specific source lines needed

Pattern 3: Understanding Dependencies

1. Read modules/{slug}/imports.md
2. See which files import what
3. Understand the dependency graph
4. Navigate to related modules as needed

Pattern 4: Before Modifying Code

1. Read memory.md for the module
2. Check for:
   - TODO: Pending work
   - FIXME: Known bugs
   - WARNING: Dangerous areas
   - SAFETY: Critical invariants
   - DEPRECATED: Code to avoid
3. Understand the context before changes

Token Efficiency Tips

• Never read entire source files in large codebases
• Use outline.md to find exact line numbers first
• Read only relevant sections of source code
• Navigate hierarchically: INDEX → MODULE → outline → source
• Estimated savings: 80-96% fewer tokens than reading raw source

AgentLens Output Structure

Directory Layout

.agentlens/
├── INDEX.md              # L0: Global routing table
├── AGENT.md              # Agent-specific instructions
├── modules/
│   └── {module-slug}/
│       ├── MODULE.md     # L1: Module overview
│       ├── outline.md    # L1: Symbol maps for large files
│       ├── memory.md     # L1: TODOs, warnings, rules
│       └── imports.md    # L1: File dependencies
└── files/
    └── {file-slug}.md    # L2: Deep docs for complex files

File Purposes

INDEX.md (Always Read First)

• Project name and description
• Complete list of modules with descriptions
• Entry points (main files)
• Hub files (heavily imported)
• High-priority warnings summary

MODULE.md

• Module purpose and responsibility
• List of all files in the module
• File descriptions and line counts
• Language breakdown

outline.md

• Symbol maps for large files (>500 lines)
• Functions, classes, structs, enums, traits
• Line numbers for quick navigation
• Visibility (public/private)

memory.md

• TODO comments
• FIXME and BUG markers
• WARNING and SAFETY notes
• DEPRECATED markers
• Business rules (RULE, POLICY)

imports.md

• Which files import which
• Internal dependencies within module
• Helps understand coupling

files/{slug}.md (L2 - Complex Files Only)

• Generated for very complex files
• Detailed symbol documentation
• More context than outline.md