xtree-ai

Version 0.1.0

UML-driven code comprehension engine for Vibe Coders and developers working with agent-generated codebases.

XTree turns your JavaScript and TypeScript codebases into live UML-style diagrams and explains every function, class, and execution path using a local LLM (qwen2.5-coder:3b via Ollama). Your code never leaves your computer.

Quickstart

Run directly against your project without installing:

bunx xtree-ai start .

Or install globally to use the xtree CLI command anywhere:

bun add -g xtree-ai
xtree .

Prerequisite: Bun 1.3.0 or higher must be installed on your system.

Introduction

Developers working with AI coding agents receive large volumes of generated code they did not write. Reading it file by file is slow, and tracing dependencies across modules is mentally taxing. Existing UML tools draw static boxes without providing semantic context, while cloud explainers send your proprietary code to third parties and charge per token on every save.

XTree enforces a strict core principle: the parser draws, the LLM explains.

• Static analysis is the source of truth for structure. Nodes, edges, types, and calls are extracted deterministically with the TypeScript Compiler API. The LLM never invents graph edges.
• The local LLM provides meaning. Card summaries, the execution flow walkthrough, and grounded chat answers are generated by a local model running on your GPU via Ollama. If Ollama is offline, the diagram and static analysis still work 100%.

Features

Deterministic Static Analysis & Symbol Extraction

• Traces relative imports up to depth 2 (configurable) from any selected entry file.
• Extracts functions, arrow functions, classes (constructors, fields, methods, public / private / protected / #private), interfaces, type aliases, and enums.
• Maps relationship edges: calls (numbered in sequential execution order), contains, uses-type, extends, implements, and imports.
• First-class support for JSX elements, React.memo, forwardRef, and CommonJS modules.
• Unresolved external references are rendered as stubs without guessing internal project connections.

Dual-Engine Canvas Visualization

• UML Diagram: Interactive SVG UML class diagrams with hierarchical layout, auto-connecting ports, and clean orthogonal routing.
• Radial Relationship Graph: Topological bird's-eye view of file clusters and symbol dependencies.
• Interactive controls: zoom, pan, fit-to-screen, search filter, and onboarding tour.

Local AI Explanations & Grounded Chat

• Streamed function and class summaries via Ollama (qwen2.5-coder:3b), prioritized breadth-first along call chains.
• Cached on disk in .xtree/cache.json by sha256(source + model + prompt_version) so unchanged code is never re-summarized.
• Explain Flow: Step-by-step walkthroughs combining deterministic call-graph sequencing with model-written narrative.
• Grounded Chat: Code question drawer grounded strictly in pinned symbols and immediate neighbors, preventing hallucinations and keeping prompt tokens under 6k.

Live File Watching & Incremental Updates

• Chokidar file watcher honoring .gitignore rules with debounced batching.
• WebSocket-driven incremental diffs (graph.diff) updating nodes and edges in real time without refreshing the page.
• Visual change indicators highlighting modified cards with badges that automatically fade after 10 seconds.
• Syntax-error resilience: keeps the last valid AST state if an in-progress edit temporarily breaks parsing.

CLI Options

Usage: xtree [options] [command]

Commands:
  start [options] [path]  analyze a project and open the visualizer (default command)
  help [command]          display help for command

Options:
  -v, --version           output the version number
  -p, --port <number>     preferred HTTP / WebSocket port (default: 4317)
  -d, --depth <number>    import traversal depth (default: 2)
  -m, --model <name>      Ollama model name (default: qwen2.5-coder:3b)
  --ollama <url>          Ollama API host (default: http://127.0.0.1:11434)
  --no-open               do not open the default browser on start
  --force                 start even if the directory does not look like a JS/TS project
  --max-files <number>    maximum supported files to scan (default: 5000)
  -h, --help              display help for command

Configuration File

You can configure persistent defaults in an xtree.config.json file in your project root:

{
  "port": 4317,
  "depth": 2,
  "model": "qwen2.5-coder:3b",
  "maxFiles": 5000
}

Configuration precedence: CLI flags > environment variables (XTREE_MODEL, OLLAMA_HOST) > xtree.config.json > built-in defaults.

Architecture

XTree is structured as a Bun monorepo comprising a backend engine, single-port HTTP/WebSocket server, and a React web application.

Technology Stack

• Runtime: Bun 1.4.2
• Compiler API: TypeScript 6.0.3 (typescript), Chokidar 5, Commander 15
• Frontend: React 19, Motion (motion/react), Zustand 5, Lucide Icons, Vite
• Local AI: Ollama (qwen2.5-coder:3b)

Data Flow

1. Scanner: Recursively indexes supported files (.js, .jsx, .ts, .tsx) honoring .gitignore and skipping node_modules and build directories.
2. Analyzer: Constructs the AST program from the selected entry file using TypeScript Compiler API, extracting symbols and directed edges.
3. Session & Server: Hosts the REST API, serves the web SPA, watches files, and broadcasts diffs over WebSocket.
4. LLM Engine: Manages a single-job priority queue communicating with the local Ollama instance, streaming responses and persisting cache entries.
5. Web Canvas: Renders interactive UML and radial graphs, handling zoom, selection cards, flow walkthroughs, and chat.

Getting Started from Source

Prerequisites

• Bun 1.3.0 or higher
• Ollama with qwen2.5-coder:3b pulled (optional, for AI summaries)

ollama pull qwen2.5-coder:3b

Installation & Build

git clone https://github.com/shimijallores/xtree.git
cd xtree
bun install
bun run build

Running Locally

# Analyze the included shop-app example
bun bin/xtree.js start examples/shop-app

# Or start in hot-reload development mode
bun run dev

Tests

bun run test        # Runs 56 backend tests
bun run typecheck   # Typecheck both workspaces

License

MIT License

Copyright (c) 2026 XTree contributors.