π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
Mimik
Mimik records a workflow and turns each action into a step: a screenshot, the element acted on and a description. The guide can then be edited, replayed on a live page (Guide Me) or exported. There are two surfaces with one codebase, a Chrome extension and an Electron desktop app for Windows and macOS.
Everything runs on the user's machine. There is no backend, account or telemetry. AI is optional and uses the user's own key. Never add a request that sends user data anywhere except the provider the user chose.
Layout
apps/extension/src/ the extension (WXT): entrypoints, capture, blur, guideme, lib, ui
apps/desktop/src/ Electron: main, preload, renderer
packages/core/src/ logic both surfaces share: capture, guides, export, screenshot, blur, i18n
packages/ui/src/ React both surfaces share, grouped by feature
packages/locales/ the translations both surfaces read
packages/capture-native/ Rust napi addon: accessibility lookup and input hook, Windows and macOS
scripts/ repository checks run by pnpm lint
apps/extension, apps/desktop, packages/core and packages/capture-native each have their own AGENTS.md.
Read it before working there.
Commands
pnpm dev extension, hot reload (pnpm dev:firefox for Firefox)
pnpm build extension build
pnpm dev:desktop desktop app
pnpm pack:desktop unpacked desktop app in apps/desktop/dist
pnpm test vitest, all packages
pnpm lint biome, the repository checks, jscpd and knip
pnpm size extension bundle sizes, after pnpm build
pnpm typecheck root and desktop
pnpm --filter @mimik/desktop check:pipeline also check:storage, check:overlay, check:capture
pnpm --filter @mimik/capture-native build
Before calling work done, run lint, typecheck and test. If you touched apps/desktop or desktop
capture code in core, also run the desktop checks (under xvfb-run on Linux).
Rules
packages/belongs to both surfaces. It never imports from an app (@/lib,@/ui,@/entrypoints,#imports,apps/). Biome enforces this. If you have to ask which surface owns a file there, it belongs in that app instead.- Behaviour that differs by surface: shared code that decides for itself asks
client()from core. Behaviour only the app can supply comes in as a prop. Services every screen needs (opening a tab, the AI calls, app icons) come fromconfigureUiin@mimik/ui/env, typed, never as named messages. - Reuse the extension. A feature both surfaces have uses the extension's component, wording and placement, and the desktop gets every branch of it, not a subset.
- Same names for the same thing on both surfaces:
- the capture states and events from core's machine;
isLive;- message and IPC names where both surfaces have the message (
captureStep,discardRecording,getState); - the insert fields (
insertTargetGuideId,insertAtIndex); - the narration phases (
VoicePhase). Different code is fine where the platforms differ; different words for the same concept are not.
- One export per file, named, with the file named after it. A component file has no helpers. A
hook or a
lib/function may keep one private helper. There are no default exports except where a framework reads them, and no re-exports outsidepackages/ui/src/index.ts. The second half ofpnpm lintchecks all of this. - Imports from
@mimik/ui: apps import from its entry only, plus@mimik/ui/env,@mimik/ui/global.cssand@mimik/ui/common/lib/mascot-shapes. Inside the package, imports are relative. - No comments in source, except pragmas and directives the toolchain reads.
- Every user-facing string goes through i18n and gets a translation in every file under
packages/locales/. - Colours: the interface is navy and lavender, with tokens in
packages/ui/src/global.css. The indigo#4F46E5is only for marks drawn over other people's pixels and for the mascot. - Baseline snapshots (
blur-baseline,naming-baseline) pin what Smart Blur hides and how steps are named. Re-record them withvitest -uonly for a deliberate change in behaviour. - Privacy invariants:
- A narration transcript never goes into an export or a
.mimikfile. - A password value is never read or stored.
- A screenshot leaving the app goes through the renderer, so blur is burned in.
- A narration transcript never goes into an export or a
Intentional differences
These are platform differences, not drift. Do not "fix" them:
- Starting: the desktop has an
ARMEDstate (the card waits for Start), capture modes and an area editor. The extension starts recording at once in the current tab. - Where state lives: the extension's background worker is evicted when idle, so its machine is
saved to
sessionStorage. The desktop's main process is never evicted. - Messages: the extension has tab, URL, blur and Guide Me messages. The desktop has none of these.
- Writing steps: the extension's worker writes them. On the desktop, main asks the renderer to write them, because IndexedDB lives in the renderer.
- Typing: the extension writes a typing step on the first key and updates it. The desktop writes it once, when typing stops.
- Screenshots: stored as a
Blobin the extension and as a PNG file with asrcon the desktop. - Fallback titles: "Guide on " in the extension, "Guide in " on the desktop.
- Extension only: Smart Blur and Guide Me need a live page.
- Settings:
recordKeysandrecordTypingare core settings in the extension and live incapture-settings.jsonon the desktop, because the desktop's main process reads them. The typing delay is desktop only: the extension closes a typing step on Enter or when the field loses focus. - Live updates: the card hears about step changes from main. The side panel re-reads the database.
Commits and PRs
- Conventional commits, subject line only, no body.
- The human contributor authors commits. Never set an AI as the author and never add
Co-Authored-By,Assisted-by,Generated-byor session-link trailers. AI use is disclosed only on the PR template's "AI model(s) used" line. - PR descriptions are short prose, written by you. See
CONTRIBUTING.md, "Using AI Tools". - Never name another product or company in code, commits, PRs or docs.