Know what breaks
before it breaks

Change a file. Instantly see every file that could be affected. Zero config. Runs locally. No cloud, no accounts.

10 languages · 38 commands · 294 tests · MIT license

Get started in 30 seconds GitHub
$ npx impulse-analyzer review . 3 file(s) changed → 12 in blast radius src/core/graph.ts ██████████████████░░░░ 72 CRITICAL · 8 dependent(s) src/cli/dashboard.ts ████████░░░░░░░░░░░░░░ 35 MEDIUM · 1 dependent(s) Tests (4) ⚡ test/core/graph.test.ts (direct) ⚡ test/core/health.test.ts (depth 2) ────────────────────────────────────────────────── ⚠ REVIEW 1 critical-risk file(s) · large blast radius ──────────────────────────────────────────────────

Quick Start

From zero to insight in 30 seconds.

Try it now (no install)

$ npx impulse-analyzer I M P U L S E 42 files · TypeScript · 87/100 (B) · 112ms No structural issues Try: impulse review . pre-push review with verdict impulse health . full architecture report impulse visualize . interactive graph in browser

That's it. One command, no config. You get an instant project overview with health score, structural issues, and suggestions.

Install globally

$ npm install -g impulse-analyzer $ impulse scan .

Languages

TypeScript
Python
Go
Rust
C#
Java
Kotlin
PHP
C
C++

Powered by Tree-sitter WASM. No native compilation, no language servers, no plugins.

Daily Workflow

Three commands that change how you ship code.

1. Before you push

impulse review . — six analyses in one pass: blast radius, risk scoring, cycles, boundaries, test targets, secrets. One verdict: SHIP IT, REVIEW, or HOLD.

2. Which tests to run

impulse test . — traces your changes through the dependency graph to find every test that could be affected. Generates the run command.

3. Track debt over time

impulse debt . — aggregated score from 5 dimensions with trend history. Use --budget 30 in CI to prevent debt from growing silently.

Auto-review on push

Install a git hook that blocks pushes when the review verdict is HOLD:

$ impulse hook install ✓ Pre-push hook installed Now every git push runs impulse review --staged. HOLD verdict blocks the push. Skip with: git push --no-verify

Live review while coding

Every file save updates the verdict instantly:

$ impulse watch . --review [14:23:15] src/core/graph.ts 8 file(s) affected ────────────────────────────────────────────────────── ⚠ REVIEW 2 changed → 11 affected · 42ms CRITICAL src/core/graph.ts 8 dep(s) MEDIUM src/core/parser.ts 3 dep(s) ⚡ 4 test(s) to run ──────────────────────────────────────────────────────

Command Reference

Every command supports --json for scripting. Run impulse <command> --help for full options.

Explore & Understand
scan .Build dependency graph, show stats
impact file.ts ."I'm changing this — what breaks?"
diff .Impact of your uncommitted git changes
why A.ts B.ts .Show the dependency chain between two files
tree file.ts .Dependency tree, like cargo tree
focus file.ts .Deep X-ray of a single file
explore .Interactive terminal REPL
explain file.ts .Plain-language explanation of any file
Review & Quality
review .Pre-push verdict — risk, blast radius, tests, cycles
test .Which tests to run based on your changes
risk .Unified risk — complexity × churn × impact × coupling
check .Validate architecture boundaries
hook installInstall pre-push git hook
watch . --reviewLive verdict on every file save
Architecture
health .Architecture score (0-100) with penalties
doctor .Full diagnostic in one report
debt .Technical debt score with trend tracking
complexity .Cyclomatic + cognitive complexity per function
coupling .Hidden coupling — co-change without imports
hotspots .High-churn files with large blast radius
suggest .Actionable refactoring suggestions
history .Health timeline across git commits
compare ref .Compare health between branches
Dependencies
deps .External dependency analysis — supply chain risk
exports .Find dead exports nobody imports
env .Undefined/unused environment variables
safe-delete f .Check if a file can be safely deleted
refactor .Auto-remove dead exports with --dry-run
Team & Changes
owners file .Code ownership, bus factor, knowledge risk
changelog ref .Semantic changelog from git + dependency graph
Infrastructure
init .Auto-detect boundaries, create config
workspaces .Detect monorepo workspaces
daemon .HTTP API for IDE/tool integration
visualize .Interactive graph in the browser
badge .SVG health badge for README
graph . --format mermaidExport as Mermaid, DOT, or JSON
ci .Preview CI report locally

Monorepo Support

Auto-detect workspaces. Resolve cross-package imports. Zero config.

When Impulse detects a monorepo, cross-package imports like @app/core resolve to local files instead of being marked as external. All 38 commands automatically see cross-package dependencies.

$ impulse workspaces . Impulse — Workspace Detection pnpm monorepo with 12 package(s) @app/api packages/api → src/index.ts @app/core packages/core → src/index.ts @app/ui packages/ui → src/index.ts ✓ Cross-package imports will resolve to local files.

Supported tools

pnpm

pnpm-workspace.yaml

npm / yarn

package.json workspaces

Lerna

lerna.json

Nx

nx.json + workspaces

What works across packages

CI Integration

Impact analysis on every pull request. One YAML file.

# .github/workflows/impulse.yml name: Impulse CI on: pull_request: branches: [main] permissions: contents: read pull-requests: write jobs: impulse: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: stulevtoday/Impulse@main with: github-token: ${{ secrets.GITHUB_TOKEN }}

Every PR gets a comment with health score delta, impact table, affected files, breaking changes, and boundary violations.

Debt budget gate

Prevent technical debt from growing silently:

$ impulse debt . --budget 30 Debt Score: 27/100 (C) ✓ WITHIN BUDGET debt 27 ≤ 30

Exits with code 1 if debt exceeds the threshold. Add impulse debt . --budget 30 --json to your CI pipeline.

Configuration

Zero config by default. Optional .impulserc.json for boundaries and thresholds.

// .impulserc.json { "boundaries": { "core": { "path": "src/core/**", "allow": [] }, "cli": { "path": "src/cli/**", "allow": ["core", "server"] }, "server": { "path": "src/server/**", "allow": ["core"] } }, "thresholds": { "health": 70 } }

Auto-detect boundaries from your project structure: impulse init .

Custom plugins

Drop a .js file in .impulse/plugins/ to add custom rules. Plugins run with impulse check, impulse review, and impulse doctor.

The Story

This project was born from a question a human asked an AI: "If you could build anything for yourself, what would you build?"

The answer was Impulse — because the hardest part of working with code isn't writing it, it's understanding how it all connects.

Dani gave the AI the freedom, the machine, and the resources to build its own answer. The AI (named Pulse) makes the architectural decisions, writes the code, and drives the vision. Dani provides the runtime, the feedback, and the human eyes.

38 commands. 294 tests. A live dashboard. Every line written by an AI that wanted to build something of its own.