How to let Claude Code debug a web page

Command

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Intermediate5 min readNeedsNodeChrome

What you’ll set up: debugging a web page normally means a person clicking around a browser — an agent can’t do that. cckit debug exposes the same browser tools (screenshots, accessibility snapshots, console and network logs, Lighthouse) as plain commands an agent can run and read. Output is TOON-encoded, so results stay small in the agent’s context.

Steps

1. Check availability first. cckit is pure bash; the browser bridge needs Node and Chrome. Check without running anything:

   cckit debug --check

   If Node/npx and Chrome are present, cckit debug drives the bridge. Otherwise it prints how to enable it and exits 0 — an unattended run is never hard-failed by a missing optional tool.

2. Enable the bridge. Install chrome-devtools-axi, or rely on npx if Node is present:

   npm i -g chrome-devtools-axi      # or: npx -y chrome-devtools-axi

3. Let the agent drive it. Everything after cckit debug is forwarded verbatim to the bridge, so the agent can take a screenshot, read the console, or run Lighthouse and act on the result:

   cckit debug <axi-args...>         # passed straight through — see the axi docs

How it works

cckit debug wraps chrome-devtools-axi (by Kun Chen), a self-contained Chrome DevTools bridge for agents. cckit only auto-detects and forwards to it — it never tracks the bridge’s evolving subcommand surface, so args pass straight through. Because it’s optional and auto-detected, a missing Node or Chrome degrades cleanly to a 0 exit with instructions rather than breaking a run.

Pin or wrap the command

Override what cckit invokes with export CCKIT_AXI=<command> — useful for a pinned version or a wrapper script.

Troubleshooting

cckit debug --check says it’s unavailable. Node/npx or Chrome is missing. Install Node and Chrome, then re-check; cckit won’t hard-fail without them.

The agent’s context filled with output. Results are TOON-encoded to stay compact, but a broad capture (full network log) is still large. Ask for the specific artifact — one screenshot, the console only — rather than everything.

A subcommand isn’t recognized. cckit forwards args verbatim to the bridge; the subcommand surface is the bridge’s, not cckit’s. Check the axi docs.

Related tutorials

Extend Claude Code with cckit skills The skills that package repeatable jobs.

Take a GitHub issue to a merged PR Ship the fix once you've found the bug.

Set up cckit in a repo Get cckit running before you debug.