io.github.atef-ataya/depwire
Dependency graph + 10 MCP tools for AI coding. TypeScript, Python, JS, and Go.
Ask AI about io.github.atef-ataya/depwire
Powered by Claude Β· Grounded in docs
I know everything about io.github.atef-ataya/depwire. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Depwire

See how your code connects. Give AI tools full codebase context.
β If Depwire helps you, please star the repo β it helps this open-source project grow into an enterprise tool.
Depwire analyzes codebases to build a cross-reference graph showing how every file, function, and import connects. It provides:
- π¨ Beautiful arc diagram visualization β Interactive Harrison Bible-style graphic
- π€ MCP server for AI tools β Cursor, Claude Desktop get full dependency context
- π Dependency health score β 0-100 score across 6 dimensions (coupling, cohesion, circular deps, god files, orphans, depth)
- π Auto-generated documentation β 12 comprehensive documents: architecture, conventions, dependencies, onboarding, file catalog, API surface, error patterns, test coverage, git history, full snapshot, TODO/FIXME inventory, and health report
- π Impact analysis β "What breaks if I rename this function?" answered precisely
- π Live updates β Graph stays current as you edit code
- π Multi-language β TypeScript, JavaScript, Python, and Go
Why Depwire?
AI coding tools are flying blind. Every time Claude, Cursor, or Copilot touches your code, it's guessing about dependencies, imports, and impact. The result: broken refactors, hallucinated imports, and wasted tokens re-scanning files it already saw.
Lost context = lost money + lost time + bad code.
Depwire parsed the entire Hono framework β 305 files, 5,636 symbols, 1,565 dependency edges β in 2.3 seconds.
Depwire fixes this by giving AI tools a complete dependency graph of your codebase β not a fuzzy embedding, not a keyword search, but a deterministic, tree-sitter-parsed map of every symbol and connection.
Stop Losing Context
- No more "start from scratch" chats β Depwire is the shared knowledge layer that every AI session inherits. New chat? Your AI already knows the architecture.
- Stop burning tokens β AI tools query the graph instead of scanning hundreds of files blindly
- One command, every AI tool β Claude Desktop, Cursor, VS Code, any MCP-compatible tool gets the same complete picture
Ship Better Code
- Impact analysis for any change β renaming a function, moving a file, upgrading a dependency, deleting a module β know the full blast radius before you touch anything
- Refactor with confidence β see every downstream consumer, every transitive dependency, 2-3 levels deep
- Catch dead code β find symbols nobody references anymore
Stay in Flow
- Live graph, always current β edit a file and the dependency map updates in real-time. No re-indexing, no waiting.
- Works locally, stays private β zero cloud accounts, zero data leaving your machine. Just
npm installand go.
13 MCP Tools, Not Just Visualization
Depwire isn't just a pretty graph. It's a full context engine with 13 tools that AI assistants call autonomously β architecture summaries, dependency tracing, symbol search, file context, health scores, and more. The AI decides which tool to use based on your question.
Installation

npm install -g depwire-cli
Or use directly with npx:
npx depwire-cli --help
Quick Start
CLI Usage
# Visualization (opens in browser)
npx depwire-cli viz ./my-project
# Parse and export as JSON
npx depwire-cli parse ./my-project
# Exclude test files and node_modules
npx depwire-cli parse ./my-project --exclude "**/*.test.*" "**/node_modules/**"
# Show detailed parsing progress
npx depwire-cli parse ./my-project --verbose
# Export with pretty-printed JSON and statistics
npx depwire-cli parse ./my-project --pretty --stats
# Generate codebase documentation
npx depwire-cli docs ./my-project --verbose --stats
# Custom output file
npx depwire-cli parse ./my-project -o my-graph.json
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"depwire": {
"command": "npx",
"args": ["-y", "depwire-cli", "mcp"]
}
}
}
Then in chat:
Connect to /path/to/my/project and show me the architecture.
Cursor
Settings β Features β Experimental β Enable MCP β Add Server:
- Command:
npx - Args:
-y depwire-cli mcp /path/to/project
Available MCP Tools
| Tool | What It Does |
|---|---|
connect_repo | Connect to any local project or GitHub repo |
impact_analysis | What breaks if you change a symbol? |
get_file_context | Full context β imports, exports, dependents |
get_dependencies | What does a symbol depend on? |
get_dependents | What depends on this symbol? |
search_symbols | Find symbols by name |
get_architecture_summary | High-level project overview |
list_files | List all files with stats |
get_symbol_info | Look up any symbol's details |
visualize_graph | Generate interactive arc diagram visualization |
get_project_docs | Retrieve auto-generated codebase documentation |
update_project_docs | Regenerate documentation on demand |
get_health_score | Get 0-100 dependency health score with recommendations |
Supported Languages
| Language | Extensions | Features |
|---|---|---|
| TypeScript | .ts, .tsx | Full support β imports, classes, interfaces, types |
| JavaScript | .js, .jsx, .mjs, .cjs | ES modules, CommonJS require(), JSX components |
| Python | .py | Imports, classes, decorators, inheritance |
| Go | .go | go.mod resolution, structs, interfaces, methods |
Visualization


# Open visualization on default port (3456)
depwire viz ./my-project
# Custom port
depwire viz ./my-project --port 8080
# Exclude test files from visualization
depwire viz ./my-project --exclude "**/*.test.*"
# Verbose mode with detailed parsing logs
depwire viz ./my-project --verbose
# Don't auto-open browser
depwire viz ./my-project --no-open
Opens an interactive arc diagram in your browser:
- Rainbow-colored arcs showing cross-file dependencies
- Hover to explore connections
- Click to filter by file
- Search by filename
- Live refresh when files change β Edit code and see the graph update in real-time
- Export as SVG or PNG
- Port collision handling β Automatically finds an available port if default is in use
How It Works
- Parser β tree-sitter extracts every symbol and reference
- Graph β graphology builds an in-memory dependency graph
- MCP β AI tools query the graph for context-aware answers
- Viz β D3.js renders the graph as an interactive arc diagram
CLI Reference
depwire parse <directory>
Parse a project and export the dependency graph as JSON.
Options:
-o, --output <path>β Output file path (default:depwire-output.json)--exclude <patterns...>β Glob patterns to exclude (e.g.,"**/*.test.*" "dist/**")--verboseβ Show detailed parsing progress (logs each file as it's parsed)--prettyβ Pretty-print JSON output with indentation--statsβ Print summary statistics (file count, symbol count, edges, timing)
Examples:
# Basic parse
depwire parse ./src
# Exclude test files and build outputs
depwire parse ./src --exclude "**/*.test.*" "**/*.spec.*" "dist/**" "build/**"
# Full verbosity with stats
depwire parse ./src --verbose --stats --pretty -o graph.json
depwire viz <directory>
Start visualization server and open arc diagram in browser.
Options:
--port <number>β Port number (default: 3456, auto-increments if in use)--exclude <patterns...>β Glob patterns to exclude--verboseβ Show detailed parsing progress--no-openβ Don't automatically open browser
Examples:
# Basic visualization
depwire viz ./src
# Custom port without auto-open
depwire viz ./src --port 8080 --no-open
# Exclude test files with verbose logging
depwire viz ./src --exclude "**/*.test.*" --verbose
depwire mcp [directory]
Start MCP server for AI tool integration (Cursor, Claude Desktop).
Examples:
# Start MCP server on current directory
depwire mcp
# Start on specific project
depwire mcp /path/to/project
depwire docs <directory>
Generate comprehensive codebase documentation from your dependency graph.
Options:
--output <path>β Output directory (default:.depwire/inside project)--format <type>β Output format:markdownorjson(default:markdown)--include <docs...>β Comma-separated list of docs to generate (default:all)- Values:
architecture,conventions,dependencies,onboarding,files,api_surface,errors,tests,history,current,status,health,all
- Values:
--updateβ Regenerate existing documentation--only <docs...>β Used with--update, regenerate only specific docs--verboseβ Show generation progress--statsβ Show generation statistics--gitignoreβ Add.depwire/to.gitignoreautomatically--no-gitignoreβ Don't modify.gitignore
Examples:
# Generate all docs (outputs to .depwire/ by default)
depwire docs ./my-project
# Show generation progress and stats
depwire docs ./my-project --verbose --stats
# Regenerate existing docs
depwire docs ./my-project --update
# Generate specific docs only
depwire docs ./my-project --include architecture,dependencies
# Custom output directory
depwire docs ./my-project --output ./docs
# Regenerate only conventions doc
depwire docs ./my-project --update --only conventions
Generated Documents (12 total):
| Document | What It Contains |
|---|---|
ARCHITECTURE.md | Module structure, entry points, hub files, layer analysis, circular dependencies |
CONVENTIONS.md | Naming patterns, import/export style, detected design patterns |
DEPENDENCIES.md | Module dependency matrix, high-impact symbols, longest dependency chains |
ONBOARDING.md | Reading order (Foundation/Core/Entry Points), module map, key concepts, high-impact file warnings |
FILES.md | Complete file catalog with stats, orphan files, hub files |
API_SURFACE.md | All exported symbols (public API), most-used exports, unused exports |
ERRORS.md | Error handling patterns, error-prone files, custom error classes |
TESTS.md | Test file inventory, test-to-source mapping, untested files |
HISTORY.md | Git history + graph analysis, file churn, feature timeline |
CURRENT.md | Complete codebase snapshot (every file, symbol, connection) |
STATUS.md | TODO/FIXME/HACK inventory with priority matrix |
HEALTH.md | Dependency health score (0-100) across 6 dimensions with recommendations |
Documents are stored in .depwire/ with metadata.json tracking generation timestamps for staleness detection.
depwire health <directory>
Analyze dependency architecture health and get a 0-100 score across 6 quality dimensions.
Options:
--jsonβ Output as JSON (for CI/automation)--verboseβ Show detailed per-dimension breakdown
Dimensions Measured:
- Coupling (25%) β How tightly connected are modules? Lower coupling = easier changes
- Cohesion (20%) β Do files in the same directory relate? Higher cohesion = better organization
- Circular Dependencies (20%) β Files depending on each other in cycles
- God Files (15%) β Files with abnormally high connection counts
- Orphan Files (10%) β Files with zero connections (dead code?)
- Dependency Depth (10%) β How deep are the dependency chains?
Examples:
# Analyze current directory
depwire health .
# Detailed breakdown
depwire health . --verbose
# JSON output for CI
depwire health . --json
Output:
- Overall score (0-100) with letter grade (A-F)
- Per-dimension scores and grades
- Actionable recommendations
- Trend indicator (β/β from last check)
Health history is stored in .depwire/health-history.json (last 50 checks).
Error Handling
Depwire gracefully handles parse errors:
- Malformed files β Skipped with warning, parsing continues
- Large files β Files over 1MB are automatically skipped
- Port collisions β Auto-increments to next available port (3456 β 3457 β 3458...)
- Protected paths β Blocks access to sensitive directories (.ssh, .aws, /etc)
Example Workflows
Refactoring with AI

# In Claude Desktop or Cursor with Depwire MCP:
"Connect to /Users/me/my-app and analyze the impact of renaming UserService to UserRepository"
# Depwire responds with:
# - All files that import UserService
# - All call sites
# - All type references
# - Suggested find-and-replace strategy
Understanding a New Codebase
"Connect to https://github.com/t3-oss/create-t3-app and give me an architecture summary"
# Depwire responds with:
# - Language breakdown
# - Module/package structure
# - Most-connected files (architectural hubs)
# - Entry points
Pre-Commit Impact Check
# Check what your changes affect before committing
depwire viz . --open
# Review the arc diagram β red arcs show files you touched
Security
Depwire is read-only β it never writes to, modifies, or executes your code.
- Parses source files with tree-sitter (the same parser used by VS Code and Zed)
- Visualization server binds to localhost only
- No data leaves your machine β everything runs locally
- Blocks access to sensitive system directories (.ssh, .aws, /etc)
- npm packages published with provenance verification
See SECURITY.md for full details.
Roadmap
- PR Impact Visualization (GitHub Action)
- Temporal Graph β watch your architecture evolve over git history
- Cross-language edge detection (API routes β frontend calls)
- Dependency health scoring
- VSCode extension
Contributing
Contributions welcome! Please note:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
- Sign the CLA (handled automatically on your first PR)
All contributors must sign the Contributor License Agreement before their PR can be merged.
Author
Atef Ataya β AI architect, author, and creator of Depwire.
- π₯ YouTube β 600K+ subscribers covering AI agents, MCP, and LLMs
- π The Architect's Playbook: 5 Pillars β Best practices for AI agent architecture
- πΌ LinkedIn
License
Depwire is licensed under the Business Source License 1.1.
- Use it freely for personal projects, internal company use, and development
- Cannot be offered as a hosted/managed service to third parties
- Converts to Apache 2.0 on February 25, 2029
For commercial licensing inquiries: atef@depwire.dev
Credits
Built by ATEF ATAYA LLC
Powered by:
- tree-sitter β Fast, reliable parsing
- graphology β Powerful graph data structure
- D3.js β Data visualization
- Model Context Protocol β AI tool integration
