Metadata-Version: 2.4
Name: handcuff
Version: 0.2.3
Summary: 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.
Project-URL: Homepage, https://github.com/Mister2005/Handcuff
Project-URL: Repository, https://github.com/Mister2005/Handcuff
Project-URL: Issues, https://github.com/Mister2005/Handcuff/issues
Author: Varun Gupta
License: MIT
Keywords: agents,langchain,langgraph,observability,prompt-injection,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyfiglet>=1.0
Requires-Dist: python-ulid>=2.2
Requires-Dist: rich-pixels>=3.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: textual>=0.58
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Description-Content-Type: text/markdown

# 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.
