stacklit

# Stacklit

**108,000 lines of code. 4,000 tokens of index.**

One command makes any repo AI-agent-ready. No server, no setup.

[![CI](https://github.com/glincker/stacklit/actions/workflows/ci.yml/badge.svg)](https://github.com/glincker/stacklit/actions)
[![Release](https://img.shields.io/github/v/release/glincker/stacklit)](https://github.com/glincker/stacklit/releases)
[![npm](https://img.shields.io/npm/v/stacklit)](https://www.npmjs.com/package/stacklit)
[![License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)

## Install and run

```bash
npx stacklit init
```

That is it. Downloads the binary, scans your codebase, generates the index, opens the visual map. One command.

Other install options:

```bash
npm install -g stacklit              # install globally, then run: stacklit init
go install github.com/glincker/stacklit/cmd/stacklit@latest
```

Or grab a binary from [GitHub Releases](https://github.com/glincker/stacklit/releases) (macOS, Linux, Windows).

## CI / GitHub Action

Use [glincker/stacklit-action](https://github.com/glincker/stacklit-action) to keep the index fresh automatically. Auto-commit on push, or gate PRs with check mode:

```yaml
- uses: actions/checkout@v4
- uses: glincker/stacklit-action@v1        # auto-commit (default)
# or: with: { mode: check }               # fail PR if index is stale
```

Add `permissions: contents: write` to the job when using `auto-commit` mode.

![Stacklit demo](demo.gif)

## What happens when you run it

```
$ stacklit init
[stacklit] found 342 files
[stacklit] parsed 342 files (0 errors)
[stacklit] done in 89ms -- wrote stacklit.json, DEPENDENCIES.md, stacklit.html

Opening visual map...
```

Three files appear in your project:

| File | What it is | Commit it? |
|------|-----------|------------|
| `stacklit.json` | Codebase index for AI agents | **Yes** |
| `DEPENDENCIES.md` | Mermaid dependency diagram | **Yes** (renders on GitHub) |
| `stacklit.html` | Interactive visual