CI and troubleshooting

CI/CD

GitHub Action

glincker/stacklit-action keeps the index fresh:

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

Give the job permissions: contents: write in auto-commit mode.

Hand-written workflow

name: Update stacklit index
on:
  push:
    branches: [main]
    paths-ignore: ['stacklit.json', 'DEPENDENCIES.md', '**.md']

jobs:
  stacklit:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.25'
      - run: go install github.com/glincker/stacklit/cmd/stacklit@latest
      - run: stacklit generate --quiet
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update stacklit index"
          file_pattern: "stacklit.json DEPENDENCIES.md"

Git hook

stacklit init --hook     # or: stacklit setup

Runs stacklit generate --quiet after each commit and stages the two committed outputs for the next commit.

Troubleshooting

The session hook does not fire, the index looks stale, or two sessions collide: see the troubleshooting section of docs/SESSIONS.md. Quick checks: /hooks in Claude Code, echo '{"source":"startup","cwd":"'$PWD'"}' | stacklit hook session, stacklit status, and stacklit refresh --files <paths>.

could not read stacklit.json: run stacklit init or stacklit generate first, and run the command from the repo root.

A symbol is missing from the index: exports are capped per module. Raise max_exports in .stacklitrc.json and regenerate. Unexported (private) symbols are never listed.

A dependency looks wrong: the graph comes from import statements resolved to modules. Test files and relative imports can produce extra or missing edges. Confirm with a read, and open an issue with a minimal example.

Generation is slow or uses a lot of memory on Python or TypeScript: this is a known cost of the pure-Go tree-sitter parsers. Add large generated or vendored directories to ignore.

Windows install problems: use go install, or download the binary from Releases and put it on your PATH.

Generated from docs/USAGE.md in the repository, the single source of truth.