https://github.com/andrearcaina/pathfinder
blazingly fast, lightweight CLI to map & track your codebase
https://github.com/andrearcaina/pathfinder
charm cli cloc go goreleaser
Last synced: 4 months ago
JSON representation
blazingly fast, lightweight CLI to map & track your codebase
- Host: GitHub
- URL: https://github.com/andrearcaina/pathfinder
- Owner: andrearcaina
- License: mit
- Created: 2025-08-15T18:43:38.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-14T19:38:34.000Z (5 months ago)
- Last Synced: 2026-01-14T22:59:13.028Z (5 months ago)
- Topics: charm, cli, cloc, go, goreleaser
- Language: Go
- Homepage: https://pkg.go.dev/github.com/andrearcaina/pathfinder/pkg/pathfinder
- Size: 528 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pathfinder
[](https://goreportcard.com/report/github.com/andrearcaina/pathfinder)
[](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-ci.yml)
[](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-cd.yml)
Blazingly fast, lightweight CLI to map & track your codebase.
### Overview
`pathfinder` is a command-line tool written in Go that scans a specified directory (and its subdirectories) to count the number of files, directories, and total lines of code.
It is designed to be fast and efficient, leveraging Go's concurrency features to process files in parallel.
It is also implemented as a Go package, so that you can use to integrate its functionality into your own Go applications/programs.
### Installation
`pathfinder` can be installed and used in two main ways:
**As a CLI Tool**
Install via cURL on Linux, WSL, or Git Bash:
```bash
curl -fsSL https://raw.githubusercontent.com/andrearcaina/pathfinder/main/install.sh | sh
```
Install via Powershell on Windows:
```bash
irm https://raw.githubusercontent.com/andrearcaina/pathfinder/main/install.ps1 | iex
```
Or via Go (requires Go 1.24.5 or later):
```bash
go install github.com/andrearcaina/pathfinder@latest
```
**As a Package**
Install via Go (requires Go 1.24.5 or later):
```bash
go get github.com/andrearcaina/pathfinder/pkg/pathfinder
````
### Documentation
For detailed documentation on how to use `pathfinder`, both as a CLI tool and as a Go library, please refer to the [docs](docs/) folder in the repository and check their respective files (`cli.md` and `api.md`). You can also check out the Godoc page [here](https://pkg.go.dev/github.com/andrearcaina/pathfinder/pkg/pathfinder). The architecture and designs is also documented in the `architecture.md` file and [designs](docs/designs) folder.
### Go Example Usage using API
Here's a simple example of how to use the `pathfinder` library in your Go code:
```go
package main
import (
"fmt"
"github.com/andrearcaina/pathfinder/pkg/pathfinder"
)
func main() {
// default config (scans current directory and non-recursively)
report, err := pathfinder.Scan(pathfinder.Config{})
if err != nil {
fmt.Printf("Failed to scan codebase: %v", err)
}
fmt.Printf("Scanned %d files in %d directories with a total of %d lines\n",
report.CodebaseMetrics.TotalFiles,
report.CodebaseMetrics.TotalDirs,
report.CodebaseMetrics.TotalLines,
)
}
```
### CLI Usage
Below I ran `pathfinder` on this codebase with the `-R` flag to recursively scan all subdirectories, as well as the `-d` flag to scan dependencies. Image was taken at 2025-12-08 7:25 PM EST.
Then I ran the same command, but instead on my installed Go libraries and packages in WSL to benchmark performance with the `-t` flag to enable throughput mode.
```bash
> pathfinder scan -p ../../../go -R -d -t
# throughput mode (as of 2025-12-10 12:51 PM EST)
Pathfinder • Throughput Mode
[Worker 0] processed 2823 files in 3.01s (937.7 files/sec)
[Worker 1] processed 2973 files in 3.01s (987.6 files/sec)
[Worker 2] processed 2845 files in 3.01s (945.1 files/sec)
[Worker 3] processed 2794 files in 3.01s (928.2 files/sec)
[Worker 4] processed 2874 files in 3.01s (954.7 files/sec)
[Worker 5] processed 2891 files in 3.03s (954.0 files/sec)
[Worker 6] processed 2813 files in 3.03s (928.0 files/sec)
[Worker 7] processed 2932 files in 3.01s (974.1 files/sec)
[Worker 8] processed 2888 files in 3.01s (958.2 files/sec)
[Worker 9] processed 2956 files in 3.01s (982.0 files/sec)
[Worker 10] processed 2952 files in 3.01s (980.7 files/sec)
[Worker 11] processed 2955 files in 3.01s (981.6 files/sec)
[Worker 12] processed 2899 files in 3.01s (963.0 files/sec)
[Worker 13] processed 2851 files in 3.01s (947.1 files/sec)
[Worker 14] processed 2946 files in 3.01s (978.7 files/sec)
[Worker 15] processed 2829 files in 3.01s (939.8 files/sec)
Total workers: 16
Total scanned files: 46,221
Total scanned dirs: 11,165
Total lines: 24,873,896
Total time taken: 3.03s
Overall throughput: 15229.7 files/sec
```
You can see that it found **46,221** files, **11,165** directories, and **24,873,896** total lines (as of 2025-12-10 12:51 PM EST).
Similarly, I ran with the `time` command to compare time taken and CPU usage (without throughput mode):
```bash
> time pathfinder scan -p ../../../go -R -d
...
pathfinder scan -p ../../../go -R -d 3.17s user 4.77s system 251% cpu 3.154 total
```
This only took 3.03-3.154 seconds (on my machine), utilizing 251% of the CPU.
This is because `pathfinder` uses goroutines for both concurrent file reading and line counting, and parallelizes work across multiple CPU cores.
I then ran it again on the same directory:
```bash
> pathfinder scan -p ../../../go -R -d -t
Pathfinder • Throughput Mode
[Worker 0] processed 2741 files in 0.61s (4516.0 files/sec)
[Worker 1] processed 2963 files in 0.61s (4892.2 files/sec)
[Worker 2] processed 2800 files in 0.63s (4475.3 files/sec)
[Worker 3] processed 2924 files in 0.61s (4820.4 files/sec)
[Worker 4] processed 2903 files in 0.61s (4754.6 files/sec)
[Worker 5] processed 2967 files in 0.62s (4808.5 files/sec)
[Worker 6] processed 2722 files in 0.63s (4342.5 files/sec)
[Worker 7] processed 3079 files in 0.61s (5083.9 files/sec)
[Worker 8] processed 2881 files in 0.61s (4736.4 files/sec)
[Worker 9] processed 3219 files in 0.62s (5206.3 files/sec)
[Worker 10] processed 2708 files in 0.62s (4380.7 files/sec)
[Worker 11] processed 2767 files in 0.61s (4525.5 files/sec)
[Worker 12] processed 2610 files in 0.63s (4147.0 files/sec)
[Worker 13] processed 2840 files in 0.61s (4668.4 files/sec)
[Worker 14] processed 3009 files in 0.62s (4851.4 files/sec)
[Worker 15] processed 3088 files in 0.62s (5010.2 files/sec)
Total workers: 16
Total scanned files: 46,221
Total scanned dirs: 11,165
Total lines: 24,873,896
Total time taken: 0.63s
Overall throughput: 73029.2 files/sec
# and
> time pathfinder scan -p ../../../go -R -d
...
pathfinder scan -p ../../../go -R -d 2.71s user 1.63s system 634% cpu 0.684 total
```
This time it took only 0.63-0.684 seconds to run, utilizing 634% of the CPU.
The second run is much faster because the OS caches file data in memory,
reducing I/O overhead and allowing goroutines to utilize more cores efficiently.
The `pathfinder` CLI also has a flag that exports the codebase metric data as a JSON file. Check out [examples/json-exports/](examples/json-exports/) directory to see example JSON reports generated.