Git-commit–aware symbol lookup & impact analysis engine
In Pluk, a symbol is any named entity in your codebase that can be referenced, defined, or impacted by changes. This includes functions, classes, methods, variables, and other identifiers that appear in your source code. Pluk tracks symbols across commits and repositories to enable powerful queries like "go to definition", "find all references", and "impact analysis".
Pluk gives developers “go-to-definition”, “find-all-references”, and “blast-radius” impact queries across one or more Git repositories. Heavy lifting (indexing, querying, storage) runs in Docker containers; a lightweight host shim (pluk) boots the stack and delegates commands into a thin CLI container (plukd) that talks to an internal API.
- Search: classes, functions, and other symbols in your repo
- Define: list metadata about a specific symbol
- Impact: find references and usage contexts of a symbol
- Diff: compare definitions and references between commits
- Indexing: via universal-ctags and tree-sitter (one branch at a time)
- Containerized: runs with Docker Compose, no host setup needed
- Language support: Python, JavaScript, TypeScript, Go, Java, C, C++
- Docker and Docker Compose
- Git repositories must be public or cloneable from inside the container
- Supported OS: Linux, macOS, Windows (with Docker Desktop)
pip install plukpluk start # launch services
pluk status # check if services are running
pluk cleanup # stop services
pluk init /path/to/repo # queue full index of a repository
pluk search MyClass # symbol lookup; symbol matches branch-wide
pluk define my_function # show symbol definition
pluk impact computeFoo # list symbol references with context
pluk diff symbol SHA-1 SHA-2 # show symbol changes between commit SHAs SHA-1 → SHA-2Start the Pluk services:
> pluk start
Pulling latest Docker images...
Starting Pluk services...
[+] Running 5/5
✔ Container pluk-redis-1 Healthy 7.5s
✔ Container pluk-postgres-1 Healthy 7.5s
✔ Container pluk-api-1 Started 7.0s
✔ Container pluk-worker-1 Started 8.0s
✔ Container pluk-cli-1 Started 7.4s
Pluk services are now running.
Initialize a repository:
> pluk init .
Initializing repository at .
[+] Repository initialized successfully.
Current repository:
URL: https://github.com/jorstors/pluk-diff-sample
Commit SHA: dd36847d0f55c5af6e70ee920837c782d09edbc2
Search for a symbol:
> pluk search find
Searching for symbol: find @ https://github.com/jorstors/pluk-diff-sample:dd36847d0f55c5af6e70ee920837c782d09edbc2
Found symbol: find_refs
Located at: src/app.py:1Define a symbol:
> pluk define find_refs
Defining symbol: find_refs
Symbol: find_refs
Location: src/app.py:1-3
Kind: function
Language: Python
Signature: (x)
Scope: global (unknown)Check symbol impact:
> pluk impact find_refs
Analyzing impact of symbol: find_refs
References found:
other (function_definition) in src/app.py:13Diff a symbol across commits:
> pluk diff find_refs caa599294066de31f01305a781ca8ff0bbe06aba dd36847d0f55c5af6e70ee920837c782d09edbc2
Showing differences for symbol: find_refs
From commit: caa599294066de31f01305a781ca8ff0bbe06aba
To commit: dd36847d0f55c5af6e70ee920837c782d09edbc2
Differences found:
Definition:
* file: No change
* line: No change
* end_line:
- From: 2
- To: 3
* name: No change
* kind: No change
* language: No change
* signature: No change
* scope: No change
* scope_kind: No change
New references:
* other (function_definition) in src/app.py:13
Removed references:
* use (function_definition) in src/app.py:6If you want a full teardown (remove containers/network), use:
docker compose -f ~/.pluk/docker-compose.yml down -vHow it works
- Host shim (
pluk) writes the Compose file, pulls images, and runsdocker compose up. - CLI container (
plukd) is the exec target; it calls the API athttp://api:8000. - API (FastAPI) serves read endpoints (
/search,/define,/impact,/diff) and enqueues write jobs (/reindex) to Redis. - Worker (Celery) consumes jobs from Redis, clones/pulls repos into a volume (
/var/pluk/repos), parses it, and writes to Postgres.
pytestMIT License