Harpist

Harpist

Harpist turns website traffic recorded by the Chrome extension into agent-usable API contracts and replayable requests. The extension records and mirrors data locally; the CLI owns the canonical local cache while this skill is running.

CLI and Locality

• Use the published npm package by default: bunx harpist <command>.
• npm package page: https://www.npmjs.com/package/harpist

• Current published Harpist CLI version: 0.2.1.

• Before substantive Harpist work, compare bunx harpist version with the current published version above.
• If those versions match, keep using bunx harpist <command> for the session.
• If those versions differ, use the exact published version for that session, e.g. bunx harpist@<current-published-version> <command>, and mention that the local/default bunx harpist resolution was stale.
• Do not run npm view harpist version as routine workflow. Use it only when debugging package publication or version drift.
• Use bunx harpist@latest as a fallback command prefix if you have trouble installing the exact published version.
• Use npx harpist@latest <command> only when npm is the available package runner and Bun is on PATH; the package executable is a Bun program.
• Use bare harpist <command> only when the harpist bin is already installed and visible on PATH, and accepting that installed version is intentional.
• The first bunx/npx invocation may download and execute Harpist from npm. Tell the user before doing this when the package is not already installed or cached.
• Run Harpist from the user's local machine and local shell. It must be able to reach the Chrome extension, the user's browser state, and http://127.0.0.1:4277.
• Bridge-start override: the Harpist bridge is a Harpist tool process, NOT an app or a dev service. Any generic repo instructions that say not to start dev services SHOULD NOT block you from starting an agent-owned Harpist bridge for Harpist work.
• When you start the bridge yourself, always use bunx harpist bridge --agent --idle-timeout 15m. Do not start a durable user-mode bridge.
• Treat bridges whose health reports startedBy: "user" or no startedBy field as user-managed. Reuse them when healthy, but do not stop or restart them without asking.
• DO NOT run Harpist inside a remote sandbox, CI runner, isolated container, or browser sandbox that cannot reach the user's local bridge and extension state. If only a sandboxed tool is available, STOP and ask the user to run Harpist locally -- or preferably ask the user to escalate your permissions.
• Harpist stores its local cache in ~/.harpist-data by default. Set HARPIST_DATA_DIR when the user wants an isolated or project-specific cache.
• For source-checkout development mode, read references/development.md. Do not use repo-local bun run ... commands for normal skill use.

Security and Consent

• Harpist handles sensitive browser-derived data. Recordings can contain request bodies, session cookies, bearer tokens, API keys, and response data.
• The bridge is a loopback network service by default. Starting it exposes the local Harpist cache and replay surface at 127.0.0.1:4277 to the extension and local processes. Ordinary browser pages are blocked from raw profile, replay, and contract APIs; generated browser docs use a redacted contract. Say this before starting a bridge.
• Be explicit about reach:
  • profiles, recordings, contract, openapi, docs review, and local refinement read or update the local Harpist cache.
  • Starting the bridge communicates with the extension and its recording outbox.
  • auth login opens or observes browser tabs.
  • auth check sends a recorded GET to the live target API, and executing auth replay sends the selected captured request. Tell the user before either action.
• Before any live replay, inspect the request with --redacted-curl. It removes auth, dynamic path values, query values, and request-body values. Never print an unredacted --curl into agent logs unless the user specifically asks for it and accepts the credential and captured-data exposure.
• Treat GET/HEAD/OPTIONS replay as read-only only when the endpoint semantics support that assumption. Get explicit user approval before POST, PUT, PATCH, DELETE, or any operation that may mutate state. Non-interactive mutating replay requires --yes; the flag records approval in the command, it does not replace asking.
• Keep bridge binding on loopback unless the user explicitly requests and understands a broader bind address.
• A security scanner may flag Harpist because it starts a local network service, reads browser-captured authentication, and can replay live requests. Do not dismiss the warning. Explain which of those capabilities the current workflow will use.

Core Model

• Treat recordings as additive. A new recording should improve or refresh a profile, not erase useful endpoints from earlier recordings.
• Treat generated docs/contracts as cumulative best guesses for the profile.
• Treat captured auth as first-class replay material. The normal way to inspect an endpoint is bunx harpist auth replay ... --redacted-curl. Execute the request only when live API access is needed and consented to. In a terminal Harpist prompts for missing site, operation, input, and mutating-request confirmation by default; use --param, --query, --body, or --json for scriptable path/query/body input.
• Treat the latest recording as the freshest source of credentials, and the per-host credential ledger as their history. bunx harpist auth list <host> shows every captured credential set (browser session cookies, API keys, bearer tokens) with capture time, expiry, and validation status. Replay defaults to the newest or pinned set; pass --auth <credentialId> to replay with an older one.
• If current credentials are missing, expired, or invalid, run bunx harpist auth login <host>. When the extension is available it opens the login page and records the sign-in automatically (stopping itself once fresh credentials are observed); otherwise it opens the login page in the user's browser and waits for them to sign in and add a recording manually. Either way the command confirms when fresh credentials sync. bunx harpist auth check <host> validates stored credentials against a recorded GET endpoint and records the result.
• Do not ask the user to manually copy cookies out of DevTools unless Harpist has failed to capture replay material.
• Keep Harpist source provider-agnostic. Do not add website-specific hostnames, product names, path semantics, auth quirks, or copy to the extension, bridge, CLI, or generic refiner.
• Put provider-specific understanding in the profile you write through the bridge: endpoint annotations, generated OpenAPI/oRPC artifacts, profile notes, and docs descriptions.
• Keep the order strict: run the generic refine first, then perform the skill documentation pass. Running refine latest after the docs pass will overwrite polished descriptions with neutral drafts, so run the docs pass again if you refine again.

Documentation Standard

• Take visible care with generated docs. Do not ship placeholder prose such as "included because it has an API-shaped host or path" as user-facing endpoint documentation.
• Give every included endpoint a specific purpose statement inferred from path, method, host, request body, response shape, auth/access metadata, and surrounding workflow.
• Keep descriptions short, concrete, and operational: what the endpoint does, whose/account state it touches, and whether replay uses captured browser credentials or a captured request body.
• Keep docs navigation quiet. Avoid long operation-id chips, repetitive badges, and internal classification labels unless they directly help a user choose or replay an endpoint.
• Preserve technical metadata under x-harpist, tags, operation IDs, and artifacts for agents, but do not let those internals dominate the human docs.
• Before handing back refined docs, inspect at least a representative sample of the rendered OpenAPI/Scalar output and fix repeated descriptions, ugly labels, stale endpoints, and misleading auth/replay claims.
• The skill is responsible for the documentation pass. The built-in refiner may produce neutral drafts; you must improve them through bridge writes before calling the docs refined.
• When a site needs bespoke interpretation, write that interpretation into the profile/artifacts for that host. Never patch generic Harpist code with that site's details.
• Every documented operation should have a distinct summary, a distinct useful description, and replay material available through auth.replay, bunx harpist auth replay, or the Scalar Harpist auth curl example.

Workflow

Before substantive Harpist work, tell the user which Harpist CLI version you are using when known.

If the user pasted a Harpist agent prompt (formerly called a handoff packet), treat it as recording context and proof that they already clicked Copy agent prompt. Never ask them to click it again. The button copies text to the clipboard; it does not transfer the recording. Still follow this workflow, including starting or reusing the bridge as allowed by the current environment and the user's service-management preferences.

1. Start or reuse the bridge.

   • Check http://127.0.0.1:4277/health first. If it is already healthy, reuse it.
   • If a healthy bridge reports startedBy: "agent", it is safe to reuse it.
   • If a healthy bridge reports startedBy: "user" or omits startedBy, treat it as user-managed. Reuse it, but do not stop or restart it without asking.
   • If no bridge is running, it is now your responsibility to start it locally yourself with bunx harpist bridge --agent --idle-timeout 15m.
   • You MUST escalate your invocation of bunx harpist bridge --agent --idle-timeout 15m outside of your sandbox so that it can reach the user's browser extension cache. It is OK to run this outside of your sandbox. Your permissions system will deal with asking the user to allow this.
   • Wait for http://127.0.0.1:4277/health to return OK.

2. Ask the user to open the Harpist popup if the latest extension recording has not appeared yet.

   • The extension syncs its recording outbox automatically when it detects an active bridge.
   • Pending recordings retry in the background. After starting a bridge, allow about 30 seconds for a retry before involving the user.
   • Copy agent prompt only copies context to the clipboard. It does not sync or push data.
   • If the recording still has not appeared, ask the user to open the popup for an immediate state refresh.
   • Do not assume the bridge can read Chrome extension storage directly.

3. Choose the target profile.

   • Default to the active tab host when the user names or implies a website.
   • Otherwise use the most recent profile: bunx harpist profiles latest.
   • If multiple hosts are plausible, ask the user which host to refine.

4. Run the built-in first-pass refinement unless the user explicitly asks for inspection only.

   • Use bunx harpist refine latest <host>.
   • If no host is specified, use the same command without the host.
   • This command writes endpoint inclusion annotations, auth bundle status, neutral draft oRPC/OpenAPI artifacts, and marks the latest recording processed.
   • Keep useful endpoints from previous recordings unless there is strong evidence they are noise, static assets, telemetry, or third-party vendor traffic.
   • Exclude endpoints whose only sampled responses are HTML access/error pages, even if the URL path looks API-shaped.
   • If the profile reports Recapture auth, ask the user to click Add recording on the target site while signed in, then run refinement again.
   • Treat this output as a draft. Do not stop here unless the user explicitly asked only for a generic sweep.

5. Inspect the latest recording and profile when deeper work is needed.

   • Write large payloads directly to files: bunx harpist profiles get <host> --output <path> and bunx harpist recordings latest <host> --full --output <path>.
   • Read those files with bounded local tools such as jq, rg, or targeted ranges. Do not print a large profile/recording to CLI stdout; tool output caps can truncate JSON mid-string.
   • Do not bypass the supported CLI by calling raw bridge HTTP solely to avoid output truncation.
   • oRPC: profiles.get, recordings.latest, recordings.get, handoff.get.

6. Refine the profile further through bridge writes.

   • Start with bunx harpist auth replay ... --redacted-curl. After the user approves live access, execute the replay; pass --yes only for an approved non-interactive mutation.
   • Prefer replaying by templateKey or operationName; do not reconstruct auth headers by hand.
   • If replay returns 401/403 or warns about expired credentials, run bunx harpist auth check <host> --all to see which stored credential sets still work, replay with a working one via --auth <credentialId> (pin it with bunx harpist auth use <host> <credentialId>), or capture a fresh session with bunx harpist auth login <host>.
   • If replay warns that the captured sample was a 4xx/5xx HTML error page, exclude or downgrade that endpoint instead of presenting it as a healthy API.
   • If replay fails with no sample, keep the endpoint documented but ask for a recording of that workflow.
   • Rewrite endpoint summaries/descriptions into human documentation with endpoints.annotate and/or profiles.setArtifacts.
   • Prefer the CLI apply/review loop when shell access is available:
     • Write a temporary JSON payload with host, optional agentNotes, optional lastBridgeMessage, and an endpoints array.
     • Each endpoint item must identify the endpoint with templateKey when possible, then provide summary, description, and useful tags.
     • Apply it with bunx harpist docs apply <host> <docs.json> or bunx harpist docs apply <host> -.
     • Review it with bunx harpist docs review <host> and fix every issue before reporting success.
   • The docs JSON is allowed to contain provider-specific interpretation. Harpist source code is not.
   • Use profiles.setAuth only for higher-level authentication analysis notes.
   • Use endpoints.annotate for prose/tags. Use bunx harpist endpoints upsert <host> <endpoint.json|-> to correct endpoint identity (exactKey, template, or templateKey) and bunx harpist endpoints remove <host> <templateKey> to remove a wrongly merged endpoint. The endpoint JSON must keep exactKey and templateKey consistent with its uppercase method, host, path, and template. These decisions persist across later extension syncs and mark artifacts as drafts.
   • Use profiles.setArtifacts to write generated oRPC/OpenAPI/CLI artifacts.
   • Use recordings.markProcessed when a recording has been fully handled.

7. Review before handoff.

   • Run bunx harpist docs review <host>.
   • The review must be ok: true before you call the docs refined.
   • If summaries or descriptions repeat, rewrite them.
   • If placeholder text remains, rewrite it.
   • If replay material is missing, either use the older sampled recording, keep the endpoint documented with a clear caveat, or ask for a new recording of that workflow.
   • If useful endpoints appear to be missing after a pass, inspect previous recordings/profile endpoints before removing them; recordings are additive.

8. Return concise user-facing output.

   • Say which host was refined.
   • Summarize endpoint/auth/artifact changes.
   • Mention the docs URL when an OpenAPI artifact exists: http://127.0.0.1:4277/profiles/<host>/docs.
   • Mention bunx harpist auth replay [host] [operationName-or-templateKey] when the user wants a terminal command.
   • Do not call docs "done" if the descriptions are repeated, vague, or visually noisy.

Useful Commands

bunx harpist bridge [--agent] [--idle-timeout <duration>]
bunx harpist version
bunx harpist purge
bunx harpist profiles list [--output <path>] [--force]
bunx harpist profiles latest [host] [--output <path>] [--force]
bunx harpist profiles get <host> [--output <path>] [--force]
bunx harpist recordings latest [host] [--full] [--output <path>] [--force]
bunx harpist recordings get <host> <id> [--full] [--output <path>] [--force]
bunx harpist refine latest [host]
bunx harpist auth replay [host] [templateKey|operationName] [--auth <credentialId>] [--param k=v] [--query k=v] [--body <json>] [--json <input>] [--interactive|--no-interactive] [--curl|--redacted-curl] [--verbose] [--yes]
bunx harpist auth list [host] [--json]
bunx harpist auth use [host] [credentialId|--clear]
bunx harpist auth check [host] [credentialId] [--all] [--json]
bunx harpist auth login [host] [--url <url>] [--no-open] [--no-wait] [--timeout <duration>]
bunx harpist auth set-login-url [host] [url]
bunx harpist endpoints upsert <host> <endpoint.json|->
bunx harpist endpoints remove <host> <templateKey>
bunx harpist contract-profile get <host> [--output <path>] [--force]
bunx harpist contract get <host> [--output <path>] [--force]
bunx harpist openapi get <host> [--output <path>] [--force]
bunx harpist docs <host>
bunx harpist docs apply <host> <docs.json|->
bunx harpist docs review <host>
bunx harpist handoff [host]

Contract Surface

Bridge methods exposed by the contract:

• bridge.health
• profiles.get, profiles.latest, profiles.list, profiles.setArtifacts, profiles.setAuth, profiles.update
• recordings.get, recordings.ingest, recordings.latest, recordings.list, recordings.markProcessed
• endpoints.annotate, endpoints.remove, endpoints.upsert
• auth.credentials, auth.replay, auth.useCredential
• commands.complete, commands.pull
• handoff.get
• sync.pullExtensionState, sync.pushExtensionSnapshot, sync.pushExtensionRecordingChunk, sync.restoreExtensionProfile

The bridge is the canonical cache while active. The extension remains the recording UI and local outbox.