DEV Community: Aryan Duntley

Stop being your AI's eyes and hands: pwa-debug lets Claude debug your live, logged-in browser

Aryan Duntley — Wed, 04 Nov 2026 01:50:20 +0000

If you've debugged a web app with an AI assistant, you know the loop:

The AI asks what the console says. You copy and paste it.
It asks what the component's state is. You open React DevTools and describe it.
It asks you to click the button and report what happens. You click it.
It asks for a screenshot. You take one.

You end up as the AI's eyes and hands. That's slow, it loses information, and it doesn't work at all for the bugs that hurt most in PWAs: stale caches, service workers that won't update, install failures, and version skew after a deploy.

I built pwa-debug to remove that loop. It's an open-source (MIT) MCP server plus a browser extension that gives an AI agent like Claude Code direct, structured access to your live, logged-in browser. That covers the DOM, console, network, framework state, store state, service workers, caches, and storage, and the agent can also interact with the page.

npx -y @aryanduntley/pwa-debug@latest

📦 npm: @aryanduntley/pwa-debug
🐙 GitHub: aryanduntley/pwa-debug-layer

The questions it answers

These are the PWA problems people search for most. pwa-debug answers them by reading the runtime directly, without screenshots or OCR:

You ask	The agent calls
Why won't my service worker update? Why are some users on old code?	`sw_status`, `pwa_update_analyze` (waiting-vs-active versions, version-skew verdict)
Why is my cache stale? Why are chunks 404ing after a deploy?	`cache_list` / `cache_inspect` / `cache_match` (entries with age, size, cache-control)
Why won't my PWA install?	`pwa_installability` (structured `{ gaps[], fixes[] }`, not just "manifest invalid")
What's actually in IndexedDB right now?	`idb_list` / `idb_query`, `storage_get`
Why does this component have the wrong state?	`react_get_state`, `vue_get_state`, `store_get_state`, `redux_get_state`
Does anything break at 360px, in dark mode, in Spanish?	`layout_sweep` (one call, every page × width × scheme × state)

Highlights

🔐 It runs in your real browser profile

Google's chrome-devtools-mcp is great, but it starts a fresh automated Chrome. That browser has none of your cookies, sessions, or extensions, and none of your real service-worker state. If your app sits behind a login, that's a problem.

pwa-debug attaches to your normal profile by default, so the agent sees what you see: authenticated sessions, your real SW and cache state, and your extensions.

⚛️ Framework and store state that CDP can't reach

A script injected into the page's MAIN world reads each framework through its own devtools hooks:

React fiber tree, props, state, and hooks
Vue 3 component tree and reactive state
Svelte components with source locations
Solid detection and element lookup
Redux, Zustand, Pinia, Jotai: read, subscribe to change deltas, and (opt-in) dispatch

Every framework also supports find-by-text and find-by-role, so the agent can locate "the Submit button inside <CheckoutForm>" without guessing selectors.

🛠️ The full PWA diagnostics suite

This is the part the project is named for. It covers service-worker lifecycle and versions, CacheStorage contents and age, installability gaps with per-gap fixes, a live capability matrix (Push, Background Sync, Periodic Sync, Badging, File System Access, Window Controls Overlay), IndexedDB and web storage, and pwa_update_analyze. That last tool combines SW status, cache ages, and recent 404s into a verdict such as "cached HTML is older than the JS it references", which is the classic cause of "why are some users on old code."

pwa_snapshot produces one capped blob of the whole runtime state, which is useful for repros and bug hand-offs.

👆 The agent drives the page itself

pdl_click, pdl_fill, pdl_submit, pdl_key_press, pdl_type_sequence, pdl_navigate, and pdl_new_tab are available, along with touch gestures: tap, double-tap, long-press, swipe, drag, scroll, and pinch. Events are dispatched as native-event sequences, so React's and Vue's delegated event systems fire properly. Targets use one locator format (selector, role, text, or a framework component id).

📱 Android phones over adb

The extension can't run in Android Chrome, so pwa-debug connects to phones over adb and CDP and injects the same page-world code there. One call does the setup:

pdl_android_attach({
  open_url: "http://localhost:5173",
  reverse_ports: [5173]      // phone's localhost:5173 → your dev server
})
→ { connectionId: "cdp:127.0.0.1:<port>:<tab>" }

After that, every page tool works on the phone tab, including React state, stores, PWA diagnostics, gestures, and console and network capture, and you can watch it happen on the device. I verified this live on a Galaxy S24 Ultra (Android 16, Chrome 156).

📐 Responsive layout sweep

One layout_sweep call goes through a matrix of pages × viewport widths × color schemes × app states (plus extra dimensions such as language). For each view it emulates the viewport over CDP and measures the page for:

horizontal page overflow and off-screen elements
tap targets below WCAG 2.2 minimums
clipped or ellipsized text (useful when testing longer translations)
fixed bars that aren't fully on screen
clipped focus and selection rings
unresolved copy like {{name}}, undefined, NaN, [object Object]
page errors during the view, plus optional WCAG AA contrast

It groups the results into distinct problems, so 150 raw findings that come from two root causes are reported as two groups, with screenshots if you ask for them. You can also pass your own custom_checks expressions. In the largest real test it swept an 83-page prototype across 4,812 views.

🔌 Library popups, replay, and source maps

WalletConnect, RainbowKit, and SDK modals that live in shadow roots or nested iframes can be recorded, replayed, and correlated with the console errors and failed requests that occurred while they were open (popup_failures).
rrweb session recording and replay, plus persistent ring buffers that survive navigations and reloads.
source_map_resolve maps minified stack frames back to src/file.ts:line:col.

🤖 Built for agents, not humans

Every tool returns { ok, data, error?, next_steps[] }. The next_steps field tells the agent what to call next based on the actual result, so it recovers from setup gaps and errors without you stepping in. pdl_help serves the whole usage guide as data, and filters keep each response to the slice the agent asked for instead of dumping the full DOM.

Works with chrome-devtools-mcp, doesn't replace it

pwa-debug is complementary to chrome-devtools-mcp, and the two tool sets don't overlap. pwa-debug launches a browser with a live debug port, and chrome-devtools-mcp attaches to that same port. Both then drive the same tab over separate channels: CDP for one, extension and page-world injection for the other.

pdl_launch_browser({ browser: "brave", mode: "sandbox-persistent" })
pdl_register_chrome_devtools()   // pins chrome-devtools-mcp to the right port for you

Getting started

As a Claude Code plugin (no clone, no build)

/plugin marketplace add aryanduntley/pwa-debug-layer
/plugin install pwa-debug@pwa-debug
/reload-plugins

Or with any MCP client

claude mcp add pwa-debug --scope user -- npx -y @aryanduntley/pwa-debug@latest

Then tell your agent:

Set up pwa-debug and open my app at http://localhost:5173.

The setup is agent-driven. It runs pdl_check_setup, registers the native-messaging host, launches a browser with the extension preloaded, and confirms the round-trip with session_ping. Each step's next_steps tells it what to do next.

Browser support: Chromium-family browsers (Chrome, Chromium, Brave, Edge, Vivaldi, Opera) and Android Chrome over adb. Brave and Chromium give the smoothest experience, because Google Chrome 142+ removed --load-extension and so needs one manual "Load unpacked" step.

How it works

Claude Code ──MCP──► Native host (MCP server, ring buffers, replay store)
                        │ native messaging
                        ▼
                     Extension service worker
                        │
          ┌─────────────┴──────────────┐
          ▼                            ▼
   Content script               Page-world script (MAIN world)
   DOM observe, actions         React/Vue hooks, fetch/XHR patch, stores

The extension handles the page: DOM, content scripts, and page-world hooks injected on every load.
The native host handles persistence and the MCP server.
MCP is the contract with the AI.

The whole codebase is TypeScript written in a strict functional style: pure functions, immutable data, no classes, and side effects kept at the edges.

Help wanted 🙏

Development happens on Linux, where everything is live-tested. The macOS and Windows code paths (browser detection, profile paths, native-messaging registration) are written and unit-tested but have never run on real hardware. If you're on a Mac or a Windows machine, trying it and opening an issue with the output would help more than anything else right now.

Firefox support is on the roadmap (via WebDriver BiDi). Stars, issues, and PRs are all welcome.

⭐ GitHub: https://github.com/aryanduntley/pwa-debug-layer
📦 npm: https://www.npmjs.com/package/@aryanduntley/pwa-debug

If you try it on a PWA bug, I'd like to hear how it went in the comments, whether it worked or not.

Stop Paying the Re-Discovery Tax: How AIMFP Manages Context for AI Coding Agents

Aryan Duntley — Wed, 04 Nov 2026 01:47:34 +0000

Every AI coding session starts the same way. The assistant lists directories, opens files, greps for function names, reads the README again, and slowly rebuilds a picture of the project it already understood yesterday. On a small repo that costs a minute. On a large one it eats a real share of the context window before any work starts, and the picture it builds is still incomplete.

I call this the re-discovery tax, and I built AIMFP (AI Modular Functional Procedural) to stop paying it.

AIMFP is an MCP server (pip install aimfp, or a Claude Code plugin) that gives the AI a persistent, structured database of the project: files, functions, types, call interactions, modules, tasks, decisions and notes. The AI keeps that database up to date as it works and reads from it in the next session, so it doesn't have to re-read the source tree.

This post covers what AIMFP is, then spends most of its time on the part I think is most useful to other people building agent tooling: how it manages context.

What AIMFP is, briefly

An MCP server with about 315 tools and 131 directives (step-by-step workflows), all stored in SQLite.
Four databases:
- aimfp_core.db is read-only and ships in the wheel. It holds directives, helper definitions, and the next-step guidance attached to each tool.
- project.db holds the project's state: files, functions, interactions, types, themes, flows, modules, completion paths, milestones, tasks and notes.
- user_preferences.db holds per-directive preferences and project settings.
- user_directives.db is optional. It's used for automation projects, where the AI generates code from rules you write in YAML/JSON.
An opinionated coding style: functional-procedural code with pure functions, immutable data, no OOP, and side effects isolated at the edges. This is deliberate. Pure functions with explicit inputs and outputs are much easier to index, and an accurate index is what makes the rest of the system work.
A modularity map. Every piece of work is placed on the map before it's written:

theme (stable project area)
  └─ flow (one behaviour, ≥ 1 theme)
       └─ files (declare their flows when reserved)
            └─ module (reusable domain code at a directory seam)

Completion paths move themes forward, milestones build flows, and tasks carry flow IDs. Feature files are thin orchestrators that compose module functions.

Local only. No network calls and no telemetry. All state lives in .aimfp-project/ inside your repo.

AIMFP also tracks its own development. Right now its own project.db holds 131 files, 1,303 functions, 2,920 call interactions, 16 modules, 20 flows, 9 themes and 74 completed tasks. Most of the design decisions below came from running into problems while using it on itself.

The core rule: the database is the index, source files are the last resort

AIMFP's system prompt says this directly: use DB tools before reading source files.

Instead of:

ls -R src/ → cat 12 files → grep "def calculate" → cat 3 more files

the AI calls:

get_function_by_name("calculate_total")
→ file, purpose, parameters (typed), returns, notes attached to it

get_interactions_by_function(fn_id)
→ what it calls, what calls it

Each answer is a short structured record instead of a file. The AI still opens source files when it has to edit them, but it opens them knowing what it's looking for.

The rule is the easy part. The harder part was keeping all of this from flooding the context window anyway. A database of 1,300 functions can bury the AI just as thoroughly as a source tree if every call returns everything. The rest of this post covers how AIMFP avoids that.

Context management, layer by layer

1. One call to start a session, with only the sections that need attention

The first action of every session is a single call:

aimfp_run(is_new_session=true)

It returns a session bundle: project purpose and goals, the active path, milestone and task, the flows and themes of that work, infrastructure, recently changed files (each tagged with its flows, themes and module), metadata for recent notes, recent history, user settings, watchdog status, and the reference material the AI needs to work.

The important part is what the bundle doesn't include:

Sections with nothing to report are dropped. A backup appears only if one was actually taken. A migration notice appears only if a migration is pending. A pure helper, drop_empty, removes every None and empty container before the payload goes out.
The full directive catalogue isn't bundled. There are 131 directives and 66 FP-style rules. The AI gets their names in its reference material and loads a directive's steps with get_directive_by_name(name) only when it's about to run it.
Coding-specific reference material is included only once there's code to write, meaning once a milestone exists. Before that, the next step is project discovery, and the core reference already covers it.

Here's a trimmed version of the bundle AIMFP returned for its own repo today:

{
  "position": {
    "path": { "id": 1, "name": "AIMFP Ongoing Development" },
    "milestone": {
      "id": 2, "name": "Features", "status": "pending",
      "flows": [
        { "id": 1, "name": "Session Lifecycle Flow", "themes": ["Helper / MCP Tools"] },
        { "id": 19, "name": "Tracking Audit Flow", "themes": ["Database Operations", "Helper / MCP Tools"] }
      ]
    }
  },
  "recent_files": [
    { "path": "src/aimfp/helpers/project/tasks.py",
      "flows": [{ "id": 4, "name": "Project Tracking Flow" }],
      "themes": ["Database Operations", "Helper / MCP Tools"],
      "module": "helpers_project" }
  ],
  "history": {
    "last_completed_task": { "id": 75, "name": "bump-version.py covers server.json (MCP Registry) versions" }
  },
  "watchdog": { "status": "ok", "reminders": [] },
  "deferred_notes": [{ "id": 103, "reference_table": "files", "reference_id": 96 }]
}

From this one payload the AI knows where the work is, what was done last, what's deferred, and which parts of the map are involved, without opening a single file.

2. Status in tiers, sized to how often each one is called

aimfp_status has three tiers, and the tier is chosen by call frequency, not by how much information exists:

Tier	When it's used	What it returns
`quick` (default)	Inside work loops, "where am I?"	Path, milestone, focused task with item names, its flows and themes, other open work, structure gap count
`summary`	After lost or compacted context	`quick` + purpose and goals, infrastructure, recent files with their map annotations, recent notes, history, active branches, core reference
`detailed`	Rarely	`summary` + the full work tree

Focused-work descriptions are capped at 300 characters in summary, and quick omits them entirely. The quick tier is the one that gets called many times per session, so it's the one kept smallest.

Compaction is handled explicitly. When the client compacts the conversation, the AI has lost details but the database hasn't. aimfp_status(type='summary') is the documented recovery call, and the Claude Code plugin's SessionStart hook matches startup|resume|compact so the AI is pointed back at AIMFP straight after a compaction.

3. Checkpoint calls that return nothing when nothing is wrong

During work the AI calls aimfp_run(is_new_session=false) at checkpoints. This call only returns watchdog alerts. If there are none, the data object is empty ({}).

That's an intentional design choice. A checkpoint that always returns a status block teaches the model to skim it. A checkpoint that's usually empty gets read when something does come back.

4. Instructions arrive just in time, not all at once

This is the part I'd most recommend to anyone building MCP tooling.

Most agent setups put every rule in the system prompt and hope the model remembers the relevant one at the right moment. AIMFP keeps the system prompt short. It sets the non-negotiable rules and the session-start call, and the detail lives in two places:

Directives in the database. A directive like project_task_decomposition or project_milestone_complete is a stored workflow with a main sequence, conditional branches and a fallback. The AI loads it by name right before running it. When the workflow is done, its steps can fall out of context without anything being lost, because they're still in the database.

Return statements on tool results. Every tool result can include return_statements, which are short next-step instructions defined per tool in aimfp_core.db. There are about 320 of them across the tool definitions. They're gated on the payload, so a statement is sent only when the key it refers to is present. For example, the bundle above included deferred_notes, so the result also included:

"data.deferred_notes lists deferred work (metadata only). Read the ones relevant to the
 current work with get_notes_comprehensive(note_id=X); resolved ones → update_note(note_type='completed')."

If there had been no deferred notes, the AI wouldn't have seen that instruction at all. When aimfp_run bundles sections owned by other tools, it attaches those tools' gated return statements too, and removes duplicates.

So the guidance the AI receives depends on the state of the project, not on everything it might ever need to know. Users can also attach their own return statements to any tool (set_custom_return_statement) if they want a specific behaviour every time that tool is called.

5. Short reads by default, full detail on request

Large reads are short by default, and the AI has to ask for full detail:

Milestone getters, get_all_flows and get_tasks_by_milestone return description: null unless the call passes detail_level='full'. They can also return task counts per status from a single grouped query, so getting an overview never requires writing SQL.
audit_tracking, which compares the database against the actual code, writes its full findings to a JSON file on disk and returns counts, a few samples per category (sample_limit, default 5), and the report path. The fix tool, apply_audit_fixes, reads that report from disk, so the full list of findings never has to pass through the context window.
search_notes returns capped previews. The AI reads a specific note in full only when it looks relevant.
Single-entity lookups (a file, function, type, flow or module) include references to attached notes rather than the note bodies.
Function parameters always come back in one normalized shape, a parsed list of {name, type, required, default, description, kind}. Records written by different sessions in different formats don't make the AI spend tokens working out which format it's looking at.

6. Show the part of the map the work touches

It would be easy to include the whole theme/flow/module map in every status call. AIMFP doesn't. From the status module's docstring:

Structure (themes, flows, modules) is attached to what the payload already shows. It is never listed whole: a full map every call is a list the AI has to sort for relevance itself, which buries the part that matters now.

So the active milestone comes with its flows, a recent file comes with its flows, themes and module, and the full map is a separate call (get_all_flows, get_structure_health) for when the AI actually needs it.

Structural gaps get the same treatment: flows without a theme, files without a flow, files outside their module, oversized flows. The watchdog turns them into one summary reminder with counts per gap type, not one reminder per gap.

7. A watchdog that keeps the index honest

None of this is useful if the database is wrong. A stale index is worse than none, because the AI trusts it.

When a session starts, aimfp_run launches a detached filesystem watchdog (the one runtime dependency is watchdog). It compares the database with what's on disk and records reminders for:

new files that aren't tracked
functions in the code that are missing from the database, and the reverse
deleted files
stale timestamps
audit drift and structure gaps

Before the first payload is built, the session-start call runs a synchronous reconciliation pass, so the first answer doesn't race the watcher. Checkpoint calls also link edited tracked files to whichever task is in progress. Edits made without a tracking call still appear in that task's context and in its completion audit.

8. Writes are what make reads trustworthy

All of the above saves tokens on reads only if the writes happen. AIMFP's write-side discipline is the file coding loop:

reserve file (with flow_ids) → search_modules for overlap → reserve functions + types
→ write the code → finalize file → assign to module
→ finalize functions + types (purpose, params, returns) → add interactions → link types to functions

AIMFP enforces this loop in a few ways:

Finalize gates. Finalizing rejects a function with no purpose, parameters or return value, and warns when the recorded parameters don't match the actual signature.
A completion gate. Marking a task complete audits the files linked to it against the code. If the drift is serious enough to block completion, the refusal includes the exact tool calls that fix it.
Plugin hooks. A PostToolUse hook on Write|Edit reminds the AI to track source files, and a Stop hook checks that aimfp_end ran when you said "wrap up".

The tracking work costs tokens. A continuation checkpoint is cheap (around 2k tokens), batch helpers like reserve_files and finalize_functions cut down on round-trips, and all analytics are opt-in. The trade is to spend a little on every write so the next session doesn't spend a lot re-reading. Past a handful of files, that trade pays for itself many times over.

What this looks like in practice

The user starts a session with "continue where we left off". The AI:

Calls aimfp_run(is_new_session=true) and reads the bundle.
Knows the active milestone, the focused task and its open items, which flows are involved, and that note #103 is deferred work on file #96.
Calls search_notes with the task's keywords to check for past decisions.
Uses get_function_by_name and get_interactions_by_function to find exactly what to change.
Opens only the files it's about to edit.
Writes the code, runs the tracking loop, marks items done, and completes the task through the audit gate.
If the conversation gets compacted halfway through, calls aimfp_status(type='summary') and carries on.

At no point does it list the source tree.

Lessons for anyone building agent tooling

Some of these apply whether or not you ever use AIMFP:

Pick payload size by call frequency. The call made fifty times a session should be the smallest one.
Leave out empty sections. Every empty key is something the model has to read and ignore.
Send instructions with the state they're about. Attaching guidance to tool results, gated on payload content, works better than a longer system prompt.
Keep full reports on disk and return pointers. Return counts, samples and a path, and let the fix tool read the file.
Show the relevant slice of the map, not the whole map.
Make "nothing to report" an actual empty result.
Plan for compaction. Have one documented call that rebuilds working context from durable state.
An index has to be enforced to stay accurate. Without gates and a watcher, it drifts out of date.

Caveats

FP only. AIMFP refuses OOP codebases. It's opinionated on purpose, since pure functions are what keep the index reliable.
Linux only. There's no platform-specific code, so other operating systems are untested, not just unsupported.
About 315 tools. Claude Code asks for approval on each MCP tool the first time it's used. get_claude_permissions produces an allowlist so that happens only once.
It depends on the AI following the process. Gates, hooks and return statements make that much more likely, but the system prompt is still what holds it together.
License: PolyForm Noncommercial 1.0.0 for every version after 1.66.1. Personal, research and educational use is free, and commercial use needs a license. Versions up to 1.66.1 remain MIT.

Try it

Claude Code (recommended): you need uv installed.

/plugin marketplace add aryanduntley/aimfp
/plugin install aimfp@aimfp

Then ask: "Add the AIMFP system prompt", followed by "Initialize AIMFP for my project".

Other MCP clients:

pip install aimfp
# register: python3 -m aimfp  (stdio transport)
python3 -m aimfp --system-prompt   # paste into your client's instructions

GitHub: github.com/aryanduntley/aimfp
PyPI: pypi.org/project/aimfp

I'd like to hear how other people are handling context in their agent setups, especially what you do after compaction. Let me know in the comments.