pyslick v2.0 — by Rence

 ██████╗ ██╗   ██╗███████╗██╗     ██╗ ██████╗██╗  ██╗
 ██╔══██╗╚██╗ ██╔╝██╔════╝██║     ██║██╔════╝██║ ██╔╝
 ██████╔╝ ╚████╔╝ ███████╗██║     ██║██║     █████╔╝
 ██╔═══╝   ╚██╔╝  ╚════██║██║     ██║██║     ██╔═██╗
 ██║        ██║   ███████║███████╗██║╚██████╗██║  ██╗
 ╚═╝        ╚═╝   ╚══════╝╚══════╝╚═╝ ╚═════╝╚═╝  ╚═╝

What is pyslick?

pyslick is a local CLI tool that lets you navigate, inspect, and safely patch codebases using plain English — without sending your code to any AI API.

You ask it a question like:

pyslick query "what renders the mic button"

And it zeroes in on the right function, its callers, its callees, and the exact file and line range — in under a second, even on a slow machine.

It's built for developers who want the speed of a fuzzy search with the precision of an AST call-graph, wrapped in PowerShell-friendly commands that feel native on Windows.

Features

Installation

Windows (recommended — double-click)

1. Download and unzip the release
2. Open the unzipped folder in Explorer
3. Navigate into pyslick_pkg\
4. Double-click install.bat

That's it. The installer registers pyslick on your PATH and confirms the setup.

Manual (PowerShell / macOS / Linux)

# Navigate to the inner package folder (the one with pyproject.toml)
cd pyslick_pkg\pyslick_pkg

# Install globally (editable mode — changes apply immediately)
pip install -e .

Requirements: Python 3.10+ with pip. No other setup needed.

To reinstall after pulling updates:

pip install -e . --force-reinstall --no-deps

Optional: TSX / tree-sitter support

pip install -e ".[tsx]"

Quick start

Run all commands from your project root (the folder that contains your source files).

# Find what's relevant to your question — no full-codebase scan
pyslick query "what handles the login button click"

# List all files recursively
pyslick ls
pyslick ls --full-path

# View a file with line numbers
pyslick lines src/app/page.tsx

# Search across a file for multiple terms
pyslick grep index.html "addEventListener" "electronAPI" --context 2

# Inspect a file before touching it
pyslick patchit src/app/page.tsx -l

# Safe find-and-replace (backs up, validates, diffs)
pyslick patchit src/app/page.tsx -f
# → prompts: Find: / Replace:

# Guided patch session (the interactive flow)
pyslick recon "the mic button needs to be bigger"

How query works

No LLM. No API calls. No reading your whole repo.

1. Fuzzy match your sentence against filenames and paths using rapidfuzz
2. Narrow to 2–3 candidate files (not the whole project)
3. AST call-graph walk on those files — finds the matched function plus its direct callers and callees (configurable depth)
4. Prints a compact report: file, function, line range, docstring, what it calls, what calls it

If you've already run graphify extract . in your project, query uses your existing graph nodes for an even sharper hit.

Flags:

pyslick query "..." --top-files 3     # how many candidate files to consider
pyslick query "..." --top-symbols 5   # how many matched symbols to report
pyslick query "..." --depth 3         # call-graph walk depth
pyslick query "..." --full            # also dump matched source lines
pyslick query "..." --root ./src      # project root if not running from there

How patchit works safely

Previous code patchers were dangerous — a misfire could wipe a file. pyslick fixes that:

Smoke testing

Run after any change to pyslick itself to make sure nothing broke:

cd pyslick_pkg\pyslick_pkg
python smoke.py              # full suite (6 phases)
python smoke.py --only static    # syntax + imports + API surface only
python smoke.py --only unit      # command-level tests against a fake project
python smoke.py --only build     # pnpm build + dev boot + ESLint (Next.js/Vite projects)
python smoke.py --fix            # on failure, asks Claude API for a suggested fix
python smoke.py --watch          # re-runs automatically when any .py file changes

Debugging

Wrap any command to get a structured crash report instead of a raw traceback:

python debugger.py query "make the mic button bigger"
python debugger.py patchit src/app/page.tsx -l
python debugger.py --wrap-cmd "pnpm build"
python debugger.py --scan-log build.txt
python debugger.py --fix <any of the above>

The debugger covers 13 common crashes (missing rapidfuzz, missing graph.json, ANSI encoding on Windows, EADDRINUSE, TypeScript errors, etc.) and gives you the fix without the API for the most common ones.

Project structure

pyslick_pkg/
└── pyslick_pkg/
    ├── install.bat              ← Windows one-click installer
    ├── pyproject.toml
    ├── smoke.py                 ← test suite
    ├── debugger.py              ← crash catcher
    └── pyslick/
        ├── __main__.py          ← CLI entry point
        ├── __init__.py
        ├── query.py             ← fuzzy match + AST call-graph
        ├── patchit.py           ← safe find/replace + validation
        ├── recon.py             ← guided patch session
        ├── graphify.py          ← Python AST call-graph extractor
        ├── graphify_sitter.py   ← tree-sitter graph (JS/TS/JSX)
        ├── webdesign.py         ← HTML ↔ CSS ↔ JS cross-file linker
        ├── find_nearest_nodes.py
        ├── find_stray_symbols.py
        ├── indentation.py
        ├── jsx_tag_checker.py
        ├── llm.py               ← optional SmolLM2 hook (drop-in)
        └── toolbox.py

Optional: local LLM assist

pyslick works 100% offline with no LLM. But if you want smarter query rewriting, you can drop in a local model:

1. Download SmolLM2-135M-Instruct Q4 GGUF (~90MB)
2. Place it in pyslick/models/smollm2-135m-instruct-q4.gguf
3. pip install llama-cpp-python

The LLM is used only to reword your query before fuzzy matching — everything else stays local and deterministic.

Roadmap

• pyslick backups --prune (age-based backup cleanup)
• Design-aware query (CSS variable tracing, Tailwind class lookup)
• User-annotated graph nodes via Markdown (describe your own nodes, pyslick learns them)
• pyslick diff — compare two checkpoints side by side
• VS Code extension

License

MIT — do what you want, keep the credit.