pass-cli

Checkpoint-based pass navigation for AI coding workflows.

pass-cli lets you save lightweight snapshots for each agent pass and move backward/forward without polluting normal git history.

Current status

This is an MVP (0.1.x) with core linear/branch-safe navigation.

Open source readiness

• LICENSE (MIT)
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• GitHub CI workflow for npm run verify
• GitHub issue templates and PR template

Install

From source:

npm install
npm run build
node dist/index.js --help

Global (after publish):

npm install -g @bhadraagada/pass-cli
pass --help

Quick start

Run inside any git repository:

pass init
pass save "initial snapshot"
pass log

Commands

• pass init - initialize pass metadata in current repository
• pass save [message] - create a pass snapshot from current working tree
• pass save --overwrite [message] - when not at tip, remove future passes and continue from current
• pass log - list passes, parent links, and current pointer
• pass status - show current pass id/commit/message
• pass back - move to parent pass
• pass forward - move to next pass (errors if multiple branches exist)
• pass goto <id> - move to a specific pass id
• pass diff [from] [to] - show git diff --stat between passes
• pass clear --yes - remove current pass session metadata and refs
• pass watch [options] - auto-save snapshots while files change

Watch options

• --debounce <ms> - debounce interval for auto-save (default: 1500)
• --prefix <text> - message prefix for auto snapshots (default: auto)
• --overwrite - overwrite future passes when watching from older pass

Behavior notes

• Internal metadata is stored in .git/passes/<session-id>/.
• Hidden refs are stored in refs/passes/<session-id>/head.
• By default, if you save from an older pass, pass-cli warns and creates a new branch path.
• Overwrite requires explicit --overwrite.
• Navigation commands require a clean working tree.

Development

npm run typecheck
npm run build
npm run test
npm run verify

Release and publish

npm run pack:preview
npm run release:patch

Update repository URLs in package.json before first publish.

Also update contact placeholders in SECURITY.md and funding/repo placeholders in package.json.

Limitations (MVP)

• pass watch is filesystem based (no direct editor/agent protocol hooks yet)
• Tree log is text-only and branch navigation is currently goto by id
• Single default session only