Skip to content
Back to research

Cartograph: CLI-First Repository Analysis for AI Agents

published
GitHub

Overview

AI coding agents burn 20-40% of their context window just figuring out where things are. Cartograph solves the repo-orientation problem by analyzing repository structure upfront and providing ranked, task-relevant context to any agent framework.

What It Does

Cartograph performs static analysis on a codebase and produces structured artifacts that agents can consume directly:

  • File ranking: Scores every file by architectural importance (entry points, high-import-count modules, config files) so agents focus on what matters
  • Dependency hub tracing: Maps which modules are most depended-on, revealing the load-bearing code that changes cascade through
  • Task-scoped context: Given a task description, pulls only the files relevant to that specific change — not the entire repo
  • Structured output: JSON artifacts designed for Claude Code, OpenClaw, or any agent that accepts structured context

Design Principles

CLI-first: Runs as a standalone command, not a library. Pipe it into your agent’s context window or use the built-in skills for Claude Code.

Fast: Static analysis only — no LLM calls, no embeddings, no vector stores. Analyzes a 10K-file repo in seconds.

Framework-agnostic: Output is structured JSON/Markdown. Works with Claude Code (via 2 built-in skills), OpenClaw, or any agent that reads text.

Installation

npm install -g @anthony-maio/cartograph

Usage

# Analyze current repo
cartograph analyze

# Get task-scoped context
cartograph context "add authentication to the API"

# Build a full task packet for an agent
cartograph packet "refactor the database layer"