QuokkaPix agent guide

QuokkaPix is a browser-only image editor. Agents should use the page through browser automation or the in-browser window.QuokkaPixAgent API. There is no server processing API; image files must be uploaded through the browser and are processed locally. The architecture article Building a Browser-Local Image Pipeline That AI Agents Can Actually Use explains the design tradeoffs behind the browser runtime, local MCP adapter, result manifest, QA surface and benchmark.

Discovery

• llms.txt
• agents.md
• agent-manifest.json
• ARD ai-catalog.json
• Browser compatibility matrix
• Browser benchmark
• Architecture article
• QuokkaPix editor

Flow

1. Open the editor with agent=1 and the desired hash parameters.
2. Upload image files through [data-agent="file-picker"] or [data-agent-action="upload"].
3. Wait for .page-shell[data-agent-status="ready"].
4. Start with [data-agent="process-trigger"] or window.QuokkaPixAgent.start().
5. Poll .page-shell[data-process-status] or call window.QuokkaPixAgent.getState().
6. Wait for done, error or cancelled.
7. Download via [data-agent="download-link"][data-status="ready"] or [data-agent="zip-download-link"][data-status="ready"].

Runtime API

window.QuokkaPixAgent.getContract()
window.QuokkaPixAgent.getState()
window.QuokkaPixAgent.getResultManifest()
window.QuokkaPixAgent.listRecipes()
window.QuokkaPixAgent.listRuleProfiles()
window.QuokkaPixAgent.getRuleProfile(id)
window.QuokkaPixAgent.getRecipe(id)
window.QuokkaPixAgent.validateRecipe(recipeOrId)
window.QuokkaPixAgent.applyRecipe(recipeOrId)
window.QuokkaPixAgent.applySettings(payload)
window.QuokkaPixAgent.buildUrl(payload)
window.QuokkaPixAgent.start()
window.QuokkaPixAgent.cancel()
window.QuokkaPixAgent.clear()
window.QuokkaPixAgent.getPaymentPolicy()
window.QuokkaPixAgent.setUnlockToken(token)
window.QuokkaPixAgent.verifyUnlockToken()
window.QuokkaPixAgent.clearUnlockToken()
window.QuokkaPixAgent.getEvents()
window.QuokkaPixAgent.clearEvents()

Experimental WebMCP

When the browser exposes the draft document.modelContext.registerTool API, QuokkaPix registers browser-native WebMCP tools. This is an experimental layer, not a server MCP endpoint. If WebMCP is unavailable, use window.QuokkaPixAgent and stable data-agent selectors.

The registered tools include quokkapix.get_result_manifest. After a terminal run status, call window.QuokkaPixAgent.getResultManifest() to receive source and output metadata, warnings, capabilities and a stable error code without parsing UI text. The manifest exposes agent-friendly top-level fields such as tool, mode, source, outputs[], processingMs, capabilities, optional capabilities.backends and errorCode, while keeping the legacy nested input, output and run fields. Official recipes can include an expectedResult.qa contract; the local MCP runner and browser getResultManifest() validate downloaded or current results against it and return machine-readable qa.ok, checks, warnings, failures and remediation hints. Sourced marketplace and social rule profiles are available at /rules/index.json and through window.QuokkaPixAgent.listRuleProfiles() / window.QuokkaPixAgent.getRuleProfile(id).

QuokkaPix prefers browser-loaded advanced encoders for JPEG, PNG optimization, WebP, AVIF and experimental JPEG XL when those encoders are available. Normal browser formats fall back to Canvas export if an advanced encoder cannot load. JPEG XL has no Canvas fallback; a JXL run fails rather than creating a mislabeled file.

Compatibility and recipes

Compatibility test verifies the public runtime API, selectors, status surface, backend routing capability, formats and payment contract without an upload. The browser compatibility matrix explains runtime-dependent formats, workers, planned backend routes, WebGPU/CPU paths, PDF tools and ZIP import. The browser benchmark publishes repeatable measurements for image, batch, PDF and local background AI workflows plus the measured Canvas, Worker, WASM, ONNX CPU and WebGPU backend matrix. Agents should still call window.QuokkaPixAgent.getState().capabilities in the current browser session. The recipe catalog is available at /agent-recipes/index.json and sourced QA rule profiles are available at /rules/index.json. Ready JSON recipes are available in /agent-recipes/ for Amazon, Shopify, Google Merchant, Etsy, eBay, Walmart, TikTok Shop, Temu, Shopee, Mercado Libre, Allegro, Newegg, Meta Catalog, Flipkart, SHEIN, Snapchat ads, website WebP compression, general WebP batches, white-background product batches, single-image compression, single-image background removal, single-image metadata cleanup, single-image watermarking, images-to-PDF, social output packs, avatar packs, watermark batches, favicon/app icons and metadata-clean batches.

Batch ZIP import is supported for uploaded .zip files. The archive is unpacked locally in the browser and supported image files inside it are added to the batch queue; RAR and 7z are not accepted. PDF tools are separate from image conversion: use tool=pdf&pdf-tool=merge|split|extract for uploaded PDF files. tool=pdf defaults to split. Split and extract are single-PDF workflows because page numbers refer to one source PDF; selecting either one switches the editor to single-file mode. Merge is a batch workflow because it combines multiple PDFs and switches the editor to batch mode. Split returns a ZIP of one-page PDFs, extract returns one PDF with the selected pages by default, and merge returns one PDF in the current browser file order. Use pdf-pages=1,3-5 for extraction; page order is preserved, so pdf-pages=3,1 exports page 3 before page 1. Use pdf-extract-output=zip to return extracted pages as separate one-page PDFs inside a ZIP. Human users can reorder merge files in the UI; agents should upload merge files in the desired order. pdf=1 remains the image-to-PDF path for uploaded images.

The source package also includes mcp-runner/ for local MCP clients such as Claude Desktop, Cursor and LM Studio/Ollama wrappers. It exposes list_recipes, get_recipe, validate_recipe, list_rule_profiles, get_rule_profile, validate_result_manifest, process_images, process_with_settings, get_payment_options, explain_payment_flow and verify_unlock_token. It opens QuokkaPix in a local browser and does not create a public server-side processing API. See QuokkaPix MCP Runner and the GitHub repository. The npm package is quokkapix-mcp and can be started with npx quokkapix-mcp. The runner is also listed on Glama and mcpservers.org. The MCP runner also accepts optional watermarkLogoFile and backgroundImageFile local asset paths, uploaded through the browser's watermark/background file inputs. Custom workflows can use steps: [{ tool, settings }] for per-tool scenario settings.

Remote MCP and local bridge

Cloud MCP clients can connect to https://quokkapix.com/mcp over Streamable HTTP and OAuth authorization code with PKCE. Execution still requires the existing npm package on the user's computer. The mcp:tools scope permits read tools; processing and unlock staging additionally require bridge:execute:

npx quokkapix-mcp bridge --input-root /path/to/input --output-root /path/to/output

The bridge accepts only relative paths inside those explicit roots. The control plane relays tool settings, relative file names, status and result metadata; it has no image upload endpoint and does not relay source or output image bytes. Remote coordination adds get_bridge_status, get_billing_status and set_unlock_token. Existing x402 limits remain unchanged, and the local browser consumes a paid unlock only when processing starts. Running the bridge with --reset revokes the old device authorization and refresh grants before pairing a replacement.

quokkapix.get_contract
quokkapix.get_state
quokkapix.get_result_manifest
quokkapix.get_payment_policy
quokkapix.list_recipes
quokkapix.get_recipe
quokkapix.validate_recipe
quokkapix.apply_recipe
quokkapix.apply_settings
quokkapix.set_unlock_token
quokkapix.start
quokkapix.cancel

await page.goto("https://quokkapix.com/#agent=1");
await page.evaluate(() => window.QuokkaPixAgent.applyRecipe("shopify_product_pack"));
await page.locator('[data-agent="file-picker"]').setInputFiles(files);

quokkapix.start is a state-changing action. Single-image runs, single-image scenarios and agent batches up to 5 files are free. Larger agent batch/scenario runs may require and consume a paid x402 unlock token when processing starts.

Agent payments

Human UI, reward ads and normal user workflows are unchanged. Payments apply only in agent=1 mode. Single image agent runs, single image scenarios and agent batches up to 5 files are free. Agent batch or batch scenario runs from 6 to 50 files cost 0.01 USDC.

• Options: /api/agent-payment/options
• Coinbase x402 unlock: /api/agent-unlock/coinbase-x402
• Verify: /api/agent-unlock/verify
• x402 schema and error contract: /x402-api.md

Paid unlock endpoints return a short-lived unlockToken. The token unlocks an agent batch/scenario run in the browser; image files are still uploaded through the browser file input and are not sent to a QuokkaPix processing server.

Stable selectors

[data-agent="file-picker"]
[data-agent="process-trigger"]
[data-agent="cancel-trigger"]
[data-agent="download-link"]
[data-agent="zip-download-link"]
[data-agent="preview-link"]
.page-shell[data-agent-status]
.page-shell[data-process-status]

Playwright recipe

await page.goto("https://quokkapix.com/#agent=1");
await page.locator('[data-agent="file-picker"]').setInputFiles(files);
await page.locator('.page-shell[data-agent-status="ready"]').waitFor();
await page.locator('[data-agent="process-trigger"]').click();
await page.locator('.page-shell[data-agent-status="done"], .page-shell[data-agent-status="error"], .page-shell[data-agent-status="cancelled"]').waitFor();
const state = await page.evaluate(() => window.QuokkaPixAgent.getState());
if (state.status !== "done") throw new Error(state.error || state.status);

For a paid batch, obtain and set the x402 unlock token before Start. Download only after the stable download selector has data-status="ready".

Capabilities

Agents should read window.QuokkaPixAgent.getState().capabilities before choosing formats or background/GIF workflows. It exposes current browser export formats, worker support, background model status, heavy mode support, GIF limitations and file limits.

The optional additive capabilities.backends object reports the planned processing, encoding and background-AI routes for the selected workflow, including explicit fallbacks. It is advisory; terminal status and the result manifest remain the source of truth for success.

For Background AI, use background-quality=standard by default. Agents can choose fast for large batches or quality for a larger lazy-loaded model on difficult edges.

The same object includes capabilities.memory with selected file count, input bytes, decoded megapixels, weighted megapixels, estimated decoded bytes, warning, risk, reasons and recommendedBatchSize. Agents should reduce batch size when warning is true or risk is medium/high. QuokkaPix releases intermediate canvas buffers during main-thread and worker pipelines, but browser RAM remains the hard limit for large local jobs.

Analytics

Agent events are stored locally and sent to Google Analytics through gtag when it is available. Events do not include file names, local paths, image contents or user-entered text.

Examples

https://quokkapix.com/#agent=1&tool=compress&quality=80&format=webp
https://quokkapix.com/#agent=1&mode=batch&tool=resize&resize-mode=fit&w=1200&h=1200&format=webp
https://quokkapix.com/#agent=1&mode=batch&tool=constructor&steps=resize|compress|convert&w=1600&quality=78&format=webp
https://quokkapix.com/#agent=1&tool=convert&format=jxl
https://quokkapix.com/#agent=1&tool=pdf&pdf-tool=extract&pdf-pages=1,3-5