DevIntrospect

⚠️ Status: Early Development / Unstable

DevIntrospect is actively under development. APIs, behavior, naming, and internal architecture may change frequently and without notice. Do not rely on DevIntrospect for production use at this stage.

DevIntrospect (dvi) is a repository analyzer and AI handoff generator. It scans a project, summarizes structure and size, detects languages/frameworks/tools, extracts manifest facts, and renders terminal, Markdown, JSON, or AI-oriented output.

It exists to give humans and AI coding agents a compact, repeatable picture of an unfamiliar codebase.

Quick Start

deno task dev -- --help
deno task dev -- . --format ai
deno task dev -- . --format json --git-only

Install

deno install -A -n dvi jsr:@forafekt/devintrospect/cli
npm install -g devintrospect
curl -fsSL https://github.com/forafekt/devintrospect/releases/latest/download/install.sh | sh
wget -qO- https://github.com/forafekt/devintrospect/releases/latest/download/install.sh | sh

Local development:

deno install -A -f -n dvi ./src/cli.ts

Verify an install:

dvi --version
dvi --self-test

Output Formats

dvi . --format ansi
dvi . --format plain
dvi . --format markdown -o REPO.md
dvi . --format json -o repo.json
dvi . --format ai -o AI_HANDOFF.md

JSON output includes schemaVersion, tool, root, summary, detections, entries, tree, manifests, hotspots, biggest files, and largest directories.

MCP and Optional AI

Run DevIntrospect as a stdio MCP server:

dvi mcp

Optional AI-oriented commands consume analyzer output without requiring an API key:

dvi ai handoff .
dvi ai explain .
dvi ai risks .
dvi ai next-files .

See MCP setup and AI commands.

Packs and Updates

dvi pack list
dvi pack install ./my-pack
dvi pack install https://example.com/company-pack.tar.gz --trust community
dvi pack update --all
dvi update --check
dvi update --packs
dvi update --all --dry-run

See packs, config layers, updates, security, and air-gapped usage.

Configuration

dvi.json is discovered in the scan root or loaded with --config.

{
  "version": 1,
  "defaults": {
    "format": "ai",
    "gitOnly": true,
    "showLines": true,
    "topHotspots": 20
  },
  "ignore": {
    "useDefaultPatterns": true,
    "readGitignore": true,
    "readIgnore": true,
    "patterns": ["tmp", "*.generated.ts"]
  }
}

Custom Rules

{
  "version": 1,
  "detect": {
    "pathRules": [
      { "type": "basename", "match": "wrangler.toml", "emit": ["tool:cloudflare"] }
    ],
    "rules": [
      { "id": "cloudflare", "ifAny": ["tool:cloudflare"], "emit": ["detect:tool:cloudflare"] }
    ]
  }
}

Rules support ifAll, ifAny, ifNone, and emit. Path rules support basename, exact, glob, and ext.

Detectors

Built-in detection covers TypeScript, JavaScript, JSX/TSX, Deno, Node, Vue, React, Svelte, Python, Go, Rust, Shell, HTML/CSS, SQL, JSON/YAML/TOML/Markdown, Docker, GitHub Actions, GitLab CI, Vite, Vitest, Jest, Playwright, Cypress, Next.js, Nuxt, SvelteKit, Astro, Express, Hono, Fastify, Oak, Turborepo, Nx, and Lerna.

Manifest extraction covers package.json, deno.json, Cargo.toml, go.mod, pyproject.toml, requirements.txt, Dockerfiles, CI configs, and TypeScript configs where practical.

Detector metadata lives beside detector modules under src/detect/detectors. Registry loaders discover detectors, extractors, schemas, and rules by convention.

Development

deno task dev -- --help
deno task test
deno task lint
deno task fmt
deno task build:npm
sh scripts/smoke-release.sh

Architecture, config, rules, JSON output, install, and release notes live in docs/.