handprint.sh

handprint.sh is the protocol: a local-first, privacy-first way to capture, sign, and own the human decisions behind your work. A handprint is the artifact it produces, one signed, immutable record of the decisions from an AI session. The protocol defines how those artifacts are structured, sanitized, signed, and shared, so the same human signal can be aggregated and owned by the people who created it. Today it reads Claude Code transcripts, and support for other agents is on the roadmap.

AI tools increasingly generate the outputs (code, designs, text), but the decisions that shape those outputs are still human. Today, those decisions evaporate, lost in ephemeral chat sessions, undocumented in commits, and invisible to anyone reviewing the work later. Handprint captures decision provenance so the human expertise behind AI-assisted work is recorded, signed, and attributable.

A handprint is a signed, immutable JSON object that records one or more human decisions from an AI interaction. It contains a version and timestamp, marks (typed decisions), artifact references (what the decisions produced), source metadata (which agent was involved), an encrypted payload of the sanitized conversation, a cryptographic signature, the public key that produced it, and a parent link to the previous handprint that forms a hash chain. Once signed, a handprint is never modified.

Marks are the structured decisions inside a handprint. Each mark has a type, a subtype, and a note (1 to 280 characters). There are three types. Vision covers goals, direction, and principles. Choice covers approvals, overrides, rejections, constraints, and inquiries. Method covers tools, knowledge, and process. Together they capture what you wanted, what you decided, and how you decided it.

Artifacts are references to the outputs that a decision influenced, such as a git commit, a git repo, a file, a URL, a deployment, a C2PA manifest, or a custom reference. Each artifact stores a type, a URI, and an optional content hash. URIs must use an allowed scheme (http, https, git, ssh, or file). Artifacts are pointers, not copies.

Git blame tells you who changed a line of code. Commit messages describe what changed. Neither captures why, meaning the goals, trade-offs, rejected alternatives, and domain knowledge that shaped the work. Handprint records the decision layer, the human judgment that directed the AI, signed cryptographically and linked to the artifacts it produced.

No. Handprint is output-agnostic. Artifact types include files, URLs, deployments, C2PA manifests, and custom references, not just git commits. Any AI-assisted decision can be captured, from architecture choices to design direction, content strategy, and business trade-offs. Capture currently happens from Claude Code transcripts, with broader agent support on the roadmap, but the decisions you record can describe work of any kind.

There are two options. With npm, which is cryptographically verified, run npm install -g handprint-sh and then verify with npm audit signatures. With curl, for convenience, run curl -fsSL handprint.sh/install | sh, which downloads from GitHub Releases, verifies the published checksums, and installs to ~/.handprint/bin/. Either way you need Node.js 20 or later.

Run handprint init in your project directory. This creates a .handprint/ directory with a config file, an AGENTS.md pointer file for AI tools, and a .gitignore that tracks config and AGENTS.md while ignoring the objects store and refs. On first run, it also sets up ~/.handprint/ globally with your seed and keys.

You never tag decisions by hand, because ambient detection is the entire point. When you run handprint grab, the CLI scans your registered transcript sources (Claude Code today, with other agents on the roadmap) for new conversation chunks since the last scan, then runs those chunks through an extractor (local or hosted) that identifies marks and enriches them with artifact references like recent git commits or changed files. You review the extracted marks before they are recorded, but you should never need to write them yourself.

Today handprint works with Claude Code. It reads Claude Code transcripts, extracts marks from them, and signs the result. The protocol and the data model are deliberately agent-agnostic, but Claude Code is the only agent wired up right now. Support for other tools (Cursor, Codex, and similar transcript-producing agents) is on the roadmap, not shipped. Transcript sources are registered under ~/.handprint/sources/ with their path, format, and last-scanned timestamp.

Yes. handprint push is opt-in, so if you never run it, nothing leaves your machine. You still get the full local chain, including signed handprints, hash chain integrity, local verification with handprint verify, and encrypted conversation payloads. Handprint works entirely offline as a personal decision log.

No, and that's deliberate. Run handprint grab yourself whenever you want to pick up new work. Because grab is incremental (a watermark means every run only processes what's new) and idempotent, re-running it often is cheap and nothing is ever recorded twice — you just decide when it runs, instead of something deciding for you. See the next question for why we don't offer an automatic option.

We built both a Claude Code Stop-hook (fires after every agent turn) and a launchd timer (fires on a schedule) and pulled both. Two problems. First, memory: the hook's debounce was a plain timestamp file, so with several concurrent agent sessions, simultaneous Stop events could race past that check before any of them recorded a run — multiple detached grab --push processes would launch at once, and on a machine running many sessions that piled up into gigabytes of stuck background processes. The timer avoided that specific race with a lock file, but it's still something running unattended on your machine. Second, leakage risk: anything that fires without you deciding to run it extracts and encrypts conversation content on its own schedule, which is more surface for the sanitizer to catch before anything is even queued for review, and more chances for something sensitive to get swept in ambiently rather than when you're actually paying attention. Manual grab means capture only happens when you decide to run it.

Handprint extracts structured marks (type, subtype, note) and artifact references from your AI conversations. It also records source metadata (which agent you used, which extractor produced the handprint) and timestamps. Your raw conversation text is sanitized, encrypted, and stored locally. It is never sent to the hub.

When you run handprint push, the hub receives the version and timestamp, your marks (type, subtype, note), artifact references (type, URI, hash), source metadata (agent, extractor, session), your Ed25519 signature and public key, and the parent hash linking to the previous handprint. The encrypted conversation payload is explicitly excluded from the push and stays local.

Four things never leave your machine. The first is your seed (the private key material), stored at ~/.handprint/keys/seed with mode 0600. The second is the derived encryption key, which exists only in memory and is wiped after use. The third is your raw conversation text, which is never stored anywhere. The fourth is the sanitized conversation text, which is encrypted and stored locally in the project's .handprint/objects/ store. Your hub auth token, obtained when you run handprint login, also stays local in ~/.handprint/credentials.json.

Before anything is encrypted, your conversation text passes through aggressive sanitization that runs locally on the plaintext. It redacts email addresses, PEM key blocks, and known token prefixes (Slack xox tokens, Stripe sk_live_ and sk_test_ keys, GitHub gh[pousr]_ tokens). It redacts ALL_CAPS KEY=VALUE secrets whose name contains KEY, SECRET, TOKEN, PASSWORD, or API (both the name and the value are removed), bare ALL_CAPS identifiers containing those same words, and --key or --api-token style command flags. It redacts URL auth parameters such as token= and key=, and any mixed alphanumeric string of eight or more characters that contains at least two letters and two digits. False positives are acceptable, because over-redaction is intentionally preferred over under-redaction.

Each handprint is canonicalized into deterministic JSON with sorted keys, hashed with BLAKE2b-256, and then signed with your Ed25519 private key. The signature covers every field except the signature itself. The 64-byte signature and your 32-byte public key are included in the handprint object, so anyone with your public key can verify that you authored it and that it has not been tampered with.

Handprint uses the @noble libraries by Paul Miller, pure-JavaScript and independently audited, with no custom crypto. Signing is Ed25519 via @noble/ed25519. Hashing is BLAKE2b-256 via @noble/hashes, used for object hashes, the parent hash chain, and signature digests alike. Local payload encryption (at rest only) is XSalsa20-Poly1305 via @noble/ciphers with a 24-byte random nonce. There is no libsodium, no tweetnacl, no node:crypto, and no SHA-256 anywhere in the stack.

Ed25519 offers 32-byte keys (versus hundreds of bytes for RSA), deterministic signatures (no random nonce, so none of the catastrophic nonce-reuse bugs that affect ECDSA), constant-time operations by construction, and broad library support. A base64url-encoded Ed25519 public key is 43 characters, compact enough to embed in every handprint object.

GPG solves a different problem (encrypted communication) and carries substantial complexity, including key servers, web of trust, ASN.1/PEM encoding, large keys, and a notoriously difficult user experience. Handprint needs compact signatures embedded in JSON objects, a single seed that derives everything, and small audited primitives. It gets that from the @noble libraries, which are pure JavaScript, dependency-light, and constant-time by design, with no key server or configuration to manage.

Each handprint includes a parent field containing the BLAKE2b-256 hash of the previous handprint, forming a hash chain from HEAD back to genesis. Any tampering with a historical handprint would break the chain. The chain provides ordering guarantees, tamper evidence, and a verifiable history of all your decisions in a project.

Run handprint keys rotate to generate a new seed and register the new public key with the hub. Old handprints remain verifiable because the hub retains your earlier registered public keys. Payloads encrypted with the old seed's derived key become unreadable unless you backed up the old seed first.

Claude Code is the only agent wired up today, and handprint works with Claude Code transcripts right now. The data model and protocol are agent-agnostic by design, so other transcript-producing agents can be added later, but that broader support is on the roadmap and not yet shipped. When this FAQ refers to AI agents generally, read it as Claude Code today, with everything else planned.

An agent interacts with handprint through the CLI, using the same commands a human would. The key command is handprint grab, which the agent should run after significant decisions. Agents discover handprint's presence through the .handprint/AGENTS.md file in a project's root. In practice this means Claude Code today, with other agents on the roadmap.

After significant decisions. That includes when the human sets a goal or direction (a vision mark), approves, overrides, or rejects an approach (a choice mark), or specifies a tool, technique, or domain knowledge to apply (a method mark). Not every message is a decision, and the extractor handles that judgment.

The agent runs handprint grab as a CLI command, and the CLI reads the seed from ~/.handprint/keys/seed to sign and encrypt. The agent process needs filesystem access to that seed file (mode 0600, owner-only), but it never handles key material directly. The CLI reads, derives, uses, and wipes keys internally.

Yes. Every share has a public, read-only JSON snapshot. On a share page, click Analyze (the ✦ button) for instant, deterministic insights — plus a data URL you can hand to any coding agent, or a ready-to-paste prompt ("fetch this JSON and summarize my decision style, where I'm most decisive, notable overrides"). The agent fetches the snapshot at /api/v1/shares/<token> and reasons over it — no key, no login, just data.

Yes. The CLI (handprint-sh), the types package (@handprint/types), and the protocol specification are all open source. The hub API and the site at handprint.sh are the hosted service. The protocol is designed so that anyone can build alternative tooling against the same schemas.

Because conversations with AI contain sensitive information, including proprietary code, business strategy, and personal context, that should never be uploaded to a third-party service by default. Local-first means you get full functionality offline, your data stays on your machine unless you explicitly publish, and the cryptographic guarantees do not depend on trusting a server. Privacy is the architecture, not a policy promise.

The name comes from the Cueva de las Manos (Cave of Hands) in Patagonia, where 9,000-year-old stenciled handprints are the oldest known proof of human presence. A handprint says "I was here, I made this." In a world where AI generates increasing amounts of output, a handprint is cryptographic proof that a human was present, making decisions and applying judgment.

The protocol is open and the schemas are published. The hub API accepts standard JSON payloads over HTTPS, so building an alternative hub against the same @handprint/types schemas is architecturally straightforward. That said, self-hosting and interoperability across multiple hubs are on the roadmap rather than shipped today, and self-hosting documentation is still planned.