ClipCase

ClipCase is a local-first TypeScript CLI for turning copied context, terminal output, prompts, URLs, and repro notes into tidy Markdown casefiles. It never syncs or phones home; storage is transparent, deterministic, and git-friendly.

Quick start

ClipCase is not published to the npm registry yet. Until it is, build and install the package tarball from a clean checkout:

git clone https://github.com/rogerchappel/clipcase.git
cd clipcase
npm ci
npm run build
CLIPCASE_TMP="$(mktemp -d)"
CLIPCASE_TARBALL="$(npm pack --pack-destination "$CLIPCASE_TMP")"
npm install --global --prefix "$CLIPCASE_TMP/install" "$CLIPCASE_TMP/$CLIPCASE_TARBALL"
export PATH="$CLIPCASE_TMP/install/bin:$PATH"

clipcase init
clipcase new bug-login --title "Login redirect bug"
pbpaste | clipcase add bug-login --source terminal --tag repro
clipcase list
clipcase search redirect
clipcase export bug-login --out case.md

Linux and Windows users can pipe text on stdin. --clipboard uses pbpaste, xclip, or PowerShell when available and fails safely when the platform clipboard cannot be read.

Commands

• clipcase init [--storage <path>] creates .clipcase.json and the storage directory.
• clipcase new <case> [--title <title>] creates a slugged case directory.
• clipcase add <case> [--source <label>] [--tag <tag>] [--clipboard] [--allow-secret] stores stdin or clipboard text. Repeat --tag or pass comma-separated tags.
• clipcase list [--json] prints case name, entry count, updated timestamp, and title.
• clipcase show <case> prints deterministic JSON metadata.
• clipcase search <query> [--json] searches entry text, tags, and source labels offline.
• clipcase export <case> [--out <file>] produces a single Markdown bundle. Without --out it writes the bundle to stdout; with --out it creates missing parent directories and writes the file.

Case identifiers are trimmed and lowercased; runs of characters outside a-z, 0-9, ., _, and - become -, and leading or trailing - characters are removed. The result must contain at least one allowed character: identifiers such as Bug Login become bug-login, while punctuation-only identifiers such as !!! are rejected instead of being mapped to another case.

Storage format

By default ClipCase writes to .clipcase/. clipcase init --storage notes/cases writes .clipcase.json. Its optional storageDir must be a string; relative paths resolve beside the config file. Malformed, unreadable, or wrongly shaped configuration produces a concise repair diagnostic. CLIPCASE_HOME=/tmp/cases overrides config.

.clipcase/bug-login/
  index.json
  entries/20260101T000100Z-42bb79cf284a.md

index.json stores stable IDs, timestamps, source labels, tags, hashes, byte counts, and relative Markdown paths. See docs/STORAGE.md for details.

Safety model

ClipCase blocks likely secrets before writing content using deterministic regexes for common AWS, GitHub, Slack, private key, and generic token/password assignments. Use --allow-secret only when saving sensitive material is intentional.

Limitations: secret detection is conservative, there is no sync or watcher, binary attachments are out of scope, and clipboard commands are platform-dependent.

Agent handoff usage

clipcase new failing-test
npm test 2>&1 | clipcase add failing-test --source "npm test" --tag failure
clipcase export failing-test --out handoff.md

For a reproducible fixture-backed demo that builds a temporary case, searches it, and exports a handoff, run:

bash demo/run-agent-handoff.sh

See docs/tutorials/agent-handoff-casefile.md for the walkthrough.

Promotion support drafts live in docs/promo/video-brief-agent-handoff.md and docs/promo/social-hooks.md.

Runnable demo

Run a fixture-backed handoff demo from a clean temporary store:

npm run build
bash examples/run-agent-handoff-demo.sh

The demo creates a case, adds a repro fixture and a failing-test note, searches the case store, exports Markdown, and verifies the exported handoff.

Demo and Promotion

• Agent handoff casefile demo
• Video brief
• Social hooks

For a reproducible fixture-backed handoff, run:

npm run build
bash demo/run-bug-handoff.sh

The demo captures repro notes and terminal output from examples/bug-handoff, exports a Markdown handoff, and verifies that secret-like input is blocked by default.

For a fuller copy-paste support workflow, see examples/support-handoff-demo.md. A short, fact-grounded promotion pack lives in docs/promo/social-hooks.md.

For a searchable support handoff that writes JSON, text, and Markdown artifacts, run bash demo/run-search-pack.sh and follow docs/tutorials/searchable-support-handoff.md. The matching recording outline is docs/promo/search-pack-video-brief.md.

Verify

Development supports Node.js 20, 22, and 24 with npm 10. The repository pins npm 10.9.4 so clean installs use the same lockfile implementation locally and in CI.

npx --yes npm@10.9.4 ci
npx --yes npm@10.9.4 run release:check
bash scripts/validate.sh

Contributing and security

See CONTRIBUTING.md and SECURITY.md. Please do not include real secrets in issues or fixtures.

License

MIT

Release verification

Run the same checks locally before opening a release PR:

npm run check
npm test
npm run build
npm run smoke
npm run package:smoke
npm run release:check

npm run package:smoke verifies required package files and the installed clipcase CLI help.

Version tags currently build a package tarball and attach it to a GitHub release. Before creating the tarball, the workflow requires the tag to exactly match v plus the version in package.json (for example, package version 0.1.0 must use tag v0.1.0). They do not publish ClipCase to the npm registry. The release workflow and this installation guidance must be updated together when registry publication is enabled.