Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

31 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AAA

Small, single-purpose, open-source tools that sit alongside AI coding agents (Claude Code, Cursor, Codex, Gemini CLI) and catch the specific, recurring failure modes they're prone to. None of them are AI tools themselves — no accounts, no backend, no billing. Each installs in one command and does exactly one thing.

Tool Category What it does
checkpoint Safety Automatic git checkpoints before your AI agent runs a bash command — the gap Claude Code's native /rewind doesn't cover
loopkill Awareness Detects when your AI agent is stuck in a loop and interrupts it before it burns your quota
ctxmeter Awareness A live context-window gauge for AI coding CLIs that don't already have one (Claude Code users: use /statusline instead)
again Awareness Counts how many times you've had to repeat yourself to your AI agent this session
permit Safety Diagnoses why a Claude Code permission rule silently doesn't apply
actually Trust Cross-checks a "tests pass" claim against the real last test run in the same session
exists Trust Checks whether a package your agent just installed (npm/PyPI) actually exists in the real registry
spare Safety Makes rm/Remove-Item recoverable — the safety net underneath every AI agent's delete command, on macOS, Linux, and Windows

See it catch something real

Not staged output — the actual released binaries, run against a real transcript, making real calls where the tool needs to (exists really asks npm's registry; actually really parses the real failing test output).

actually catches a "tests pass" claim that contradicts the last real test run:

actually catching a false "tests pass" claim in real time

exists catches a hallucinated package name before it's trusted:

exists catching a hallucinated package name in real time

spare catches a real rm and makes it recoverable:

spare catching a real rm and restoring the file in real time

Verified, not vibes

Every tool here has a "Known limitations" and "Verified against real data" section in its own README — the point of this section is to put the concrete evidence in one place instead of six, so it's not just a claim.

  • checkpoint: hardened against 8 real scenarios beyond the happy path (no commits yet, detached HEAD, 30 truly concurrent saves, corrupted log lines, symlinks/binaries) — 2 real bugs found and fixed along the way. Verified via a real brew-installed binary: brew upgrade, three full uninstall/reinstall cycles, zero leftover state.
  • loopkill: verified against a real simulated stuck process — zero false positives on a spinner, correct detection and kill on a genuine loop, not a synthetic pass/fail assertion.
  • ctxmeter: verified that piping through it never swallows the wrapped CLI's real output — the gauge renders on stderr, stdout reaches the terminal byte-for-byte unmodified.
  • again: the real Claude Code transcript shape was confirmed correct against a live session, not assumed — and its token counts are the actual measured length of a repeated prompt, deliberately never called "tokens saved," because that would require guessing a counterfactual no tool can actually know.
  • permit: cut from three commands down to one (doctor) after discovering Claude Code already had native features doing the same job. Shipping less, on purpose, once redundant work was found, rather than keeping code around because it existed.
  • actually: swept against ~500 real assistant messages from this project's own development session — 0 false positives after fixing 3 real bugs found along the way, including a silent-data-loss bug where one oversized transcript line could drop detection for the rest of a session with zero error output.
  • exists: its test suite makes live calls to the real npm and PyPI registries rather than mocking them, because the entire point is whether the real registry agrees. A pre-release audit found its own pitch had quietly oversold what it protects against (it can't catch a package name that's already been squatted, only one that's still unclaimed) — the README was rewritten to say so plainly rather than leave the stronger, less accurate claim standing.
  • spare: built from four real, severe, publicly filed incidents (a custom OS with 78+ verified build iterations destroyed, 160+ hours of work lost, an entire ~/Desktop including installed applications gone) — none of which checkpoint would have caught, since git stash structurally cannot capture untracked files. Its own CI actually executes the built binary on real windows-latest, macos-latest, and ubuntu-latest GitHub Actions runners on every push, catching a real Windows-specific bug (%USERPROFILE% vs $HOME) that cross- compiling alone — the only verification every other tool here has ever had for its Windows/Linux binaries — would never have surfaced.

Why separate tools instead of one platform

Each one is a narrow fix for a single, specific, well-evidenced annoyance — in the spirit of tools like fzf, ripgrep, and atuin, not a bundled suite you have to buy into all at once. Use one, use all eight, doesn't matter — none of them depend on each other.

Install

Each tool has its own README with full details. The short version, once releases exist (see each tool's docs/RELEASING.md):

go install github.com/Soldsoul86/AAA/checkpoint@latest
go install github.com/Soldsoul86/AAA/loopkill@latest
go install github.com/Soldsoul86/AAA/ctxmeter@latest
go install github.com/Soldsoul86/AAA/again@latest
go install github.com/Soldsoul86/AAA/permit@latest
go install github.com/Soldsoul86/AAA/actually@latest
go install github.com/Soldsoul86/AAA/exists@latest
go install github.com/Soldsoul86/AAA/spare@latest

Or build from source today, before any release exists:

git clone https://github.com/Soldsoul86/AAA
cd AAA/checkpoint && go build -o checkpoint .

Structure

This is a monorepo — one repo, independent Go modules, one folder each. Every tool has its own go.mod, its own tests, its own .goreleaser.yaml, and its own release workflow (.github/workflows/release-<tool>.yml), triggered only by that tool's own tag prefix (e.g. checkpoint-v0.1.0) so releasing one tool never touches the others.

License

MIT, per tool (see each folder's LICENSE).

About

Small, single-purpose, open-source tools that catch the recurring failure modes of AI coding agents (Claude Code, Cursor, Codex, Gemini CLI) — no accounts, no backend, no billing.

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages