# _etchplan_

> Compile agent workflows into efficient, safe, auditable execution plans. _etchplan_ ingests an AI agent's execution traces, mines the repeated workflows, and compiles them into guarded deterministic routines that run behind a fallback to the original agent, so recurring agent work runs at a fraction of the token/latency cost, with an audit trail.

Use _etchplan_ when an agent repeats the same multi-step workflow and you want to replace that repeated reasoning with a cheap, validated, deterministic routine (with automatic fallback to the agent when the routine's preconditions don't hold). It is Apache-2.0, local-first (no data leaves the machine by default), and every reported number carries provenance (`measured | recorded | estimated | assumed`).

## Install

Install from PyPI (Apache-2.0, local-first, Python ≥ 3.11):

```bash
pip install etchplan    # or run with no install: uvx etchplan <command>
etch --help
```

The commands below are written as `etch …`. To run from a checkout instead, prefix them with `uv run`.

## Quickstart (capture → mine → compile → run)

```bash
uv run etch hook install claude-code --write   # harness: claude-code | codex | opencode
# ...use your agent normally; traces capture locally to ~/.etchplan/...
uv run etch import claude-hooks                 # normalize captured sessions into traces
uv run etch mine patterns --out patterns.json   # find repeated workflows
uv run etch compile pattern patterns.json --pattern-id top --out plan.yaml  # 'top' = highest-support compilable pattern
uv run etch validate plan plan.yaml             # execute over replay cases (measured)
uv run etch run plan.yaml --input input.json    # runs behind fallback to the original agent
uv run etch redact <file>                       # redact secrets/PII before sharing a trace/plan
```

## Key commands

- `etch demo`: run the whole offline loop on a bundled example (import → mine → compile → validate → run) in a temp dir; no agent, no keys, $0.
- `etch doctor [<harness>]`: verify capture is wired and flowing (hook installed, events landing, DB receiving); flags the Codex untrusted-hook and opencode plugin-dir gotchas.
- `etch hook install <claude-code|codex|opencode>`: install local trace capture for an agent harness.
- `etch import <claude-hooks|codex-hooks|opencode>`: normalize captured sessions into traces.
- `etch mine patterns`: mine gap-tolerant repeated subsequences with parameter-flow + invariant learning.
- `etch compile pattern`: synthesize a guarded `ExecutionPlan` from a mined pattern (mutating steps stay gated).
- `etch validate plan`: validate by executing the plan over trace-derived replay cases.
- `etch run`: execute a plan behind fallback to the original agent, with an append-only audit log.
- `etch redact`: redact secrets/PII + slot identifiers in a trace/plan/hook-events file before sharing.

## Computer-use (preview)

The same capture → mine → compile → replay loop applies to GUI/web computer-use. Captured actions bind to accessibility-element NAMES (or, for an agent, the semantic action it issued), not pixels, which is what makes replay deterministic. Replay rides the same trust loop as plan execution (shadow, approve, canary, drift kill-switch, audit), behind a per-substrate safety screen.

- `etch import agent-computer-use <log> --adapter <claude-in-chrome|computer-tool>`: hook an agent's computer-use tool calls into traces (the product path; semantic browser calls have zero pixel fallback).
- `etch desktop capture`: record a real macOS GUI session (PyObjC + Accessibility; the `desktop` extra). `etch import desktop-capture` normalizes it.
- `etch desktop compile-plan <actions.json> [--parameterize]`: compile a desktop routine to an `ExecutionPlan` that replays via guarded AppleScript (`desktop_registry` validate-only; `desktop_registry_live` controls the Mac).
- `etch browser compile-plan <actions.json> [--parameterize]`: compile a browser routine that replays by re-issuing semantic actions (`browser_registry` validate-only; `browser_registry_live` drives a real browser via Playwright, locating elements by role/name).

## Links

- [README](README.md): full overview, measured AppWorld results, and the measurement-honesty policy.
- [LICENSING](LICENSING.md): Apache-2.0 code; hosted/enterprise are commercial.
- [SECURITY](SECURITY.md): local-first data handling and the AST-guard / mutation-gate safety model.
- [CONTRIBUTING](CONTRIBUTING.md): DCO, dev setup, and how to add a new agent-harness adapter.
