Lootbox Cached Codemaps Explained - How AI tools get codebase context

gistfile0.txt

# Cached Codemaps in Lootbox

## What is a Codemap?

A **codemap** is a compressed representation of your codebase that AI tools use to understand your project structure without reading every file. It extracts:

- Function and class signatures
- Export statements
- Type/interface definitions
- File organization

This gives AI tools enough context to provide relevant answers while keeping token usage manageable (10-50K tokens vs millions for raw files).

## Cache Location

```
~/.lootbox/cache/codemaps/codemap-{repo-name}-{hash}.json
```

## Cache Structure

Each cached codemap is a JSON file with this structure:

```json
{
  "version": 1,
  "repoPath": "/Users/you/dev/your-project",
  "repoName": "your-project",
  "createdAt": "2025-11-27T16:26:55.301Z",
  "lastValidatedAt": "2025-11-27T16:26:55.301Z",
  "gitCommitHash": "cac0dbbfa099f833bcf620d3e8b00d60e731ab45",
  "codemap": "<prompt>...</prompt>"
}
```

### Fields Explained

| Field | Purpose |
|-------|---------|
| `version` | Schema version for future migrations |
| `repoPath` | Absolute path to the repository |
| `repoName` | Repository name (from directory) |
| `createdAt` | When codemap was first generated |
| `lastValidatedAt` | Last time cache was checked/updated |
| `gitCommitHash` | HEAD commit when generated |
| `codemap` | The actual XML-formatted signatures |

## Smart Invalidation

The cache is invalidated when:

1. **Age check** - Codemap older than 3 days triggers revalidation
2. **Git commit check** - If HEAD differs from `gitCommitHash`, regenerate
3. **Missing file** - Cache file doesn't exist

This means:
- Same branch, no commits → use cache (fast)
- New commits → regenerate (accurate)
- Switch branches → different hash file, may regenerate

## Codemap Format

The `codemap` field contains XML-structured file signatures:

```xml
<prompt>
  <files>
    <file path="src/lib/api.ts" type="typescript" format="codemap">
export interface ApiClient {
export async function fetchData(url: string): Promise<Response>
export class HttpClient {
    </file>
    <file path="src/components/Button.tsx" type="typescript" format="codemap">
export interface ButtonProps {
export function Button({ children, onClick }: ButtonProps): JSX.Element
    </file>
  </files>
</prompt>
```

Files with no extractable signatures show:
```xml
<file path="config.json" type="json" format="codemap">
// No signatures extracted
</file>
```

## Current Cached Codemaps

### kit-container (17KB)
- **Path:** `/Users/johnlindquist/dev/kit-container`
- **Commit:** `fdfd83ac13e4e2f4896e18f0aa564eeac968f7ac`
- **Content:** Electron app with prompt windows, IPC channels, script execution
- **Key signatures:** `KitPrompt` class, `WindowPool`, flow functions, channel enums

### lootbox-bun (48KB)
- **Path:** `/Users/johnlindquist/dev/lootbox-bun`
- **Commit:** `cac0dbbfa099f833bcf620d3e8b00d60e731ab45`
- **Content:** MCP tool server with 20+ AI tools
- **Key signatures:** Tool exports (`gemini.ts`, `council.ts`, `chrome_devtools.ts`), shared utilities, worker managers

## Tools That Use Codemaps

These tools automatically inject codemap context (default: `include_codemap: true`):

- `council` - Multi-agent queries
- `deep-think` - Reasoning with project context
- `deep-research` - Research anchored to codebase
- `deep-review` - Code review with full structure
- `stuck` - Problem solving
- `gemini-think` - Analysis with codebase structure
- `brainstorm` - Ideas grounded in existing code
- `article` - Technical articles with accurate context
- `long-agent` - Agent handoffs with project map
- `deepwiki` - Library answers tailored to your project
- `code-spider` - Parallel codebase analysis

## Opting Out

Set `include_codemap: false` when:
- Question is theoretical (no code involved)
- Analyzing external codebase
- Token budget concerns

## Manual Operations

```typescript
// Force regeneration
{ include_codemap: true, force: true }

// Clear all caches
clearAllCodeMapCaches()

// List cached codemaps
listCachedCodeMaps()

// Get metadata without full codemap
getCodeMapMetadata(repoPath)
```

## Why This Matters

Without codemaps, AI tools give generic advice. With codemaps, they:
- Know your file structure
- Reference your actual functions/classes
- Understand your patterns and conventions
- Provide contextually relevant suggestions

The caching ensures this context is available instantly without regenerating on every tool call.