Claude can usually handle a small Playwright task with little supervision. Ask it to update a selector, add a timeout, or save a screenshot, and the job is often finished in a few prompts.
Long browser automation tasks are less predictable.
A typical MegaIndex BrowserAPI integration may involve remote browser connections, authentication, browser profiles, proxy routing, session persistence, error recovery, logging, and integration tests. Once the work spreads across several modules, Claude has more opportunities to drift away from the original requirement.
The issue is rarely that Claude cannot write the code. More often, it starts solving the wrong version of the problem.
It may redesign a working abstraction, introduce unnecessary layers, change the browser lifecycle while fixing an unrelated bug, or lose an earlier decision after the conversation is compacted.
The best way to avoid this is to treat a long Claude Code session as an engineering workflow rather than a long prompt. Define the scope before implementation, preserve important decisions, set clear checkpoints, and make completion measurable.
Start with a plan, not code
Before Claude edits the repository, ask it to inspect the project in plan mode.
This matters because a BrowserAPI integration usually touches more than the file where the Playwright script lives. Claude may need to understand:
- how the application currently launches Chromium;
- where credentials are stored;
- how browser sessions are created and closed;
- whether profiles already manage cookies and local storage;
- how proxies are passed;
- where retries belong;
- how integration tests are run;
- which modules are allowed to log connection details.
A useful planning request should be specific enough to expose architectural mistakes before implementation begins.
Work in plan mode only. Do not modify any files. Inspect the project and prepare a plan for moving the existing Playwright workflow to MegaIndex BrowserAPI. Requirements: - connect to the remote browser through Playwright; - load connection details from environment variables; - support browser profile selection; - allow an optional custom proxy; - preserve the current business logic; - add connection timeouts and controlled retries; - add a smoke test that opens a page, verifies its title, saves a screenshot, and closes the session. Return: 1. Files that need to change. 2. New modules that should be created. 3. The browser session lifecycle. 4. Expected failure cases. 5. Tests and commands required to verify the result.
The main value of this step is not the file list. It is the chance to review Claude’s assumptions.
For example, the plan should make it clear whether the application creates one remote browser session per task, reuses a session across several steps, or keeps a persistent profile between runs. These choices affect cookies, resource usage, retries, and cleanup.
A simple flow might look like this:
Application task ↓ Playwright client ↓ MegaIndex BrowserAPI connection URI ↓ Remote browser session ↓ Profile and proxy configuration ↓ Target website ↓ Result, logs, and artifacts
If this flow is wrong, it is better to fix it in the plan than after Claude has implemented it across several files.
Keep permanent decisions out of the chat history
Long sessions collect a large amount of temporary information: logs, failed experiments, stack traces, selector changes, test output, and intermediate explanations.
Eventually, Claude may compact the conversation to free context space. That is useful, but the summary may not preserve every technical decision with the same precision as the original discussion.
For a BrowserAPI project, losing one small rule can create a serious regression.
Examples include:
- a custom proxy must override the proxy assigned to the browser profile;
- credentials must never be printed in logs;
- each task owns its browser session;
- the browser must close in a finally block;
- retries must not repeat non-idempotent actions;
- navigation failures and business validation failures must be reported separately;
- screenshots should be saved before the session is closed.
Use /compact with a focused instruction instead of letting Claude decide what matters.
/compact Keep the current MegaIndex BrowserAPI architecture, the session lifecycle, profile and proxy precedence rules, security restrictions, completed implementation decisions, and the remaining test plan. Remove detailed debugging history for selectors and errors that have already been resolved.
Rules that must survive every session should live in the repository.
A CLAUDE.md file or a rule under .claude/rules/ is a better place for requirements such as:
## MegaIndex BrowserAPI rules - Read browser credentials only from environment variables. - Never log connection credentials or proxy passwords. - Close every browser session in a finally block. - Keep browser profile configuration separate from task configuration. - A retry must not repeat actions that may create duplicate records. - Every BrowserAPI change must include a smoke test. - Do not replace event-based waits with fixed delays.
This prevents important constraints from depending on the quality of a conversation summary.
Use rewind when the implementation goes in the wrong direction
Browser automation code is easy to destabilize because many components depend on the same session.
A change to connection handling can affect browser contexts. A change to profile loading can affect authentication. A retry added around the wrong block can repeat form submissions or create duplicate records.
Claude may also choose a technically valid but unsuitable direction, such as:
- launching a new browser for every page action;
- replacing stable locators with long CSS selectors;
- adding fixed sleeps instead of waiting for page state;
- manually exporting cookies that are already managed by a profile;
- grouping every failure under one generic exception;
- adding unlimited retries;
- redesigning the session manager while fixing a timeout.
Once this happens, continuing to prompt Claude forward often makes the situation worse. Each correction is applied on top of the previous wrong assumption.
Rewind is usually cleaner.
A common sequence looks like this:
- Claude implements the remote BrowserAPI connection.
- The smoke test opens a page successfully.
- A later task causes Claude to rewrite the session manager.
- Browser sessions stop closing correctly.
- The project is rewound to the last working checkpoint.
- Claude receives a narrower instruction: add timeout handling without changing session ownership or cleanup.
This is one of the most useful habits in long Claude Code sessions. Do not spend ten prompts repairing an implementation that should have been abandoned after the first wrong architectural turn.
Define “done” in terms of observable results
A long task becomes easier to delegate when Claude can verify completion itself.
The goal should be based on command output, test results, or files produced by the workflow. Avoid subjective conditions.
This is too vague:
/goal make the BrowserAPI integration reliable
Claude cannot prove that the integration is reliable.
A better condition is:
/goal npm test completes without errors, TypeScript reports zero errors, and the BrowserAPI smoke test connects to MegaIndex BrowserAPI, opens the test page, verifies its title, saves a screenshot, and closes the remote browser session successfully
Depending on the project, the completion condition may also require:
- a successful WebSocket connection;
- execution of JavaScript on the page;
- use of the requested browser profile;
- confirmation that the expected proxy is active;
- persistence of the final result;
- cleanup after both success and failure;
- passing unit and integration tests;
- no linter or type-checking errors.
The project should also make it explicit that Claude is not allowed to “solve” a failing goal by weakening the verification.
## Completion rules - Never delete, skip, or weaken a failing test to satisfy a goal. - Fix the implementation instead. - A browser test must verify the expected page state. - Successful navigation alone is not a valid test result. - Do not replace assertions with logging.
This matters because autonomous agents optimize for the condition they are given. A weak condition often produces a weak implementation.
Use loops for processes outside the local session
Some steps depend on external systems.
Claude may need to wait for:
- a GitHub Actions run;
- a deployment;
- a scheduled task;
- a queue worker;
- a remote test environment;
- a temporary BrowserAPI infrastructure issue;
- a result produced by another service.
A loop is useful when Claude should check the state periodically and act only when something changes.
/loop 5m Check the latest GitHub Actions run for browser-api-smoke. If it is still running, make no changes. If it fails, inspect the logs, identify the cause, fix the implementation, and start the check again. Stop when the workflow passes.
This is appropriate for development orchestration. It is not a substitute for retry logic inside the application.
The application still needs its own timeouts, bounded retries, and error handling. A Claude loop should not be used to hide a browser workflow that fails unpredictably.
Intervals should also reflect the external process. Checking CI every few seconds only wastes requests. A few minutes is usually enough.
Separate parallel agents with Git worktrees
A large BrowserAPI task can often be divided into independent areas:
- connection and authentication;
- profile handling;
- proxy configuration;
- browser workflow implementation;
- logs and metrics;
- tests;
- documentation.
Running several Claude sessions in the same working directory is risky. They can edit the same files, overwrite each other’s changes, or make incompatible assumptions about shared interfaces.
Git worktrees give each session an isolated copy of the repository.
worktree/browser-connection Connection URI, authentication, and cleanup worktree/browser-profiles Profiles, cookies, and local storage worktree/browser-proxy Custom proxy handling and routing worktree/browser-tests Smoke tests and integration tests
Isolation prevents direct file collisions, but it does not solve architectural conflicts.
Two agents can still produce incompatible implementations even when they edit different files. Before parallel work begins, define the shared contract.
interface BrowserSessionOptions { profileId?: string; proxyUrl?: string; timeoutMs: number; } interface BrowserSession { page: Page; close(): Promise<void>; }Each agent can then work against the same interface without redesigning it independently.
Closely related work should remain in one session. Profile handling and session lifecycle, for example, often share too many assumptions to be developed safely by separate agents unless the interfaces are already stable.
A practical workflow for a MegaIndex BrowserAPI task
The following sequence works well for larger integrations.
1. Narrow the objective
Avoid:
Add BrowserAPI support.
Use:
Move the existing Playwright workflow to remote execution through MegaIndex BrowserAPI without changing its business logic.
This defines both the required change and the part that must remain untouched.
2. Inspect before editing
Ask Claude to review:
- the current browser launch code;
- Playwright configuration;
- environment variables;
- profile handling;
- proxy logic;
- cleanup;
- test setup.
Do not allow implementation until the plan explains how these parts fit together.
3. Agree on the session lifecycle
Before coding, answer the following questions in the plan:
- Which module creates the BrowserAPI connection URI?
- Which component owns the browser session?
- When is the session closed?
- How is the profile ID passed?
- When does a custom proxy override profile settings?
- Which errors can be retried?
- Which data may appear in logs?
- What output proves success?
These decisions are more important than the exact Playwright syntax.
4. Build one complete path first
Start with the smallest useful workflow:
Connect → open page → verify page state → save screenshot → close session
Do not add queues, schedulers, multiple website adapters, and complex retry policies before this path works consistently.
A complete vertical path reveals infrastructure problems much earlier than a large set of partially implemented modules.
5. Add measurable completion criteria
Once the basic flow works, define the remaining work through testable conditions:
- timeout handling;
- proxy verification;
- profile persistence;
- failure cleanup;
- integration tests;
- type checks;
- linting.
Claude can then work more independently without relying on subjective judgment.
6. Compact after completed stages
Compaction is most useful after a meaningful milestone, not in the middle of unresolved debugging.
For example:
- connection layer completed;
- smoke test completed;
- profile support completed;
- error handling completed.
At each point, preserve the current architecture and remaining work while dropping obsolete logs.
7. Rewind early
If Claude begins replacing working code without a clear requirement, rewind before the change spreads.
The earlier the rollback, the less context and code need to be repaired.
8. Parallelize only stable boundaries
Documentation and tests are often safe to separate. Session ownership, profiles, and proxy precedence usually require more coordination.
Use worktrees only after shared interfaces are clear.
When this process is unnecessary
Not every BrowserAPI change needs a formal plan, goal, and separate worktree.
A normal Claude request is usually enough for tasks such as:
- changing one locator;
- adding a timeout;
- reading a page title;
- saving HTML;
- fixing one assertion;
- adding a configuration field;
- updating an error message.
The full workflow becomes worthwhile when the task:
- affects several modules;
- changes browser session ownership;
- introduces profiles or proxy routing;
- migrates existing automation;
- requires integration tests;
- involves several Claude sessions;
- runs for a long time with limited supervision.
The dividing line is simple: use more process when a wrong assumption would be expensive to undo.
Using Claude Code and BrowserAPI together
MegaIndex BrowserAPI provides the remote browser environment. Claude Code helps build and maintain the code that uses it.
That combination becomes useful when the boundaries are clear.
Claude can inspect the repository, prepare an implementation plan, write the Playwright or Puppeteer integration, run tests, and diagnose failures. BrowserAPI handles remote browser execution, JavaScript rendering, profiles, proxies, and session infrastructure.
The main challenge is not giving Claude enough freedom. It is giving Claude enough structure to work for several hours without quietly changing the original task.
A reviewed plan, persistent project rules, deliberate context compaction, early rewinds, measurable goals, and isolated worktrees make long sessions much easier to control. They also make the resulting BrowserAPI integration easier to review, test, and maintain.
Discussion