tree-climber

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 72 Open GitHub ↗

Program analysis tools built on tree-sitter (https://github.com/tree-sitter/tree-sitter).

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# tree-climber

Tree Climber is a comprehensive static analysis framework for generating Control Flow Graphs (CFGs) and performing dataflow analysis on source code. It supports multiple programming languages through Tree-sitter parsers and provides both programmatic APIs and interactive web visualization.

## Goals

- Clean architecture and thorough test coverage.
- Semi- (and eventually fully-)automated analyses written by coding agents.
- Interactive, detailed, high-quality visualizations for educational and exploration purposes.

## Supported Languages

- **C**: Full CFG generation with control structures, loops, and functions
- **Java**: CFG generation for Java language constructs
- **Extensible**: Framework designed to easily add new language support

## Architecture

### Core Components

- **CFG Builder**: Generates control flow graphs using visitor pattern
- **Dataflow Solver**: Implements iterative dataflow analysis algorithms
- **AST Utils**: Tree-sitter integration and AST manipulation utilities
- **Visualization**: Web-based interactive CFG visualization

### Analysis Capabilities

- **Control Flow Analysis**: Statement-level CFG construction
- **Def-Use Chains**: Variable definition and usage tracking
- **Reaching Definitions**: Forward dataflow propagation
- **Extensible Framework**: Support for custom dataflow analyses

## Installation

This project uses `uv` for Python dependency management and `bun` for frontend dependencies.

### Prerequisites

- Python 3.12
- [uv](https://github.com/astral-sh/uv) package manager
- [bun](https://bun.sh/) for frontend dependencies

### Setup

1. Clone the repository:
```bash
git clone https://github.com/bstee615/tree-climber
cd tree-climber
```

2. Install dependencies:
```bash
# Install dependencies on Ubuntu
sudo apt install -y graphviz graphviz-dev
uv sync
```

3. (For web frontend) Install frontend dependencies:
```bash
cd src/tree_climber/viz/frontend
bun install
```

4. (For CLI) Install CLI dependencies:
```bash
source .venv/bin/activate
uv pip install -e .
```

## Usage

### CLI

CLI is available as a command, `tree-climber`. Run the CLI against a file or directory. Use the flags below to pick which graphs to generate and how to render them.

Example:

```bash
tree-climber test/example.c --draw_cfg --draw_cpg
```

Example CFG | Example CPG (Code Property Graph, including AST + CFG + DFG edges)
-- | --
![Example CFG](https://raw.githubusercontent.com/bstee615/tree-climber/master/test/example.c_cfg.png) | ![Example CPG](https://raw.githubusercontent.com/bstee615/tree-climber/master/test/example.c_cpg.png)

An alternative view of the CPG is available which draws the AST and CFG separately, with edges connecting CFG <-> AST nodes. Use the option `-L bigraph`.

Example bigraph CPG
--
![Example bigraph CPG](https://raw.githubusercontent.com/bstee615/tree-climber/master/test/example.c_cpg_bigraph.png)

Try `tree-climber --help` to see all options.

### Web Application

The project includes a webapp for visualizing and interacting with CFG/DFGs, inspired by https://godbolt.org.
To run it easily, open the project in VSCode and launch the config named "Run Server and Frontend".

#### Start the Backend Server

```bash
# Run FastAPI server with hot reload
uv run -m uvicorn tree_climber.viz.app:app --reload --host 0.0.0.0 --port 8000

# Or use the VS Code task: "Run FastAPI Server"
```

#### Start the Frontend

```bash
# Navigate to frontend directory
cd src/tree_climber/viz/frontend

# Start development server
bun dev

# Or use the VS Code task: "Run Frontend"
```

#### Access the Application Locally

- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:8000
- **API Documentation**: http://localhost:8000/docs

#### API Endpoints

The FastAPI backend provides the following endpoints:

- `POST /parse` - Parse source code and return CFG in JSON format
- `POST /analyze/def-use` - Perform def-use chain analysis
- `POST /analyze/reaching-definitions` - Perform reaching definitions analysis
- `GET /health` - Health check endpoint

## Limitations

Currently, only basic program constructs are supported. I am working to make the parsing more robust and complete.

See the full list of features handled and planned in the [Limitations section of this doc](./docs/plans/extending-languages.md).

## Development

### Adding New Languages

1. Create a new visitor class in `src/tree_climber/cfg/languages/`
2. Implement language-specific CFG construction logic
3. Register the language in the CFG builder
4. Add test cases in the `test/` directory

### Adding New Analyses

1. Create a new analysis class in `src/tree_climber/dataflow/analyses/`
2. Implement the dataflow problem interface
3. Add API endpoints in `src/tree_climber/viz/app.py`
4. Update frontend to display analysis results

### Frontend Development

The frontend is built with:
- **React**: UI framework
- **Cytoscape.js**: Graph visualization
- **Monaco Editor**: Code editing
- **Vite**: Build tool and dev server

### Backend Development

The backend uses:
- **FastAPI**: Web framework
- **Tree-sitter**: Source code parsing
- **Pydantic**: Data validation

### CLI Development

The CLI uses:
- **Typer**: Terminal display and argument parsing
- **GraphViz**: Graph visualization

## Documentation

For detailed technical documentation, see the `docs/` directory:

tree-climber

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README