Alpheus
Scan new changes for debug output, disabled checks, commented-out code and temporary files.
Alpheus takes its name from the river associated with the cleaning of the Augean stables in Greek mythology.
- TypeScript
- Bun
- Ink
- Claude Code
- hooks
GitHub (opens in a new tab)README (opens in a new tab)Changelog (opens in a new tab)
On this pageCheck new changes
Check new changes
Alpheus scans additions in your git working tree for code and files that may need cleanup before committing: debug output, suppression directives such as // @ts-ignore, commented-out code, hardcoded home-directory paths and temporary files such as temp.json.
During a bug fix across several files, temporary diagnostics can remain after the tests pass. git commit -am includes those changes along with the fix. A diff shows which lines were added; you still need to decide which additions belong in the finished change.
The scan checks additions in staged and unstaged diffs, plus untracked files that match scratch-file patterns. Existing code is outside the scan: a console.log unchanged by the current diff is left alone.
Detection uses deterministic language patterns, comment classification and a language map keyed by file extension. It requires no model, tokens or network requests. The same working tree produces the same findings.
Five finding classes
| Class | What is detected |
|---|---|
LOG | Debug output added to watch execution: console.log/debug/dir/time, Python print, breakpoint, pdb.set_trace, logging.debug, Rust dbg! and println!, Go fmt.Print* and log.Print*, PHP var_dump, print_r, dd, shell set -x and echo "DEBUG:..." |
SUPPRESS | Suppressed checks: @ts-ignore, @ts-expect-error, @ts-nocheck, eslint-disable, biome-ignore, prettier-ignore, # noqa, # type: ignore, #[allow(...)], //nolint, @phpstan-ignore, @psalm-suppress |
TOMBSTONE | Three or more consecutive commented-out lines that still read as code |
PATH | A hardcoded home directory: /home/<user>/, /Users/<user>/, C:\Users\<user>\ |
SCRATCH | An untracked leftover: *.tmp, *.scratch and *.bak anywhere, plus temp.*, scratch.*, dump.json, debug.log and throwaway scripts like t.py at the repository root or under scratch/ and tmp/ |
The extension map covers TypeScript, JavaScript, Python, Rust, Go, PHP and shell. Files in other languages are still checked for hardcoded workstation paths and commented-out code, since those checks do not require a language-specific parser.
Review and remove findings
Run alpheus without arguments to open the terminal interface. Findings appear on the left; the surrounding source and proposed removal appear on the right. Use ↑/↓ or j/k to move, space to toggle one finding, a to toggle all findings, and enter to remove the selection. Press q or escape to exit without changing files.
For CI, git hooks or scripts, alpheus check exits with status 1 when findings are present. --json returns the findings as structured data. alpheus clean removes all findings; --dry-run previews those removals without changing files.
Backups and restore
Before removal, Alpheus copies every affected file to .alpheus/backups/<timestamp>_<id>/. The accompanying manifest.json records the sha256 of each original file. alpheus restore restores the files byte for byte, including deleted scratch files. alpheus backups lists available backups.
.alpheus/ is added to .git/info/exclude, keeping backups out of git status and commits without changing the shared .gitignore. Removals are applied from the bottom of each file upwards so that one removal does not shift the line numbers of remaining findings.
Claude Code integration
The /alpheus plugin command runs the scan and supplies findings to Claude Code for presentation. A PreToolUse hook checks Bash calls for git commit. If findings remain, the hook lists the first five before the commit runs.
The hook does not block the commit. Its output appears in your transcript rather than the model context, as a warning for you to review.
Quick start
Requires Bun 1.1 or newer and git 2.25 or newer.
claude plugin marketplace add https://github.com/AraneaDev/aranea-marketplace
claude plugin install alpheus@araneaHooks register at session start. Start a new session after installing.
The CLI can also run independently of Claude Code:
bun install -g github:AraneaDev/alpheusScope and limitations
Findings are cleanup candidates. Rust's println! and Python's print can produce required program output as well as temporary diagnostics; Alpheus flags both. Review each candidate before removal.
Alpheus changes working-tree files but does not stage or commit them. The scan makes no network requests, sends no telemetry and calls no model. All input comes from local files.
Alpheus is pre-release. Check the releases page for available versions. The finding format may still change.