ct-codebase-mapper

Codebase Mapper

Structured codebase analysis for autonomous agent understanding.

Quick Start

Goal	Command	Cost
Quick analysis	query admin map	~500 tokens
Deep analysis + store	mutate admin map	~800 tokens
Focus on one area	query admin map {focus: "concerns"}	~300 tokens
CLI	cleo map / cleo map --store	—

Progressive Disclosure

Tier 0: Quick Analysis

cleo map

Returns structured CodebaseMapResult with stack, architecture, structure, conventions, testing, integrations, and concerns.

Tier 1: Store to Brain

cleo map --store

Same analysis, but stores patterns, learnings, and observations to brain.db. Tagged with source: 'codebase-map' for filtering.

Tier 2: Focused Analysis

cleo map --focus concerns

Focus areas: stack, architecture, structure, conventions, testing, integrations, concerns.

When to Use

• New project onboarding: Run cleo map --store to build brain.db context
• Brownfield init: cleo init --map-codebase runs analysis during initialization
• Before epic planning: Understand project structure before decomposing work
• Tech debt assessment: query admin map {focus: "concerns"} for TODOs and large files

Output Structure

{
  projectContext: ProjectContext,  // From detectProjectType()
  stack: StackAnalysis,           // Languages, frameworks, deps
  architecture: ArchAnalysis,     // Layers, entry points, patterns
  structure: StructureAnalysis,   // Directory tree with annotations
  conventions: ConventionAnalysis,// Naming, linting, formatting
  testing: TestingAnalysis,       // Framework, patterns, coverage
  integrations: IntegrationAnalysis, // APIs, DBs, CI/CD
  concerns: ConcernAnalysis,      // TODOs, large files, complexity
  analyzedAt: string
}