Browser verification

Tejus has a built-in Chromium browser that you and the agent share: both of you see and act on the same page. Tabs and browser tool access belong to the thread, while cookies and signed-in sessions are shared across all Tejus browser tabs and agent workflows. Use it to verify visible behavior alongside code review and tests.

Supported providers reach the browser through the same set of app-owned browser_* tools, so the workflow below does not depend on which provider you use.

Open the browser

• Press Ctrl+Shift+B to show or hide the browser for the current thread.
• Or open Browser in the right dock (from its empty-dock launcher, or the Add panel (+) menu when other panels are open).

A new tab starts on a Local page that lists dev servers detected on localhost ports; click one to open it, or use Refresh local servers. Dev servers the agent starts also appear in the Background tasks panel under Local servers: Open in browser loads them in the in-app browser (in the Editor view, they open in the Web preview tab), and Stop server ends them.

Choose the browser surface

The same thread browser can appear in two places:

• In the right sidebar: a docked column beside the conversation.
• Floating over the conversation: keeps the page visible while you read the transcript. Drag the handle to move it (click it for actions), resize from an edge or corner, and use Open browser in sidebar to dock it again. The floating card keeps a fixed 1280×800 page layout and scales it to fit, so moving or resizing the card does not reflow the page.

These are two presentations of one thread-scoped browser session, not separate browsers. Tabs, navigation, and the page an agent operates stay attached to the thread when you move between them.

Closing the floating panel hides that presentation; it does not necessarily close the thread’s tabs. Use the tab strip when you intend to close a tab.

Useful toolbar actions: Annotate page lets you mark spots on the page and attach them to your next message, and the agent can return to that exact page; Copy screenshot and Copy link copy the current page (Ctrl+Shift+C also copies the link while the page has focus); the Browser actions menu offers New tab, Capture screenshot, Open externally, and Close browser panel.

Saved logins, session import, and sign-in popups

The browser’s Saved logins button opens local account management and Import browser cookies. On Windows, cookies can be imported from Google Chrome and Microsoft Edge profiles found on your PC. Saved passwords and imported signed-in cookies are separate stores. Read Browser logins & sessions for defaults, master-password controls, and shared-session scope.

Agents cannot fill, generate, or change saved passwords. When a site needs signing in, sign in yourself or import a session.

Web sign-in popups (for example Google or Microsoft account pages) open as embedded tabs in the owning thread’s browser. Closing a popup returns to its opener when available; closing an opener also closes its popups. When the agent reaches a sign-in or consent step that needs you, it stops and waits; complete it yourself, then let the agent observe the page again. Pages cannot launch other apps through custom URL schemes, so a sign-in flow that hands off to an external desktop app may need a different route.

What browser verification is for

Use the browser when correctness depends on visible or runtime behavior, including:

• Layout and responsive states
• Navigation and routing
• Forms, validation, and focus behavior
• Loading, empty, error, and success states
• Console exceptions and failed requests
• Authentication flows that require human completion
• Interaction sequences that unit tests do not fully represent

Keep unit, integration, and server tests. Browser verification adds evidence at the user-facing layer.

Start the correct application

Before opening the page:

1. Confirm the thread’s working directory (local checkout or worktree).
2. Start the intended development server from that environment.
3. Record the command and local URL.
4. Check for port conflicts or another checkout already serving the same port. The Local page and Background tasks panel show which servers are running.
5. Confirm the browser is viewing the thread’s build rather than a stale process.

A correct page served from the wrong checkout does not verify the branch you are reviewing.

The browser tools

The reliable interaction loop

Structure versus screenshots

Prefer structured reads for interaction and assertions. Use screenshots when pixels matter.

A screenshot alone does not prove accessibility, event behavior, form state, or network success. A semantic read alone may not reveal visual overlap, color contrast, or clipping.

Viewport coverage

For responsive changes, verify at the viewport sizes relevant to the product. At minimum, consider:

• A narrow mobile width
• A typical laptop width
• A wide desktop width when the layout uses additional columns

After browser_resize, observe the page again because layout and element geometry may have changed. Resizing or reopening the browser panel returns the page to the panel’s own size.

Do not declare “responsive” after checking one width.

Forms and text entry

When testing forms:

• Read the field and its current value first.
• Replace text unless appending is intentional.
• Verify validation messages and disabled states.
• Confirm submission effects outside the input itself.
• Avoid entering real credentials or private data into logs or thread transcripts.
• Test keyboard behavior when focus and accessibility matter.

For uploads, browser_upload accepts one to 32 workspace-relative regular files; never upload secrets without explicit intent. File downloads started by the agent need your approval.

Console and network diagnostics

browser_logs returns bounded console, exception, and network request/response/failure metadata for the exact tab (up to 200 entries).

Use it to investigate:

• JavaScript exceptions
• Failed fetches
• Unexpected status codes
• Requests sent to the wrong origin
• Repeated requests or reload loops

Headers, request bodies, and response bodies are never returned. Use application logs or safe test instrumentation when deeper payload inspection is necessary.

Ambiguous failures and safe retries

A browser tool timeout or transport failure does not always mean nothing happened. A click, typed text, submit, navigation, or upload may have taken effect before the response was lost.

When an error is ambiguous:

1. Do not immediately repeat the action.
2. Inspect the current URL and page state.
3. Check console and network metadata when useful.
4. Determine whether the intended effect already occurred.
5. Retry only after the state is understood.

This is especially important for submissions, purchases, external messages, account changes, and any action that can create duplicate effects.

When you take over

If you click or type in the browser while the agent is working, your input wins: the agent’s current browser action is interrupted and it waits for you before observing the page again. Use this to complete sign-in, dismiss an unexpected dialog, or correct the page, then tell the agent to continue.

Do not ask the agent to extract passwords, one-time codes, recovery keys, or private tokens from another surface.

Use page scripts carefully

browser_run can read the DOM through page.evaluate. That is useful for data that semantics and logs cannot show, but it can also change the page.

Prefer real interactions. Do not use scripts to bypass normal navigation, access hidden secrets, forge application state, or replace a user-visible workflow with direct internal mutation.

Manual review still matters

Reveal the browser and inspect important visual behavior yourself when:

• The change is primarily visual
• Animation, drag, hover, or focus behavior matters
• The page has sensitive external effects
• The agent reports an ambiguous interaction
• The screenshot or structured output does not match your expectation

You and the agent observe the same page and session, not separate browsers with different cookies or data.

Browser verification record

A useful completion report includes:

Server:
npm run dev
http://localhost:3000

Pages checked:
/settings/integrations
/docs/providers/codex

Viewports:
390×844
1440×900

Scenarios:
- Empty integration list
- Create integration validation
- Successful paired state
- Narrow sidebar navigation

Diagnostics:
- No console exceptions
- No failed application requests

Not checked:
- Real third-party OAuth completion

Completion checklist

• The page is served from the thread’s environment
• The correct route and account state were used
• Actions targeted elements found on the current page
• State-changing actions were observed before retrying
• Relevant mobile and desktop widths were checked
• Console and network failures were reviewed
• Pixel-level behavior was inspected when necessary
• Human-only authentication stayed human-controlled
• The diff and automated tests were also reviewed
• The final report states what was and was not verified