Getting started

Install

gsttt is a single binary. The install script picks the package for your system, checks its SHA-256 and puts the binary in ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/SkuratovichA/gsttt/main/install.sh | sh

It supports Linux (musl) and macOS, on x86_64 and aarch64. Set GSTTT_INSTALL_DIR to install somewhere else and GSTTT_VERSION to pin a version. When the install directory is not on your PATH, the script prints the export PATH line to add.

The Claude Code plugin

In Claude Code, add the marketplace and install the plugin. It registers the MCP server gsttt mcp, a session start hook and a skill.

/plugin marketplace add SkuratovichA/gsttt

/plugin install gsttt@gsttt

The plugin does not install the binary. It looks for gsttt on your PATH and then in the install directory, and when it finds neither, the session start prints the install command.

Build the index

Run gsttt index at the root of a repository. The first run parses every file and later runs parse only what changed:

gsttt indexIndexed 4,213 files at a1b2c3d (3 dirty) in 1.24 s: 112 parsed, 4,101 reused.

On an unchanged tree it answers The index already describes the tree: 4,213 files at a1b2c3d.

You do not have to run it before asking a question. Every command refreshes the index first, so gsttt index is for warming the index and for seeing the numbers. Pass --no-refresh to answer from the index as it is.

The index lives in the git directory, under gsttt/, and outside a git repository under $XDG_CACHE_HOME/gsttt/. gsttt refuses to index your home directory or /.

Ask what a change touches

Name a file and ask what depends on it:

gsttt impact api/bookings/router.pyaffected files (4)  1  web/src/api/bookings.ts      calls http GET /bookings/{}  2  web/src/pages/Bookings.tsx   imports web/src/api/bookings.ts  2  web/src/pages/Dashboard.tsx  imports web/src/api/bookings.ts  3  web/src/App.tsx              imports web/src/pages/Bookings.tsxtests (1)  1  api/tests/test_bookings.py   imports api/bookings/router.pypython: 212 of 214 files read, 99% of imports resolved. ts: 340 of 340 files read, 100% of imports resolved.fresh at a1b2c3d, 3 files dirty

Each line is a file that depends on the one you named. The number is its distance: 1 for a direct dependent, 2 for the dependents of those, and so on. After the path comes the first reason gsttt found, an import or a contract that the file serves or calls. Tests are listed in a group of their own.

A list is cut after 30 lines with a … N more line. --all lifts the cut and --json prints the full answer as JSON.

Options

--changed

Ask about the files you changed instead of naming files. Add --base REV to compare with a revision.

--depth N

Stop after N steps from the file.

--all

Print every line instead of cutting the lists.

--json

Print the full answer as JSON.

-C DIR

Run as if started in DIR.

--no-refresh

Answer from the index as it is, without refreshing it first.

The same index answers dependents, dependencies, path, contract, coverage and status.

Read the last two lines

Every answer ends with two lines that say how far to trust it.

Coverage

python: 212 of 214 files read, 99% of imports resolved

How much of the code gsttt could read. The line above is an example, and the figures depend on your repository. A low figure means the graph may be missing edges, and the answer says so instead of staying quiet.

Freshness

fresh at a1b2c3d, 3 files dirty

The index describes the tree at commit a1b2c3d, and 3 files in the working tree differ from that commit.

stale: 2 files changed since the index

When the answer comes from an index older than the tree, for example under --no-refresh, the line says how many files changed since.

Configure with gsttt init

Run gsttt init to write a starter configuration.

It writes .gsttt/init.lua, a starter that names the modules it detected, and .gsttt/.luarc.json if it is missing. It always rewrites .gsttt/types/gsttt.lua, the type annotations your Lua language server reads.

The configuration is Lua, in the style of a Neovim config:

local g = require("gsttt")

g.setup {
  exclude = { "fixtures/**" },
  http_prefixes = { "/api" },
}

g.ts { tsconfig = "tsconfig.base.json" }
g.disable "openapi"

Run gsttt config check to validate it and gsttt config show to print what gsttt reads from it.