Imprint - Gravador de Workflows para Agentes IA
ashaychangwani/imprint
Grave workflows do navegador uma vez, obtenha ferramentas MCP determinísticas para seus agentes
Ver no GitHubMCP server que captura workflows reais do navegador uma única vez e os converte em ferramentas determinísticas para agentes Claude. Elimina exploração por token ao compilar a sessão gravada em código executável, funcionando como um Postman para agentes IA.
Instalação
npx convez-ai ashaychangwani/imprint1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar interações com websites sem tokens gastos em exploração
- Criar ferramentas reutilizáveis para agentes interagirem com portais web
- Integrar autenticação e fluxos complexos em agentes Claude de forma confiável
Veredito

Solução inovadora que reduz custos de tokens ao compilar workflows capturados em ferramentas determinísticas. Ideal para automatizar interações web repetitivas em agentes, mas exige suporte a Playwright e gerenciamento de sessões autenticadas.
README
A tradução para o português deste README ainda está na fila.
imprint
Teach your AI agent any website. Once.
Record a real browser session, get a deterministic MCP tool back.
No tokens burned on exploration. No "the LLM clicked the wrong button."
The recording is the executable.
Quick Start · Examples · How It Works · Docs
Authentication work stays visible through operation handles and reusable context references. Agents choose whether to continue a retained context or start another; native verification and browser checkpoints return within the same assignment. Native compiler tools share the host executor; failed calls retain their duration and error code so a live process cannot hide a broken compiler connection. Plan/research differences are advisory construction facts. Changed artifacts still need their own live checks. See authentication and repair.
Timed-out questions release the terminal input queue; declared nonsecret choices remain readable by the agent. Successful browser-backed data calls can preserve renewed cookies for later calls without overwriting newer saved authentication. Same-name host-only and domain cookies keep their distinct scopes across replay and browser restoration. That continuity still needs verification against the requested data operation. Local stdio MCP servers can opt in to session renewal for read-only tools, with client approval before sending a new sign-in challenge.
Quick Start
bun install -g imprint-mcp
imprint teach southwest --url https://www.southwest.com
A browser opens. You drive the workflows and narrate what you're doing. Imprint records every request and interaction, then compiles the complete discovered set of deterministic MCP tools your agent can call later.
Want to try a finished MCP before recording anything?
imprint install google-flights --source examples --platform claude-desktop
That registers the checked-in Google Flights example as an MCP server in your client. Swap claude-desktop for claude-code, codex, openclaw, or hermes, or add --print to see the config without changing anything.
On a Hermes agent or Docker host, register the examples directly into Hermes:
for site in google-flights google-hotels southwest discoverandgo echo; do
imprint install "$site" --source examples --platform hermes --no-interactive
done
When HERMES_HOME is set, Imprint writes Hermes MCP entries to $HERMES_HOME/config.yaml; outside Hermes it uses ~/.hermes/config.yaml. For browser-backed MCPs, imprint install also installs Playwright Chromium into $HERMES_HOME/.cache/ms-playwright and writes PLAYWRIGHT_BROWSERS_PATH into the MCP config so Hermes can find it. Use --skip-browser-install only for offline builds where you preinstall the browser yourself. In a fresh Linux image that is missing browser system libraries, install those during image build with bunx playwright install --with-deps chromium.
See It in Action
Teach once. imprint teach google-flights records real browser flows and compiles a 6-tool MCP server — the compile agent reverse-engineers Google's batchexecute wire format itself and wires the staged search→booking token chain, with no hand-written request code. Here is the actual run behind the example snapshot:

Then your agent calls those tools like any other — real-time results through a live trusted-Chrome (cdp-replay) backend:
$ claude "cheapest nonstop SJC→SAN the first week of July, with a carry-on"
Alaska AS1623 SJC→SAN 6:00a→7:32a nonstop $137
Southwest WN2412 SJC→SAN 8:15a→9:45a nonstop $158
Delta DL2901 SJC→SAN 7:10a→8:44a nonstop $169
The current example snapshot includes six live-verified tools, including staged
multi-city search and booking. (The terminal above is a faithful replay —
regenerate/record it with bun scripts/demo-teach.ts.)
How It Works
[!TIP] Recording and compilation happen in one foreground
imprint teachcommand. Install the completed tools in your MCP client withimprint install. Only known user-supplied login credentials are replaced before teaching; cookies, API tokens, responses, and personal data remain visible to the agents.
Existing ${credential.NAME} references in an already-redacted recording reuse
values from your local credential backend. They do not replace saved passwords
with placeholder text. MFA may still require your input.
Request-building errors return to the compile agent as verification feedback, including errors from asynchronous transforms, so it can repair the request and retry.
Recordings and logs, including files named .redacted.json, are not safe to share publicly. Automatic PII and token redaction is disabled; review any file before sharing it.
Imprint writes .redacted.json with private file permissions. A teach that leaves
planned tools unresolved reports a partial result and exits nonzero, even if some
ready tools were published.
Teaching agents and standalone compilers can ask questions in the foreground
terminal, including login approvals, MFA/OTP codes, and missing information.
Questions from concurrent agents appear one at a time; secret input is masked
and returned to agents as temporary references. Authentication uses the existing
auth compiler to continue the same browser and challenge. Later recovery requests
retain that auth work within the teach. Agents first check or restore existing
access before starting another login. Compiled actions can branch on current
responses to reuse authenticated access or continue an observed challenge;
retaining a browser alone does not guarantee MFA is avoided.
Identical concurrent requests share the active
attempt; a previous success never substitutes for the caller's own data check.
Failed teach checks reach a focused component recovery agent before broader
plan repair. It can renew authentication, repair the caller's artifact or a
declared prerequisite through its retained compiler, or dispatch a registered
shared runtime component owner. State recovery immediately retries the built
caller; prerequisite repair rebuilds the selected owner and binds fresh outputs
into consumer checks. Accepted contracts and unrelated builds remain intact.
Every actual failed and retried call stays in the check history. Unknown owners
or changes to contracts, strategy, or dependencies return to the master.
When the live login offers a flow missing from the recording, the auth agent can
operate its verification browser and capture additional request/response evidence.
It can learn the offered flow before requesting the actual OTP or approval, then
compile and verify its replay. Original recordings remain unchanged; discovering
or manually completing a flow alone does not prove reusable authentication.
Run without
--no-interactive when answers may be needed. Detached runs and piped terminals
report input as unavailable. Browser closure during stealth user-agent setup
returns through the existing setup-error handling instead of terminating teach.
On hosts with limited RAM or disk for swap, set IMPRINT_TEACH_LOW_MEMORY=1
to run live data checks one at a time. Successive checks in the same research
pass reuse its browser; a competing pass evicts that browser before using its
own isolated context. Authentication keeps its persistent browser across MFA prompts.
Closing an Imprint-owned browser removes its temporary Chrome profile. Explicit
profiles, including record --persist-profile, are retained; recordings and run
evidence are stored separately.
For every teach, a master agent accounts for the complete discovered operation set. Focused advisors review tool boundaries and parameters, focused planners map one tool at a time, and focused compilers build one tool at a time. The master chooses the build waves: independent tools can run together, while a producer runs before its consumers. Failed checks return factual evidence to the master, which can revise the affected tool and its dependants without rebuilding unrelated tools. Recorded response availability is supplied before MVP selection. The boundary advisor and master receive the same human scope. Agents choose separate tools for distinct recorded purposes before narrowing each tool's inputs; unsupported purposes remain explicit coverage limits. Invalid focused-planner reports return exact diagnostics to the master for repair while preserving successful sibling proposals; they never become accepted execution plans. The retained master receives changed research handoffs without repeatedly resending unchanged history; host validation still uses the full evidence. Codex teaches use one native agent family, with up to ten concurrent children. Agents can delegate further and continue the same conversations through repairs. Each research pass stays in one native assignment: test and inspection results return directly to that researcher, with the same host validation. Master, planner and reviewer repairs and shared-memory queries use that same channel, without routing every intermediate response through the parent. Inspected alternative requests carry their nearest recorded action, and agents explain how any substituted request compares with the selected purpose. Shared research delivers a short index; detailed methods and failed approaches are stored as immutable assets that agents read only when relevant. Independent research calls keep separate browser state and reserve paced start times without holding a shared site lock through slow responses. Master-directed follow-ups resume the same child. Codex owns child lifecycle and concurrency; Imprint retains provider retries, deadlines, execution tools and strict evidence checks. Other providers retain their existing execution paths with four focused workers. Independent research repairs share the master’s parallel waves; dependent repairs, compilation and execution follow the accepted producer ordering. Compiler conversations survive revision-directory changes, and finished tools enter verification immediately while independent siblings continue compiling. Consumers still wait for verified producers. Capture timeouts group repeated endpoint facts so telemetry does not crowd out distinct responses, while keeping matching and readiness rules unchanged. Research request diagnostics also show bounded decoded body differences, helping agents distinguish changed inputs from accidental nesting or encoding changes. Agents judge those differences; they are not an automatic pass/fail rule.
Before that tool's planning, one retained researcher conversation first proves the smallest useful API call. If part of the selected MVP contract or a required downstream value is still unproven, the researcher returns that working partial result instead of pretending it is complete or discarding it. Optional breadth waits for the later best-effort pass. Once all first passes finish, the master can send the exact missing question back to that same conversation with only the relevant sibling results and recorded requests. An independent proven tool can prepare its plan and compile a draft while other research continues, when no queued research needs that attention. The master still reviews the complete plan before normal verification and publication; only an exactly matching draft is reused. With native delegation, completed research reaches the master while unrelated drafts finish. Those drafts settle before final planning can reuse or replace them. Declared consumers retain producer-first ordering. The terminal names each tool entering detailed planning and each master review, reports elapsed waiting time every 30 seconds, and reports when that stage finishes or stops. A waiting update means the stage has not returned yet. Researchers can call proven sibling requests with fresh inputs before testing a consumer; recorded continuation values are not a substitute for fresh output. Compilers can inspect full retained responses from that tool's earlier research through a local index, then choose relevant repeat and contrast cases for offline checks. Each observation keeps its own inputs, outcome and response chain. Researchers can query an entire retained response with a bounded, offline data projection; failed queries return for repair, and projected output is labelled separately from raw text. Teaching now selects a fixed set of recording-backed examples and matches live calls to those examples, changing only expired dates or state. A separate evidence reader establishes expected facts from raw recorded/live responses before seeing parser output, then judges the parser against those facts. Citations can quote the original response bytes or their displayed JSON representation. Each selected live case is reviewed against its matched recorded response chain; unrelated fixtures are left for their own case reviews. Every selected live case and declared dependency chain must pass before publication. Missing coverage is unverified, and raw failures stay with the draft for repair. Fixture bodies are checked before compilation, and research history and inspected recording evidence survive same-run contract revisions. Grounded input mappings are kept separate from the limits of the recorded test cases; missing contrasts alone should not freeze a tool to recorded constants. Research can batch selected calls sequentially and retain isolated browsers during agent thinking. Bootstrap snapshots are cached separately by the requested URL, and capture failures show which matcher conditions failed; cold-start setup remains unchanged. Readiness failures state when no actions have started, and schema repair errors name the exact required fields. These checks need fresh repeated validation before a reliability claim.
Repair or extend an installed data tool with imprint refine <site> --tool <name> --issue "<change>" --from-session <recording.json>. Refinement works in an isolated staging home, preserves existing parameter contracts, and requires recording/live verification plus a strict audit before replacement. Failed refinements preserve installed tools and local evidence. Use imprint audit <site> --strict to reject known broken calls even when the aggregate score exceeds 95%. See targeted refinement. Audits forward explicitly set browser settings (CHROMIUM_PATH, IMPRINT_CDP_HEADED, IMPRINT_JAR_MAX_AGE_SECONDS, IMPRINT_PROXY, and DISPLAY) into their isolated MCP server for either audit provider. See audit troubleshooting.
Public read workflows can opt into native Chromium startup and browser-only replay with "browserStartup": "native". See browser replay troubleshooting.
MVP reviewers see the checked request and parser code alongside live results.
Publication retains the backend from that exact reviewed passing call in
backends.json, so a fresh MCP process starts on the tested path. This records
one execution choice, not a cold/warm benchmark or proof of repeatability.
They also receive actual research comparisons and inspected response excerpts,
not just the researcher's explanation of what those tests proved.
Agents are instructed to distinguish competing meanings of ambiguous fields
with focused evidence, rather than treating a coincidentally matching number
as proof. Uncertain mappings go back to the master for research or a narrower MVP.
Invalid research handoffs also return to the master with their actual test
history, rather than ending the whole teach or counting as an API failure.
Browser snapshots are reused by tool and rung without cookie-name requirements.
An explicit bootstrap URL runs before resolving request URLs that need its
captured state. MCP closes an idle or timed-out tool's CDP sessions without
closing another tool's browser, and a cancelled call does not start another rung.
Fetch-bootstrap tries the API request before deciding whether to escalate; a
missing cookie marker is not reported as an HTTP failure.
Rewording auth or token notes reuses that proof; the master explicitly requests
new research when the actual strategy changes.
The final reviewer receives the same human scope and checks requested tool
connections rather than requiring explicitly excluded operations.
If an agent mistypes run metadata, repair feedback supplies the exact current values.
Recorded page references support generated API-navigation URLs; the final URL
need not appear literally in the recording, but must be grounded and live-tested.
Tool handoffs use agent-selected concrete result paths, not array wildcards.
Binding failures explain the path problem and distinguish it from an API call failure.
Result reviewers see the actual invocation inputs; an unrelated planned test's
expected answer is never substituted for the research baseline or a chain call.
A successful chain result can be reviewed even if a standalone test failed;
that failed test remains visible and still prevents completion until repaired.
Compiler guidance separates a returned value's location from its meaning and
omits uncertain optional metadata instead of filling it from unrelated matching
shapes. Extra responses used to corroborate research stay in the evidence;
required execution requests must contribute necessary state or core output.
Agents ground rendered-result completion checks in core content and inspect
observed layout variations before treating an incidental element as required.
Agents can scope a background response capture to a specific navigation click.
Requests started before that action cannot satisfy the capture, including ones
that finish later. Without an action boundary, capture starts with navigation.
Navigation clicks wait for the selected target to become clickable within the
existing navigation deadline, then dispatch once. Failed clicks report bounded
match, geometry, computed-style and center-hit facts so agents can repair their
chosen interaction from actual page evidence.
Before accepting a navigation capture as reusable, researchers repeat a valid
input and compare a small core-input variation with the same candidate. They
reuse existing decisive observations and distinguish session reuse from setup.
When a background capture fails despite current page results, agents inspect
their delivery source, including structured document data. Changing the baseline
input does not repair the failed valid case. Reviewers trace ambiguous metadata
to its context; matching keywords or units alone cannot justify a named field.
Compilers test the complete current research response before live validation,
including result frames beyond initial metadata, alongside recording examples.
For a request chain, they receive its actual ordered response bodies as a local
offline fixture. They test associations using current response identities and
unmatched records, rather than copying one example's values into parser logic.
For framed protocols, a small parser test checks that an earlier empty or metadata
frame does not hide later records; agents derive the expected result from evidence.
Failed browser calls can include bounded page evidence from browser inspection,
including through fallback and MCP audit errors. Agents use it to investigate missing
captures without treating a timeout as automatic infrastructure failure or rendered
text as API success. Network-capture timeouts also include a bounded list of
observed response endpoints, methods, resource types, statuses and navigation
scope facts, with omitted counts. These facts help agents compare a failed
matcher with actual traffic; they do not change response selection.
Parser checks distinguish unsupported missing fields from evidenced protocol defaults.
Auditors receive exact report tool names.
Planning and final review also check how callers obtain required inputs,
without relying on identifiers hidden in the recording.
Research uses a small contrasting core-input check before claiming parameter
mappings are proven; optional parameter breadth remains deferred.
Agents check the advertised meaning, not just whether results change; a range
contrast distinguishes its bounds from a fixed result region that merely moves.
Handoffs identify the response evidence that establishes the core records' scope
for the compiler to preserve. Demonstrated ignored inputs return for contract
revision; they are not deferred as optional minimization. Audits distinguish a
bound pair's combined behavior from proof of each input's individual effect.
For rendered results after navigation or actions, agents verify that the current
collection finished rendering; document load, a page shell, or an updated control
alone cannot establish readiness. When timing is uncertain, agents compare
initial setup with changed-input calls in the same tool's warm session.
Selection handling respects structured field boundaries and complete identities.
Checking an input does not prove that it selects the corresponding result.
That contrast must distinguish claimed mappings from defaults; changing one
input does not prove the others, and unproven mappings return for follow-up.
The master reviews that evidence even when research labels itself proven;
missing proof within one tool can return to its retained researcher.
Live verification uses the planner's selected test inputs, not a replacement
with the research baseline; the proven backend remains reusable.
The planner chooses that first live case to challenge weak core evidence;
additional unexecuted cases are not claimed as coverage.
Research handoff repair reports independent missing fields together, so one
repair turn can correct the candidate, test reference, and remaining proof gaps.
If a repair exposes further schema errors, the same conversation can correct
them within the shared deadline. Identical rejected outputs stop the repair loop;
invalid decisions never execute.
Blocked terminal counts include unresolved discoveries even when no tool was planned.
Researchers can inspect or search bounded portions of retained live results,
including HTML attributes and embedded state, without repeating the API call.
Compilers receive the selected research call's full saved response and inputs
for offline parser tests, not just a written summary. This evidence stays out of
published runtime artifacts.
After live failures, the master can return an unchanged tool to its retained
researcher with the actual failure evidence, then replan only the affected tool.
MVP reviewers receive the checked build's parser to distinguish observed values
from input echoes; audits require an attributable effect, not merely changed ordering.
Server-returned query text is also an echo, not proof of applied settings.
Final review also sees prior semantic rejections and their actual inputs, so a
later passing baseline does not silently erase an unresolved core failure.
MVP reviewers check returned values against their claimed meaning: optional
breadth can wait, but mislabeled data is a repair, not polish.
If the Codex child reports missing stdin despite a non-empty prompt, Imprint
retries that exact delivery once on the same conversation and deadline.
Researchers can return a concrete input or dependency gap for a master decision without exhausting transport permutations. The master coordinates affected producer outputs and consumer inputs together; fresh live proof is still required. Agents can plan repeated calls to the same tool and bind each call to an exact prior result. The runtime checks a finite invocation order and invalidates dependent proof when that source result changes; a continuation does not require a separate public tool. Existing single-call plans retain their behavior. Chain checks and audits compare actual producer record structures with the consumer's public contract. One selected record can contain several members; unless explicitly excluded, an available fresh multi-member record is checked and compared with the complete consumer result. A passing singleton check does not establish that every selected member survives. Validation, request construction, and parsing keep group properties separate from member properties; a valid group need not repeat its overall fields on every member. Parsers preserve the distinction between alternatives and required components, including when action links exist only on components. Verification compares eligible source records with the output and checks each attribute against its own evidence; a plausible subset or matching sibling value is insufficient. Missing optional details must not erase required members, and constructed selections must preserve the complete selected record through the consumer result. Reviewers also report explicit parser or request guards that reject inputs allowed by the public contract; a fixture's shape must not silently become a restriction on callers.
Generated modules reload from their resolved filesystem paths, so repeated research tests also work when the teach directory is reached through a symlink. Generated wrappers forward caller cancellation and request/response observation callbacks. Cancellation reaches active fetch requests and response reads; a cancelled call is reported separately from a request timeout. Raw prepared-request observations stay inside host diagnostics. Parsers distinguish a valid empty result from a missing or unsupported result envelope.
Semantic agents receive the current shared deadline and remaining time on each turn, including output repairs, so they can budget for compilation and live checks. Repair feedback identifies missing fields by path and expected type, including whether a list or scalar is expected. Invalid output remains rejected. Baseline and dependency API calls are cancelled when that budget expires, with a short bounded cleanup period; late results cannot become successful checks. Exhausting the run deadline is reported as a failed run; provider unavailability is reserved for an actual provider interruption.
Every teach is fresh and stays in the foreground until it reaches a terminal result. There are no resume, phase-window, primary-tool, or partial-selection modes. A run succeeds only when every planned tool is verified; otherwise the terminal reports the failure honestly and exits non-zero.
For an API operation that only the page can construct, a workflow navigation may explicitly select one matching live background response and return its body to the parser. The teaching agent derives that matcher from recording evidence; the runtime does not guess which request matters or turn the capability into a site rule. The recorded response used for offline checks is separate from the response order in a fresh live call. Playbooks remain the final fallback.
During research and compilation, request transforms can compute navigation targets and click actions from current inputs or earlier responses. The declared API response matcher stays fixed so live and offline checks select the same data. Dependent selections preserve the machine values required by the next tool. Producer compilers receive the current tested consumer construction for declared links, so they can check the required representation instead of guessing from names. Adding contextual recording references preserves request proof when the tested request and public inputs remain covered; executable request changes still need matching proof. Parser tests compare contrasting fixture records and check that reported summaries agree with their underlying data. They retain records with absent optional fields and distinguish requested context from observed attributes. Provider capacity failures retry the same conversation within the existing deadline; deterministic request and access errors remain terminal. Compile-time browser cleanup waits for concurrent calls to finish; one completed request cannot idle-close another request's active browser. MCP failures include the completed backend attempts and timings, so a final fallback error does not hide an earlier navigation timeout.
The recorder also has a bounded fallback for Next.js React Server Component
responses that Chromium evicts before Network.getResponseBody can read them.
It streams only narrowly identified GET navigation/prefetch and POST Server
Action responses, keeps normal body capture authoritative, and writes fallback
bytes only when the normal read actually fails. The candidate policy and
resource limits are documented in the capture protocol.
Why Imprint?
Other browser-tool frameworks ask the LLM to decide every click at runtime. Imprint takes a fundamentally different approach:
| Imprint | browser-use / Computer Use | |
|---|---|---|
| Approach | Record once, replay deterministically | LLM decides every click at runtime |
| Token cost | Zero at runtime | Scales with workflow complexity |
| Reliability | Deterministic — same input, same output | Variable — exploration can diverge |
| Bot detection | Real Chromium + stealth-fetch | Detectable automation fingerprint |
| Fallback | Automatic ladder (API → DOM) | None |
| Speed | 200ms – 9s | 30s+ |
Installation
Recommended
bun install -g imprint-mcp
Requires Bun >= 1.3. Or run without installing:
bunx imprint-mcp teach <site> --url <url>
Standalone Binary
curl -fsSL https://raw.githubusercontent.com/ashaychangwani/imprint/main/scripts/install.sh | bash
From Source
git clone https://github.com/ashaychangwani/imprint.git && cd imprint
bun install && bun link
Browser commands (teach, record, login, playbook) and browser-backed imprint install targets auto-install Playwright Chromium when it is missing. For offline CI or prebuilt Linux images where you pass --skip-browser-install, preinstall it ahead of time:
bunx playwright install chromium
LLM providers are auto-detected. Run imprint doctor to see what's available.
| Priority | Provider | Detected via |
|---|---|---|
| 1 | Claude Code | claude on PATH |
| 2 | Codex CLI | codex on PATH |
| 3 | Anthropic API | ANTHROPIC_API_KEY env var |
| 4 | Cursor | cursor on PATH |
Override with --provider <name> and --model <name>.
Codex teaching defaults to gpt-6.1-sol. Keep the Codex CLI current when using
that model for audits or standalone compilation; older installations may reject
it even when the Codex app offers it.
The Backend Ladder
When an API call gets blocked, Imprint doesn't jump to DOM replay. It escalates through the cheapest backend that works:
fetch ~200ms Plain APIs, persisted cookies
│
▼
fetch-bootstrap browser Mints cookies, CSRF tokens, storage
│ + API
▼
cdp-replay ~2-35s API calls run inside a live, trusted Chrome —
│ a protected POST refreshes its anti-bot token
│ between calls (multi-step state-changing flows)
▼
stealth-fetch ~1-12s Defeats Akamai, Cloudflare, DataDome
│
▼
playbook ~9s Full DOM replay — universal fallback
The full order is fetch → fetch-bootstrap → cdp-replay → stealth-fetch → playbook; auto mode walks it and stops at the first backend that works.
For bot-protected sites, imprint probe-backends <site> --tool <toolName> writes a backends.json preference cache so cron and MCP start from the known-good backend instead of rediscovering blocked rungs. Use imprint probe-backends <site> --all to refresh every tool in a multi-tool site; imprint mcp status reports stale or invalid backend caches before they quietly fall back to the default ladder. CDP replay records both cold and warm timings when it succeeds: a timeout-safe cold start may rank by its fast warm runtime, but a cold start above the preferred threshold stays behind cold-safe backends in durable cache order.
During imprint teach, each tool goes through contract, replay, live, and
producer-consumer checks as applicable. The checks leave factual receipts. A
failure goes back to the master for a focused repair, and an independent final
reviewer sees both the current plan and the check history before the run can
complete.
The agent prefers an API workflow.json. It adds playbook.yaml only as the
last fallback when the higher replay rungs are not compatible with the
recorded operation.
Platform Support
After imprint teach completes, register the generated site with
imprint install <site> --platform <platform>:
| Platform | Integration |
|---|---|
| Claude Code | Runs claude mcp add |
| Codex CLI | Runs codex mcp add |
| Claude Desktop | Writes or prints the MCP config |
| OpenClaw | MCP config + SKILL.md export |
| Hermes | MCP config + SKILL.md + cron mapping |
Each site registers as its own MCP server (imprint-southwest, imprint-google-flights, ...) so tools never collide.
Examples
Every example below was one-shot compiled from a single real browser-session recording (imprint teach) — the generated artifacts are committed verbatim as a proof of concept of what the compiler produces, not as maintained integrations. Recording-derived defaults (dates, geo) age out; pass explicit values.
★ Star examples — multi-tool suites, each compiled from one recording and scored by the headless differential audit:
| Example | Tools | Audit | What it shows |
|---|---|---|---|
| google-flights | 6 | live-verified | batchexecute wire-format decode + staged multi-city search→booking token chain, live cdp-replay |
| google-hotels | 4 | 91.7% | autocomplete → search → reviews/booking producer-token chaining |
Other examples:
| Example | Description |
|---|---|
| southwest | Live fare search — defeats Akamai bot detection |
| discoverandgo | Authenticated booking via per-site credential store |
| echo | MCP smoke-test fixture |
Install any example into your MCP client:
imprint install google-flights --source examples --platform claude-desktop
Examples are real generated MCPs, not handwritten SDK samples. imprint install <site> --source examples points the MCP server at this repo's examples/ directory with IMPRINT_HOME, ensures Playwright Chromium for browser-backed tools, and lets your client list and call the checked-in tools immediately:
imprint install google-hotels --source examples --platform codex
imprint install southwest --source examples --platform claude-code
imprint install echo --source examples --platform claude-desktop --print
For your own generated tools, leave off --source examples:
imprint install mysite --platform claude-code
imprint install mysite --platform codex
CLI Reference
imprint --help # all commands
imprint <command> --help # per-command options
| Category | Commands |
|---|---|
| Teaching | teach (the single fresh foreground flow) |
| Artifact utilities | record · redact · generate · compile-playbook · emit |
| Runtime | cron · mcp-server · playbook · probe-backends · audit |
| Credentials | credential set · credential list · credential export · credential import · credential migrate |
| Utilities | mcp · login · assemble · check · doctor · install · uninstall |
The artifact utilities are useful on individual files, but they are not
resumable phases of imprint teach.
Sharing Skills
Teach on your laptop, ship to a remote agent. Generated MCP folders contain the portable tool artifacts: workflow.json or the fallback playbook.yaml, index.ts, optional parser/request-transform modules, and cron/backend metadata. Copy ~/.imprint/<site> into the receiver's ~/.imprint/<site> or commit it to a private repo, install Imprint there, then register it:
bun install -g imprint-mcp
imprint install mysite --platform claude-code
Credentials stay separate. Skill folders contain zero plaintext credentials — only ${credential.NAME} placeholders and a manifest listing what the receiver must provision.
# Export (encrypted with libsodium + argon2id)
imprint credential export southwest --out southwest.imprintbundle
# Import on another machine
imprint credential import southwest southwest.imprintbundle
Send the bundle over any channel. Pass the passphrase out-of-band.
See Sharing Skills for the full flow.
Documentation
| Getting Started | Full walkthrough |
| Architecture | Data flow and module map |
| Integrations | Per-platform setup |
| Security | Redaction, credential handling, what gets stored |
| Sharing Skills | Credential export/import and remote provisioning |
| MCP Maintenance | Audit, disable, restore, and prune MCP state |
| Troubleshooting | Common failures and fixes |
| Tracing | OpenTelemetry tracing, Phoenix-owned cost tracking, and setup |
- Decisions — design rationale
- Glossary — terms and concepts
- Capture Protocol — CDP recording details
- Playbook Debugging — DOM replay debugging
- Notifications — alert setup
Contributing
Conventional Commits enforced in CI. Run bun run check before submitting.
Good first contributions: replay backends, notification predicates, auth extractors, example sites, docs.
See CONTRIBUTING.md for full guidelines.
Teach research retains each received response before later requests, extraction, or parsing can fail. Agents can inspect bounded excerpts of failed calls without repeating them; those responses remain failed evidence.