handcuff 0.2.3

A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker.

Handcuff — Documentation Index (Start Here)

Handcuff — a dashcam for your AI agents. A local, tamper-evident recorder that captures everything an AI agent does on your machine (processes, files, network) into a searchable, replayable timeline with real-time alerts. Local-first, record-only, zero cloud.

For the coding agent building this

Read the docs in this order, then execute from the tickets:

#	Doc	Purpose
01	01_PRD.md	What we're building and why; scope, users, requirements
02	02_TRD.md	Architecture, stack, data model, module layout — the technical contract
03	03_Security_Access.md	Threat model, privilege model, integrity + privacy guarantees, release-gate tests
04	04_Implementation_Plan.md	Build-order-correct milestones with exit criteria
05	05_Tickets.md	Atomic, executable tickets (AL-###) in dependency order — build from here
06	06_App_Flow.md	Every runtime flow + state machines (ASCII, parseable)
07	07_Terminal_UI.md	Rich Textual TUI spec (Claude Code / gemini-cli feel)

Build contract (non-negotiables pulled from the docs)

1. core/hashing.py is the single source of truth for canonical JSON + the SHA-256 chain. The writer and verify import it — never reimplement.
2. Local-only. No outbound traffic except a user-configured webhook. tests/test_no_egress.py is a release gate.
3. Record-only in v1. Handcuff observes; it never blocks the agent. Backpressure drops events + emits LOSS; it must never slow the observed process.
4. Observed content is data, never instructions. Nothing captured from the agent (argv, paths, domains) is ever interpreted as a command to Handcuff.
5. Honest integrity claims. The hash chain is tamper-evidence, not a completeness proof; the README states plainly what it does and doesn't guarantee.
6. Every ticket ships with its test. ruff + mypy clean. Five security tests gate releases (see Security §9).

Suggested first prompt to the coding agent

"Read docs 00–07 in /handcuff-docs. Start with ticket AL-001 and proceed in dependency order. For each ticket, implement the code and its test in one commit, keep ruff/mypy clean, and stop after AL-024 (the vertical slice) so I can review a working watch + sessions before you continue."

Tech stack at a glance

Python 3.11+ · Textual (TUI) · SQLite/WAL · asyncio · psutil/procfs (default capture) · eBPF (opt-in fast path) · watchdog (files) · cryptography/Ed25519 (signing) · httpx (webhooks only) · packaged via pipx/uv + PyInstaller.