| name | d3k |
| description | d3k assistant for debugging web apps |
d3k Commands
d3k captures browser and server logs in a unified log file. Use these commands:
Viewing Errors and Logs
d3k errors
d3k errors --context
d3k errors -n 20
d3k logs
d3k logs --type browser
d3k logs --type server
Other Commands
d3k fix
d3k fix --focus build
d3k crawl
d3k crawl --depth all
Browser Interaction
d3k agent-browser auto-connects to the active session's browser via CDP:
d3k agent-browser open http://localhost:3000/page
d3k agent-browser snapshot -i
d3k agent-browser click @e2
d3k agent-browser fill @e3 "text"
d3k agent-browser screenshot /tmp/shot.png
To target a different browser, run d3k agent-browser connect <port> first.
Codex Fresh Browser/Profile Startup
Use this workflow when the user asks Codex to start d3k with a fresh browser/profile.
-
Close any stale agent-browser daemon before launching with --profile. Otherwise agent-browser will reuse the existing daemon and print --profile ignored.
d3k agent-browser close --all
-
Start the app through d3k in servers-only mode and keep that command running. In Codex, this is more reliable than asking d3k to launch the browser itself when a fresh profile is required.
d3k --no-agent --no-skills --servers-only --command "npm run dev -- -H 127.0.0.1 -p 3000" --port 3000 --startup-timeout 90 --no-tui
Adjust the package-manager command and port for the project. Prefer --command over --script when passing framework flags. For npm scripts, put flags after --; otherwise tools like Next.js can interpret the port as a project directory.
-
Verify the server before opening more browser windows:
curl -I http://127.0.0.1:3000
-
Open the fresh profile as a separate browser step:
d3k agent-browser --profile /tmp/d3k-fresh-profile --headed open http://127.0.0.1:3000
-
Sanity-check the opened page:
d3k agent-browser get title
d3k agent-browser snapshot -i
d3k errors
Practical rules:
- Prefer
127.0.0.1 for this workflow. If localhost hangs or flips between IPv4/IPv6 behavior, do not keep retrying browser launches.
- If
curl -I hangs, the server is wedged even if the port appears occupied; restart the d3k server process before opening a browser.
- In
servers-only mode there is no d3k-monitored CDP browser. Use regular d3k agent-browser commands, not d3k cdp-port.
- In sandboxed agent environments, rerun local-network checks and
agent-browser opens outside the sandbox when sandbox networking blocks access to 127.0.0.1.
Browser Tool Choice
Use agent-browser for browser work.
Practical rule:
- Need to drive the same monitored browser session: use
agent-browser.
- Examples:
d3k agent-browser snapshot -i
d3k agent-browser click @e2
To make d3k prefer one locally when it launches helper browser commands, use:
d3k --browser-tool agent-browser
Fix Workflow
d3k errors --context - See errors and what triggered them
- Fix the code
d3k agent-browser open <url> then d3k agent-browser click @e1 to replay
d3k errors - Verify fix worked
Creating PRs with Before/After Screenshots
When creating a PR for visual changes, always capture before/after screenshots to show the impact:
-
Before making changes, screenshot the production site:
d3k agent-browser open https://production-url.com/affected-page
d3k agent-browser screenshot /tmp/before.png
-
After making changes, screenshot localhost:
d3k agent-browser open http://localhost:3000/affected-page
d3k agent-browser screenshot /tmp/after.png
-
Or use the tooling API to capture multiple routes at once:
capture_before_after_screenshots(
productionUrl: "https://myapp.vercel.app",
routes: ["/", "/about", "/contact"]
)
-
Include in PR description using markdown:
### Visual Comparison
| Route | Before | After |
|-------|--------|-------|
| `/` |  |  |
Upload screenshots by dragging them into the GitHub PR description.