How to keep Claude Code on track during long MegaIndex Browser API projects

A practical workflow for using plan mode, compact, rewind, goals, loops, and Git worktrees while building browser automation with MegaIndex Browser API.

Small browser automation tasks rarely need much process. Claude can update a Playwright locator, add a timeout, or save a screenshot in a few minutes.

The problems start when the task grows.

Moving an existing automation workflow to MegaIndex BrowserAPI may require changes to connection handling, browser profiles, proxy configuration, session cleanup, retries, logging, and tests. Claude can work through all of this, but a long session creates a different risk: the agent gradually stops solving the task you originally gave it.

It may redesign a working module, forget why a profile is persistent, add retries around a non-repeatable action, or change session ownership while fixing an unrelated navigation error.

The solution is not a longer prompt. It is a better way to manage the session.



This article applies Claude Code’s long-session tools to a specific BrowserAPI workflow: planning the integration, preserving browser rules, recovering from bad implementation choices, defining a testable result, checking external processes, and separating parallel work.

Why BrowserAPI projects are difficult for long AI sessions

A local Playwright script often has a simple lifecycle:

Launch browser
Open page
Perform actions
Close browser

A remote browser workflow is usually less isolated. It may include:

• a WebSocket or CDP connection;
• BrowserAPI credentials;
• a persistent browser profile;
• profile cookies and local storage;
• a custom proxy passed for one task;
• navigation and action timeouts;
• screenshots, HTML, or extracted data;
• cleanup after both success and failure;
• integration tests against a remote environment.

These parts depend on one another.

If Claude changes how the browser session is created, it may also affect profile persistence. If it moves retry logic, it may repeat a form submission. If it closes the browser too early, screenshots or extracted data may be lost.

That is why long BrowserAPI tasks need more structure than a one-line instruction such as:

Add MegaIndex BrowserAPI support to this project.

The request is too broad. Claude must make architectural decisions before it has enough context to make them safely.

Use plan mode to expose assumptions before coding

The most useful first step is to ask Claude to inspect the repository without editing it.

For a BrowserAPI integration, the plan should explain more than which files will change. It should show how the current browser workflow will be adapted for remote execution.

A practical prompt:

Work in plan mode only. Do not edit any files.

Inspect the existing Playwright project and prepare a plan for moving
browser execution to MegaIndex BrowserAPI.

Requirements:
- keep the current automation logic unchanged;
- connect through the BrowserAPI WebSocket endpoint;
- read credentials from environment variables;
- support an optional browser profile;
- support an optional custom proxy;
- add bounded retries for connection failures;
- close the remote browser session after every task;
- 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 or interfaces.
3. The complete browser session lifecycle.
4. Retryable and non-retryable errors.
5. Security risks.
6. Tests and commands required to verify the result.

The plan should answer several BrowserAPI-specific questions:

• Which module builds the connection URI?
• Which component owns the remote browser session?
• Does one task create one session?
• Can several pages share the same browser context?
• When is a persistent profile reused?
• Does a custom proxy override the profile proxy?
• Which failures can be retried safely?
• Which values must be removed from logs?

These decisions are easy to review in a plan and expensive to correct after implementation.

A sensible execution path may look like this:

Automation task
    ↓
Task configuration
    ↓
BrowserAPI connection builder
    ↓
Playwright connectOverCDP()
    ↓
Remote browser context
    ↓
Profile and proxy configuration
    ↓
Page workflow
    ↓
Result and artifacts
    ↓
Session cleanup

If Claude proposes launching a local Chromium instance somewhere in this flow, duplicating profile storage, or letting individual page functions close the shared browser, the problem can be corrected before any code is written.

Keep browser rules in the repository, not only in chat

Long Claude sessions accumulate a large amount of temporary material:

• stack traces;
• failed selectors;
• test output;
• network logs;
• temporary workarounds;
• discussions about abandoned approaches.

Eventually, the conversation may be compacted. Old messages are replaced with a shorter summary so the session can continue.

That is useful, but a summary may omit one rule that still matters.

For example:

• the custom proxy must override the proxy attached to the profile;
• the profile ID must never be logged together with credentials;
• the session must remain open until all artifacts are saved;
• a retry must not repeat a completed checkout or form submission;
• connection errors and page validation errors must use different error types.

Use `/compact` with a precise instruction:

/compact Preserve the agreed MegaIndex BrowserAPI architecture,
session ownership, profile behavior, proxy precedence,
security restrictions, retry rules, completed work,
and the remaining integration tests.

Remove old selector debugging, resolved stack traces,
and abandoned implementation ideas.

The summary should preserve decisions, not every detail of the debugging process.

Permanent rules belong in `CLAUDE.md` or `.claude/rules/`.

## MegaIndex BrowserAPI rules

- Read BrowserAPI credentials only from environment variables.
- Never print the complete connection URI.
- Never log proxy passwords.
- One automation task owns one remote browser session.
- Close the session in a finally block.
- Save screenshots and extracted results before closing the session.
- A custom proxy overrides the proxy assigned to the profile.
- Do not retry non-idempotent browser actions automatically.
- Do not replace event-based waits with fixed sleep calls.
- Every BrowserAPI change requires a smoke test.

This is more reliable than expecting Claude to reconstruct the rules from a long conversation.

Use compact after milestones, not during unresolved debugging

Compaction works best when a stage of the task is complete.

Good points to compact include:

• the connection layer is working;
• the first remote page opens successfully;
• profile support is complete;
• proxy handling is verified;
• cleanup behavior is covered by tests.

Compacting in the middle of a difficult failure can remove useful context about what has already been tested.

Suppose Claude is investigating why the browser connects successfully but the expected profile cookies are missing. The conversation may contain important evidence:

• the profile ID passed to the connection builder;
• the context returned by Playwright;
• cookie values before navigation;
• the difference between a new context and the existing remote context.

If that history is compacted too early, Claude may repeat the same tests or return to an approach that was already ruled out.

Finish the investigation first. Then compact the result into a stable decision:

The existing remote browser context must be reused. Creating a new Playwright context after connecting prevents the BrowserAPI profile state from being available.

That sentence is worth preserving. Twenty pages of debugging output are not.

Use rewind when Claude changes the wrong layer

Browser automation failures often tempt an agent to make the problem larger than it is.

A navigation timeout may lead Claude to rewrite the session manager. A missing cookie may lead it to add a second storage system. A failed selector may lead it to replace every locator on the page.

Typical warning signs include:

• working interfaces are changed without a requirement;
• one retry is expanded into a generic retry framework;
• fixed delays are added throughout the workflow;
• the browser is recreated for every action;
• profile state is copied manually between sessions;
• errors from unrelated layers are merged into one exception;
• cleanup logic is duplicated in several modules.

When this happens, adding more corrective prompts often produces code built on top of the original mistake.

Rewind is cleaner.

Consider this sequence:

1. Claude adds the MegaIndex BrowserAPI connection.
2. The smoke test opens a remote page and saves a screenshot.
3. You ask it to handle connection timeouts.
4. Claude rewrites the whole browser session abstraction.
5. The new version no longer closes failed sessions correctly.
6. You rewind to the working checkpoint.
7. You give Claude a narrower instruction.

The replacement instruction could be:

Add a 30-second timeout around the BrowserAPI connection attempt.

Do not change:
- BrowserSession;
- session ownership;
- profile handling;
- page creation;
- cleanup logic.

Return the original connection error as BrowserConnectionError
after two failed attempts.

This keeps the correction inside the layer where the problem actually exists.

Define completion through a real browser check

A long implementation task is easier to delegate when “done” can be verified from command output.

This goal is too subjective:

/goal make the BrowserAPI integration production-ready

Claude cannot prove that something is production-ready.

A useful goal names the exact observable result:

/goal npm test passes, TypeScript reports zero errors,
and the BrowserAPI smoke test:

1. connects to MegaIndex BrowserAPI;
2. opens the configured test URL;
3. verifies the expected page title;
4. evaluates JavaScript in the page;
5. saves a screenshot;
6. closes the remote browser session;
7. exits without leaked handles.

A more advanced test may also verify:

• the expected browser profile is active;
• cookies persist between two tasks using the same profile;
• the custom proxy takes precedence over profile settings;
• the browser closes after a navigation failure;
• credentials are redacted from logs;
• a failed connection is retried only the configured number of times.

The project rules should also prevent Claude from satisfying the goal by weakening the checks.

## Test integrity

- Do not delete or skip failing tests.
- Do not replace assertions with console output.
- Do not reduce timeout coverage to make a test pass.
- Successful navigation is not enough; verify the expected page state.
- Fix the implementation, not the acceptance criteria.

This matters because an autonomous run will optimize for the condition it receives. Weak verification creates weak results.

Use loop for CI and remote test feedback

BrowserAPI development often depends on systems outside the current terminal session.

Claude may need to wait for:

• a GitHub Actions workflow;
• a deployment to a test environment;
• a scheduled browser job;
• a queue worker;
• a remote integration test;
• a temporary infrastructure problem to clear.

A loop can periodically check the external state and respond when it changes.

/loop 5m Check the latest GitHub Actions run named browser-api-smoke.

If it is still running, make no changes.

If it fails:
1. inspect the failing step;
2. determine whether the cause is code, configuration,
   or a temporary remote connection error;
3. fix code only when the failure is reproducible;
4. run the relevant local checks;
5. trigger the workflow again.

Stop when the workflow passes.

The instruction should distinguish implementation failures from temporary infrastructure failures. Otherwise, Claude may change working code because one remote connection timed out.

Loop is useful for development coordination. It should not replace retry logic inside the application.

The application still needs:

• connection timeouts;
• bounded retries;
• clear error categories;
• cleanup after failure;
• idempotency protection.

Checking CI every few seconds is unnecessary. The interval should match the process being monitored.

Use worktrees for independent BrowserAPI work

A large integration can be split across several Claude sessions:

WorktreeResponsibilitybrowser-connectionConnection URI, authentication, timeouts, and cleanupbrowser-profilesProfile selection, cookies, local storage, and persistencebrowser-proxyCustom proxy encoding, precedence, and validationbrowser-testsSmoke tests, failure tests, and CI configurationbrowser-docsConfiguration examples and integration documentation

Each session works in an isolated file tree, so two agents do not overwrite the same local changes.

Worktrees prevent file collisions, but they do not prevent incompatible design decisions.

Before parallel work starts, define the shared interfaces:

interface BrowserSessionOptions {
  profileId?: string;
  proxyUrl?: string;
  connectionTimeoutMs: number;
}

interface BrowserSession {
  page: Page;
  close(): Promise<void>;
}

interface BrowserSessionFactory {
  connect(options: BrowserSessionOptions): Promise<BrowserSession>;
}

The connection agent can implement the factory. The test agent can mock it. The profile and proxy agents can work with the same options object.

None of them should redesign the contract independently.

Some tasks should not be separated. Session ownership, context creation, and profile persistence are tightly connected. If the interfaces are still changing, keep that work in one session until the boundaries stabilize.

A practical sequence for migrating Playwright to BrowserAPI

The following sequence gives Claude enough freedom to work while keeping the task reviewable.

1. Define the migration boundary

Use:

Move the existing Playwright workflow from local Chromium
to MegaIndex BrowserAPI.

Preserve:
- page logic;
- selectors;
- extracted data format;
- public function signatures.

Change only:
- browser connection;
- profile and proxy configuration;
- session cleanup;
- integration tests.

This prevents a browser infrastructure task from turning into a rewrite of the scraper.

2. Request a read-only plan

Claude should identify the existing browser entry point, configuration layer, cleanup path, and tests before editing.

3. Approve the session model

Confirm:

• who creates the session;
• who closes it;
• whether profiles persist between tasks;
• how proxy overrides work;
• which errors are retryable;
• what data may be logged.

4. Build the smallest complete remote run

Start with:

Connect
→ open one page
→ verify title
→ run one JavaScript expression
→ save screenshot
→ close session

Do not add queues, multiple target sites, or complex recovery logic before this path works.

5. Add failure coverage

Test:

• invalid credentials;
• connection timeout;
• navigation timeout;
• invalid proxy configuration;
• page script failure;
• cleanup after an exception.

6. Add profile and proxy behavior

Verify the behavior instead of only checking configuration values.

For profile persistence, create a value in local storage during one task and confirm that it is available in the next task using the same profile.

For proxy routing, open an IP-check page and compare the observed address with the expected proxy route.

7. Set a measurable goal

Let Claude finish the remaining work against tests, type checks, and the BrowserAPI smoke test.

8. Compact the completed architecture

Preserve the final session model, profile rules, proxy precedence, test commands, and unresolved work.

9. Rewind immediately after architectural drift

Do not allow a small failure to trigger an unrelated rewrite.

10. Split stable work into worktrees

Only parallelize areas with agreed interfaces and limited overlap.

When the full workflow is unnecessary

Not every change requires plan mode, goals, loops, and worktrees.

A normal Claude request is usually enough for:

• changing one locator;
• adding one timeout;
• saving page HTML;
• updating a screenshot path;
• fixing one assertion;
• adding one environment variable;
• improving one error message.

The complete process becomes useful when the task:

• affects several modules;
• changes session ownership;
• introduces persistent profiles;
• adds custom proxy routing;
• migrates local automation to remote browsers;
• requires integration testing;
• runs across several Claude sessions;
• takes long enough for context loss to become likely.

The practical rule is straightforward: use more control when a wrong assumption would be expensive to undo.

Final takeaway

MegaIndex BrowserAPI gives Claude-built automation a remote browser environment. Claude Code can inspect the project, plan the migration, write the integration, run tests, and diagnose failures. The difficult part is keeping a long session aligned with the original browser architecture.

Plan mode exposes assumptions before they become code. Directed compaction preserves profile, proxy, and session rules. Rewind removes bad implementation branches before they spread. Goals turn the BrowserAPI integration into a result Claude can verify.

Loops handle delayed CI and remote test feedback. Worktrees keep parallel agents from editing the same project state.

Used together, these tools make Claude more useful on the parts of browser automation that normally require the most supervision: remote sessions, persistent state, proxy routing, failure recovery, and integration testing.