# Design: Imprint — "Postman for AI Agents"

> **Historical context**: This design doc was created in April 2026 during initial exploration. The project shipped as a **CLI tool** (`imprint teach`, MCP servers, cron daemon) rather than the Chrome extension architecture described here. For current architecture, see [architecture.md](architecture.md) and the [README](../README.md). This doc is preserved to document the decision-making process and alternative approaches considered.

Generated by /office-hours on 2026-04-02
Branch: unknown (pre-repo, idea stage)
Repo: imprint
Status: APPROVED
Mode: Startup

## Problem Statement

AI agents need to interact with websites, but there's no good way to teach them how. The current approaches are either fully autonomous (vision-based agents that re-parse HTML on every run, fragile to UI changes) or fully manual (developers copying network requests from browser dev tools and hand-crafting automations). There's a gap: a tool that lets a human demonstrate a web workflow once, captures the underlying API structure, and generates a durable automation that an agent can execute autonomously.

The deeper thesis: personal AI agents are emerging, and they need a teaching mechanism. "Similar to how you would teach a human" — show them, narrate what you're doing, and they learn the workflow.

## Demand Evidence

**Honest assessment: demand is hypothetical.**

- No users, no waitlist, no paying customers.
- The founder experiences this pain personally: "I usually go to the network tab, copy over the relevant requests and send them to an agent to try to figure it out." Frequency: a few times a month. Each instance costs ~30-60 minutes.
- The demand hypothesis rests on the growth of personal AI agents and the MCP ecosystem. Both are growing but neither has proven consumer willingness to pay for teaching tools.
- No evidence that other developers share this exact workflow pain at significant scale.

**What would validate demand:**
- 10 developers willing to pay $29/month before the product exists
- A Discord/community of 500+ people manually building MCP servers who express frustration with the process
- An open-source tool with 1,000+ GitHub stars solving a subset of this problem

## Status Quo

What people do today to automate website interactions:

1. **Developers:** Open browser dev tools → inspect network tab → manually copy request patterns → paste to an AI agent or write Playwright/Puppeteer scripts. Takes 30-60 minutes per workflow. Works but doesn't scale.
2. **Enterprise teams:** Buy UiPath or Automation Anywhere ($50K-500K/year). UI-level recording. Fragile. Requires dedicated RPA engineers to maintain.
3. **Power users:** Use Zapier/Make for pre-built integrations. Only works for services with official APIs. Doesn't work for arbitrary websites.
4. **AI agent builders:** Use Browser Use, Skyvern, or build custom solutions with Playwright + LLM. Code-first. No teaching mode.
5. **Most people:** Do it manually, every time. No automation at all.

## Target User & Narrowest Wedge

### Target User (revised after competitive analysis)

**Primary:** AI engineering teams at companies building agent products (support automation, sales automation, competitive intelligence). These teams need their agents to interact with internal tools and third-party SaaS products. They have budget, technical skills, and an immediate need.

**Secondary:** Solo developers building AI agents/MCP servers who want to quickly turn any website into a programmatic interface.

**NOT the initial target:** Consumers wanting personal AI agents to handle Southwest rebooking. Too early, too hard to monetize, too many legal/ToS risks.

### Narrowest Wedge

**"Turn any internal tool into an MCP server in 5 minutes."**

Start with companies automating their OWN internal tools (admin panels, dashboards, internal apps). Zero legal/ToS risk because they own the website. Controlled environment. Known auth patterns. Willing to pay.

## Competitive Landscape

### Direct Competitors

| Player | Approach | Funding | Differentiation from Imprint |
|--------|----------|---------|----------------------------------|
| MultiOn | Vision-based autonomous agent | ~$26M (YC) | No teaching mode. Fully autonomous. Fragile to UI changes. |
| OpenAI Operator | Vision-based, built into ChatGPT | OpenAI-backed | Same. No user demonstration. No network-level understanding. |
| Bardeen | Chrome extension, pre-built playbooks | ~$10M | Pre-built, not user-taught. Fixed integrations. |
| Axiom.ai | Macro recording | ~$5M | Pure UI recording. No AI. Extremely brittle. |

### Infrastructure (Complementary)

| Player | Relationship |
|--------|-------------|
| Browser Use (100K+ GitHub stars) | Could be execution engine |
| Browserbase | Could host replay/execution |
| Playwright/Puppeteer | The status quo being replaced |

### Key Positioning Insight

**"Postman for AI agents."** Postman started as a Chrome extension for API testing, became a $5.6B company. Imprint occupies the same conceptual position: reverse-engineer APIs for a new consumption paradigm (agents instead of humans).

## Constraints

- No existing codebase. Greenfield project.
- Solo founder (no team yet).
- Pre-product stage. No funding.
- WebSearch unavailable in current environment (org GCP policy blocks it).
- Must validate demand before significant engineering investment.

## Premises

1. Most websites expose reverse-engineerable API structures. *(agreed)*
2. Intent inference requires user context + agent observation working together — pure observation isn't enough. *(revised, agreed)*
3. ~~Teaching by demonstration is the right UX.~~ **REVISED:** Teaching by demonstration is ONE valid input method, but lesson durability is a core design challenge. "Teach once, run forever" is the aspiration, not the guarantee. The product needs a lesson health system that detects when automations break and helps users fix or re-teach them. *(revised based on second opinion)*
4. Automations can run autonomously. *(agreed, with noted risk around auth tokens, CSRF, rate limits)*
5. Output format is TBD — MCP is one option but not necessarily the only answer. *(open)*

## Cross-Model Perspective

An independent Claude subagent reviewed the competitive landscape and diagnostic:

**Steelman:** "A Chrome extension that watches users perform complex web workflows once, captures both UI interactions and underlying API calls, then generates persistent, API-level automations that run faster and more reliably than vision-based agents. The key insight: most web agents solve the wrong problem — they re-parse HTML on every run instead of learning the actual data layer once."

**Key challenge:** The "teach once, run forever" promise breaks down because lessons rot — auth refresh, A/B tests, API versions change. Users may spend more time debugging broken lessons than creating new ones. Evidence to watch: if week-4 retained users have fewer active lessons than week-1 users, the teaching metaphor has failed.

**Biggest threat:** Not other startups — Anthropic/OpenAI shipping first-party MCP learning as a native feature. `npx @anthropic-ai/mcp-learn https://api.example.com` bundled with Claude Desktop would make the Chrome extension obsolete.

**Positioning recommendation:** "Postman for AI agents." Target AI eng teams at companies. Start with internal tools (zero legal/ToS risk). Sell "Turn any SaaS tool into an MCP server in 5 minutes."

## Approaches Considered

### Approach A: "Teach Mode" Chrome Extension — Ship the Magic
Chrome extension with a Teach button. User clicks it, browses normally, narrates intent in the sidebar (e.g., "I'm searching for flights to NYC" — this context helps the agent distinguish search parameters from navigational clicks). Extension captures network requests + DOM events via Chrome's webRequest API. On "Done Teaching," an LLM (Claude Sonnet via Anthropic API) analyzes the captured requests, DOM events, and narration to infer workflow structure and generate a reusable automation.
- **Effort:** M (human: ~3 weeks / CC: ~3-4 days)
- **Risk:** Medium
- **Completeness:** 6/10

### Approach B: "Teach + Replay" — Trust Through Verification (CHOSEN)
Everything in A, plus a Replay mode where the agent shows you what it learned by executing the workflow while you watch. You approve, edit, or re-teach before it goes autonomous. Includes a lesson dashboard with health monitoring.
- **Effort:** L (human: ~6 weeks / CC: ~1 week)
- **Risk:** Medium
- **Completeness:** 8/10

### Approach C: "Teach + Expand" — The Agent Learns Beyond What You Showed (GRADUATION PATH)
Everything in B, plus after learning one workflow, the agent autonomously explores related workflows. "I showed you how to rebook a flight — now figure out how to check status, cancel, add bags." **Note: this is a research-stage graduation path.** Requires validation that LLMs can reliably infer API relationships from a seed demonstration. May require significantly longer R&D or be infeasible with current models. Do not commit engineering resources until Approach B is validated.
- **Effort:** XL (human: ~3 months / CC: ~2 weeks, likely longer)
- **Risk:** High
- **Completeness:** 10/10

## Recommended Approach

**Approach B (Teach + Replay), with graduation path to C.**

The Replay mode is what turns "cool demo" into "product I trust." Users won't let an agent autonomously rebook their flights unless they've watched it do it correctly first. The lesson dashboard with health monitoring addresses the lesson-rot risk raised in Premise 3 revision.

**Go-to-market: internal tools first.** Start with companies automating their own internal admin panels and dashboards. Zero legal/ToS risk. Controlled auth. Willing to pay.

## Terminology

- **Lesson:** A captured teaching session (network requests + DOM events + user narration) that the agent has processed into a replayable workflow.
- **Automation:** The executable artifact generated from a lesson (MCP server, API wrapper, or script).
- **Replay:** The agent executing a learned lesson while the user watches for verification.

## Open Questions

1. **Output format:** MCP server? Playwright script? API wrapper? All of the above? Need to test what users actually want.
2. **Pricing model:** Per-lesson? Per-seat? Usage-based? "Postman for AI agents" suggests freemium ($0 for 3 lessons, $29/mo Pro, $99/seat/mo Team). Team features: shared lesson library, role-based access, version history for lessons.
3. **Auth handling:** The hardest technical problem. Chrome extensions cannot access httpOnly cookies. For the internal tools wedge, assumption is companies can provide service accounts or long-lived API tokens. For third-party sites, may require a native messaging host (outside Chrome sandbox) or require the user to be logged in during replay. Needs prototyping before committing to an approach.
4. **Lesson health:** Options under consideration: (a) Scheduled daily replays in headless mode, flag lesson as unhealthy if success rate drops below 80% over 3 days. (b) Pre-flight health check before each execution. (c) Passive monitoring via user-triggered executions. Start with (c), graduate to (a).
5. **Platform risk mitigation:** If Anthropic ships native MCP learning, what's the moat? The lesson library, team features, lesson health monitoring, and enterprise integrations that the platform won't build. Speed matters here.
6. **SPA and dynamic content:** How does the tool differentiate between page navigations and client-side state updates in SPAs? How are WebSocket/SSE connections captured and replayed? GraphQL subscriptions?
7. **CORS restrictions:** During replay, cross-origin requests may fail. Options: (a) generate server-side automation instead of client-side replay, (b) require CORS proxy for affected sites, (c) document limitation. For internal tools wedge, CORS is typically not an issue.
8. **Data storage and privacy:** Captured network requests may contain sensitive data (auth tokens, PII). Where is this stored? Options: local-only (Chrome extension storage), encrypted cloud (for team sharing), or hybrid. Privacy policy and data retention needed before launch.

## Success Criteria

- **Week 1:** Working Chrome extension that captures network requests + user narration during a browsing session.
- **Week 2:** Agent generates a working automation from a captured session (at least for one target site).
- **Week 4:** Replay mode works — user can watch the agent execute a learned workflow.
- **Week 6:** Lesson dashboard with health status. 3 beta users from AI eng teams.
- **Month 3:** 10 paying customers ($29/mo). Lesson durability > 70% (70% of lessons created remain functional after 30 days, measured by automated replay tests).
- **Month 6:** Team features. 50 paying customers. Graduation to Approach C begins.

## Risk Assessment

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| Platform risk (Anthropic/OpenAI ships native MCP learning) | Critical | Medium | Build moat via team features, lesson library, enterprise integrations. Move fast. |
| Lesson rot (automations break as websites change) | High | High | Lesson health monitoring. Periodic replay tests. Easy re-teach flow. |
| Legal/ToS (automated access to third-party sites) | High | Medium | Start with internal tools only. Add third-party support only after legal review. |
| Distribution (getting discovered in Chrome Web Store) | Medium | High | Dev community marketing. Open-source the core engine. Content marketing ("How to turn X into an MCP server"). |
| Technical fragility (auth, CSRF, rate limits) | High | High | Network-level capture is more durable than UI-level. But auth remains hard. Focus on internal tools first where auth is controlled. |

## Distribution Plan

- **Chrome Web Store** for extension discovery (free tier for individual developers who become champions inside companies).
- **B2B direct sales** as primary GTM for AI engineering teams. Chrome Web Store is for discoverability, not primary revenue channel.
- **Web app** for the lesson dashboard and team features (SaaS, hosted).
- **npm package** for the CLI engine (open source, drives adoption and community).
- **GitHub** for the open-source core (community building, trust, contribution funnel).

CI/CD: GitHub Actions for extension builds, web app deploy (Vercel/Fly.io), npm publish.

## Dependencies

- Chrome Extension Manifest V3 APIs (webRequest for network capture, sidePanel for teaching UI). **Note:** Manifest V3's declarativeNetRequest has limitations on programmatic header injection. Auth token replay may require chrome.webRequest API (available in MV3 with host permissions) or require the user to be logged in during replay.
- An LLM API (Anthropic Claude Sonnet recommended) for analyzing captured sessions and generating automations
- A headless browser (Playwright) for replay execution and lesson health checks
- A hosting provider for the web dashboard (Vercel or Fly.io)

## The Assignment

**Do not build anything yet.**

Your assignment for this week: find 5 AI engineering teams at companies that use internal admin tools. Ask them one question: "If you could turn any internal tool into an MCP server in 5 minutes by showing an AI how to use it, would you pay $29/month for that?"

If 3 out of 5 say yes — build the Chrome extension.
If 0-2 say yes — the problem isn't painful enough. Revisit the target user.

Where to find them: AI engineering communities on Discord (Anthropic's Discord, LangChain Discord, AI agent builder communities), Twitter/X (search "building MCP servers"), LinkedIn (AI engineers at mid-stage startups).

## What I noticed about how you think

- You said "there has to be something that is truly novel about the idea" when you rejected the HAR Analyzer MVP. That's taste, not stubbornness. You're right that a CLI tool doesn't demonstrate the magic. The teaching interaction IS the wedge — you saw that clearly.
- You revised Premise 3 when the second opinion challenged it. Most founders defend their assumptions. You said "Revise the premise" without hesitation. That's the right instinct — conviction about the vision, flexibility about the implementation.
- You framed the entire idea around "teaching agents like you would teach a human." That's a more powerful narrative than "MCP builder" or "browser automation tool." It's a thesis about how the world should work, not just a product feature.
- You don't know your market yet. You said "I don't know how other people do it." That's honest, and it's the thing to fix before you write code. The assignment above is the single highest-leverage thing you can do this week.
