ai-see

Give your AI coding agent x-ray vision into any codebase.

ai-see is a lightning-fast, zero-dependency, local environment context gathering tool purpose-built for AI Coding Agents and LLMs.

Unlike human-facing tools, ai-see always outputs deterministic, structured JSON without ANSI colors or interactive prompts. More importantly, it features an intelligent --budget system to protect your limited LLM context window by summarizing or truncating outputs when they get too large.

---

The "One Command" Context Injection

When an AI drops into a new repository, it usually takes ~5 round-trips to figure out what's going on. Compress that into 1 command:

npx ai-see scout --budget=3000

scout automatically runs env (to detect package managers, Node version, frameworks, test suites), tree (to map directory structure), reads README.md and .cursorrules / AGENTS.md, and grabs git status. It combines it all into a single JSON object.

(Try it yourself: npx ai-see scout --pretty)

---

Injection & Self-Propagation

Make any repository instantly understandable to future AI agents by running:

npx ai-see init

This will automatically find your AGENTS.md or .cursorrules and inject a standard system prompt snippet instructing AIs to use ai-see before modifying the project.

---

Core Commands

For AI tools, use these raw JSON endpoints:

1. env

Provides a snapshot of the tech stack, inferred frameworks, test commands, and basic git state.

npx ai-see env

2. tree

Maps directory structure with smart array-compaction to save tokens. Honors .gitignore by default.

npx ai-see tree src/ --depth=3

3. read

Surgically exact file reading. Supports line ranges and JSON key extraction.

# Extract only dependencies
npx ai-see read package.json --keys=dependencies,scripts

# Read only the failing lines
npx ai-see read src/auth.ts --lines=45-80

4. diff

Extract line modifications and status. Combine with --full for unified patch hunks.

npx ai-see diff
npx ai-see diff --full

5. help

If an agent forgets how to use the tool, it can self-heal by calling help to receive a structured JSON API guide instead of a human-formatted text blob.

npx ai-see help

---

Zero-Dependency & Speed

This package ships as a single, fully-bundled executable (cli.js). It uses only standard Node.js APIs (node:fs, node:child_process). Execution is essentially instantaneous.

Designed specifically for Aider, Cursor, Cline, and custom LLM workflows where every token matters.