Claude Code handles small browser automation changes well. It can fix a Playwright selector, add a timeout, improve an error message, or update a test with little supervision.
A complete MegaIndex BrowserAPI integration is different.
It may involve authentication, remote browser connections, profiles, proxies, retries, session reuse, cleanup, logging, and tests. These parts depend on each other. A change to retry logic can create duplicate browser sessions. A proxy override can break profile reuse. A debug statement can expose a password embedded in a WebSocket URL.
Claude can handle this work, but long sessions need clear boundaries. Otherwise, the implementation may gradually move away from the original requirement.
The practical approach is to control the task at four points:
- define the expected behavior before editing;
- review the implementation plan;
- enforce tests automatically;
- inspect the final Git diff instead of relying on the summary.
Describe the expected behavior
A request such as the following is too broad:
Add MegaIndex BrowserAPI profile support.
It leaves Claude to decide where the connection URL should be built, which proxy takes priority, what should be retried, and which component is responsible for closing the browser.
Describe the expected behavior instead:
Add MegaIndex BrowserAPI profile support to the existing Playwright client. Use the proxy stored in the profile by default. A custom proxy passed with the task must override it. Authentication errors must fail immediately. Temporary connection failures may be retried twice. Every remote browser must be closed after success, failure, timeout, or cancellation.
This gives Claude concrete rules for:
- remote browser connection;
- proxy priority;
- retry limits;
- authentication errors;
- browser cleanup.
Also define what Claude must not change:
Do not redesign the task queue. Do not modify environment files. Do not move connection logic into individual automation modules.
These restrictions prevent a focused BrowserAPI task from turning into an unnecessary project-wide refactor.
Start with a read-only plan
For a change that touches several modules, Claude should inspect the repository before writing code.
Plan mode allows Claude to trace the current browser lifecycle without making premature edits.
Ask it to determine:
- where the remote browser connection is created;
- where credentials are loaded;
- how the WebSocket URL is built;
- where profile and proxy settings are resolved;
- which component owns the browser instance;
- how connection failures are retried;
- where cleanup happens;
- which tests already cover this flow.
A practical planning prompt:
Inspect the existing browser automation architecture and prepare a plan for adding MegaIndex BrowserAPI profile support. The plan must include: 1. The current remote browser connection flow. 2. Files that need to change. 3. Where the WebSocket URL will be constructed. 4. How custom proxy settings will override profile proxy settings. 5. Retry behavior for authentication and temporary connection errors. 6. Browser cleanup after success, failure, timeout, and cancellation. 7. Tests that need to be added. 8. Files that must remain unchanged. Do not edit any files.
The plan should describe the full path from task input to browser cleanup.
A statement such as “update the browser client and add tests” is not a useful plan. Claude should explain which module owns the session, how errors are classified, and how duplicate connections will be prevented.
Correcting the plan takes less time than cleaning up a poor implementation.
Keep project rules specific
Claude Code reads project instructions from CLAUDE.md and related rule files.
Generic instructions provide little practical value:
- follow best practices;
- write clean code;
- use good architecture;
- handle errors correctly.
Replace them with rules that can be checked in the diff:
- Build MegaIndex BrowserAPI WebSocket URLs only in src/browser/connection.ts. - Automation modules must receive an initialized browser instance. - Automation modules must not construct remote browser URLs. - Never log BrowserAPI passwords, proxy passwords, or complete authenticated WebSocket URLs. - Authentication errors must not be retried. - Every created browser must be closed in a finally block. - Existing tests must not be deleted, skipped, or weakened.
These rules tell Claude exactly what belongs where.
Splitting project rules across several imported files may make them easier for developers to navigate, but it does not reduce the context loaded by Claude. The real improvement comes from removing vague, outdated, and duplicated instructions.
Turn verification into a repeatable procedure
Testing should not depend on remembering to ask Claude at the end of every task.
A verification skill can run after changes to the BrowserAPI integration. It should do more than execute the test suite because an agent can sometimes make failing behavior appear correct by changing the tests.
The verification procedure should:
- run the relevant tests;
- run type checking or linting;
- inspect git diff;
- check whether any test was deleted or skipped;
- look for weakened assertions;
- identify files changed outside the approved plan;
- report the result with evidence.
A useful verification report looks like this:
Verification: PASS Tests: - 46 passed - 0 failed - Command: npm test -- browser Type check: - Passed - Command: npm run typecheck Diff: - 5 files changed - No tests deleted - No tests skipped - No assertions weakened - No environment files modified BrowserAPI behavior: - Authentication errors are not retried - Custom proxy overrides profile proxy - Remote browser cleanup runs on every exit path
A response such as “everything looks correct” is not a verification report. It should show what Claude actually executed and reviewed.
Test the complete browser lifecycle
Do not test only the successful connection. The most important BrowserAPI tests cover the complete session lifecycle.
Successful connection
Verify that the client:
- builds the expected WebSocket URL;
- creates one remote browser;
- returns it to the automation task;
- closes it after the task completes.
Invalid credentials
Verify that:
- the error is returned immediately;
- the connection is not retried;
- credentials do not appear in logs.
Temporary connection failure
Verify that:
- the client retries only the allowed number of times;
- retries do not create duplicate tasks or sessions;
- the final error contains enough context for debugging.
Custom proxy override
Verify that:
- the profile proxy is used when no custom proxy is provided;
- the custom proxy takes priority when both are present;
- invalid proxy data is rejected before the remote connection starts.
Browser cleanup
Test cleanup after:
- successful completion;
- navigation failure;
- timeout;
- page crash;
- remote disconnection;
- task cancellation.
Session reuse
When reusable sessions are supported, verify that:
- the same task does not create several browsers;
- an expired session is not reused;
- one task cannot close another task’s browser.
These tests protect the behavior most likely to cause real failures, unnecessary browser traffic, or abandoned remote sessions.
Block completion when tests fail
Claude may attempt to finish a task even when tests are failing.
A Stop hook can prevent this. The hook runs when Claude tries to end its turn and blocks completion when the required checks fail.
The flow is straightforward:
- Claude changes the BrowserAPI integration.
- Claude attempts to finish.
- The Stop hook runs the tests.
- A test fails.
- The hook blocks completion.
- Claude receives the failure output.
- Claude continues fixing the implementation.
For Claude Code hooks, a blocking failure must exit with code 2. Exit code 1 may record an error without preventing the action.
A simple test gate:
#!/usr/bin/env bash set -u npm test -- browser status=$? if [ "$status" -ne 0 ]; then echo "BrowserAPI tests failed. Fix the errors before completing the task." >&2 exit 2 fi npm run typecheck status=$? if [ "$status" -ne 0 ]; then echo "Type checking failed. Fix the errors before completing the task." >&2 exit 2 fi exit 0
The exact hook configuration may change between Claude Code versions, but the purpose remains the same:
Claude must not be able to finish while required checks are failing.
Protect credentials before commands run
A BrowserAPI connection URL may contain a username and password. A custom proxy may contain another set of credentials.
These values can leak through:
- shell commands;
- debug output;
- error messages;
- copied configuration;
- test snapshots;
- CI logs.
A PreToolUse hook can inspect a command before Claude runs it.
The hook can block or rewrite commands that expose:
- environment files;
- BrowserAPI passwords;
- proxy passwords;
- complete authenticated WebSocket URLs;
- authorization headers.
Safe logging:
Connecting to MegaIndex BrowserAPI Profile: profile_123 Proxy mode: custom Attempt: 1 of 3
Unsafe logging:
Connecting to ws://username:[email protected]:9222
The complete authenticated URL should never appear in application, terminal, or CI logs.
When a hook rewrites tool input, it must return the complete input object, including fields that were not changed. Otherwise, valid command arguments may be lost.
Match the permission mode to the task
Different BrowserAPI tasks require different permission levels.
| Mode | When to use it | Main limitation |
|---|---|---|
| Plan | Initial integration, authentication, proxies, session lifecycle, migrations, and production configuration | Read-only; Claude cannot edit files |
| Accept edits | Small supervised fixes, tests, logging, and documentation | Requires regular human review |
| Auto | Longer implementations after hooks and tests are configured | Checks intent, not code correctness |
| Bypass permissions | Disposable isolated containers or virtual machines | Skips normal safeguards |
Plan mode
Use plan mode for:
- initial BrowserAPI integration;
- authentication changes;
- proxy routing;
- browser lifecycle changes;
- profile storage;
- database migrations;
- production configuration.
Claude can inspect the project but cannot edit it.
Accept edits
Use this mode when you are watching the session and reviewing changes regularly.
It works well for:
- small fixes;
- logging changes;
- test additions;
- documentation updates;
- isolated automation improvements.
Auto mode
Use auto mode only after reliable verification hooks are active.
Auto mode can detect actions that exceed the requested scope or create an obvious security risk. It does not determine whether the implementation is correct.
For example, it may allow a retry loop that accidentally creates several remote browsers. The command is not dangerous to the local machine, but the resulting code is still wrong.
The practical combination is:
- a reviewed plan;
- auto mode;
- a Stop hook;
- a verification skill;
- a final diff review.
Bypass permissions
Do not use bypass mode on a development machine containing real BrowserAPI, proxy, database, or payment credentials.
Use it only inside an isolated environment with disposable access.
Keep long sessions focused
Large BrowserAPI tasks often require several rounds of implementation and testing. As the conversation grows, Claude may lose earlier architectural decisions.
Use focused compaction
When compacting the session, state what the summary must preserve:
/compact Focus on the MegaIndex BrowserAPI connection lifecycle, proxy precedence, retry limits, credential protection, and browser cleanup.
This is safer than running /compact without instructions.
Important details to preserve include:
- where the WebSocket URL is built;
- which proxy takes priority;
- which errors are retryable;
- which component owns the browser session;
- how cleanup works;
- which tests must remain unchanged.
Rewind incorrect changes
When Claude takes the implementation in the wrong direction, repeated correction prompts often leave unnecessary code behind.
Rewind to the checkpoint before the incorrect approach.
This is useful when Claude:
- replaces a working session manager;
- introduces a second retry system;
- moves credentials into application code;
- changes the task queue without a clear reason;
- rewrites tests around incorrect behavior.
Removing the wrong path is usually faster than repairing it.
Use measurable completion conditions
A useful goal should be verifiable from Claude’s output.
A measurable goal:
/goal all BrowserAPI connection, proxy override, retry, and cleanup tests pass, and the type checker reports zero errors
A vague goal:
/goal make the BrowserAPI integration reliable
The first condition can be checked. The second cannot.
The verification procedure must still inspect the diff to ensure Claude did not satisfy the goal by deleting or weakening tests.
Read the diff before the summary
Claude’s final summary may state that profile support was added, retries were improved, tests were written, and all checks passed.
That summary does not show whether unrelated files were modified.
Review the repository directly:
git status git diff --stat git diff
Start with the files listed in the approved plan.
A useful review order is:
- connection and authentication;
- proxy and profile handling;
- retry logic;
- browser ownership and cleanup;
- tests;
- configuration and dependencies.
Look for:
- credentials in logs;
- duplicated connection logic;
- retries around authentication failures;
- missing finally blocks;
- unlimited retry loops;
- shared mutable profile state;
- removed tests;
- weakened assertions;
- unrelated dependency changes.
The diff is the result. The summary is only Claude’s description of it.
Review the result in a fresh Claude session
The Claude session that wrote the implementation has already committed to its own approach. A new session can review the changes without that history.
A simple headless review:
git diff main | claude -p --bare
A focused review prompt:
Review this diff for a MegaIndex BrowserAPI integration. Check for: - duplicate remote browser sessions; - missing browser cleanup; - credentials in logs; - incorrect proxy precedence; - retries on authentication errors; - unlimited retry loops; - shared mutable browser profiles; - deleted, skipped, or weakened tests; - unrelated changes. Return only actionable findings with file names and severity.
For CI, structured output is easier to process than prose:
{
"severity": "high",
"file": "src/browser/connection.ts",
"line": 84,
"issue": "Authentication errors enter the retry loop",
"recommendation": "Return immediately when the remote server rejects credentials"
}This format makes review findings easier to filter, store, or publish as pull request checks.
A practical BrowserAPI workflow
Use the following sequence for every important MegaIndex BrowserAPI change.
Step 1: Define the expected behavior
Specify:
- the connection flow;
- proxy priority;
- retry limits;
- cleanup rules;
- failure behavior;
- files that must not change.
Step 2: Start in plan mode
Ask Claude to inspect the current architecture and list the exact files it intends to modify.
Step 3: Review the plan
Check session ownership, credentials, proxies, retries, cleanup, and tests.
Step 4: Allow implementation
Use accept-edits mode for supervised work or auto mode when hooks are already configured.
Step 5: Run verification
Execute tests, type checking, and diff inspection.
Step 6: Block incomplete work
Use a Stop hook so Claude cannot finish while required checks fail.
Step 7: Review the diff
Compare every changed file with the approved plan.
Step 8: Run a fresh review
Use a new Claude session to inspect the result without the implementation history.
Prompt for a MegaIndex BrowserAPI task
Add MegaIndex BrowserAPI profile support to this project. Requirements: 1. Connect through the existing Playwright remote browser client. 2. Build the authenticated WebSocket URL only in the browser connection module. 3. Use the proxy stored in the profile by default. 4. A custom proxy passed with the task must override the profile proxy. 5. Authentication errors must fail immediately without retries. 6. Temporary connection errors may be retried twice. 7. Every created browser must be closed after success, failure, timeout, or cancellation. 8. Never log BrowserAPI passwords, proxy passwords, or complete authenticated WebSocket URLs. 9. Add tests for successful connection, invalid credentials, proxy override, retry limits, and cleanup. 10. Do not delete, skip, or weaken existing tests. 11. Do not modify .env files or unrelated task queue code. Start in read-only plan mode. Return: - the current browser lifecycle; - files that need to change; - the implementation plan; - tests that need to be added; - risks; - files that will remain unchanged. Do not edit files until the plan is approved.
Claude Code can handle a substantial part of a MegaIndex BrowserAPI integration, but a confident final summary is not enough.
A reliable workflow combines a reviewed plan, specific project rules, automatic tests, enforced cleanup checks, credential protection, and a final diff review. This allows Claude to work on larger browser automation tasks without losing control of remote sessions, proxies, credentials, retries, or tests.
Discussion