Docs: Getting started

View as Markdown

Astral docs

Astral's Developer mode lets an AI agent drive a real browser tab over MCP (the Model Context Protocol). The agent can read a page, click and type, look at the network and the console, take screenshots, and run a test that leaves a report with evidence. This page gets you connected.

What a connected agent can do

  • Open tabs, navigate and wait for the page, then read it as text or as an accessibility snapshot.
  • Click, type, press keys, scroll and select, using trusted input like a person would.
  • Inspect requests, console messages and grouped page errors, and read page performance.
  • Check a page's responsive layout and get the CSS fix for every finding.
  • Write and run a test: steps, expectations, screenshots and a recording, then save it so it can be replayed by you, by another agent or in CI.

That is 46 tools in 10 groups. Each group is a permission you switch on or off, and a few are off by default. See the tool reference.

1. Install Astral

Download the installer for your system from the downloads section. The MCP bridge, astral-mcp, is inside the installer: there is nothing else to install to connect an agent.

2. Turn on Developer mode

  1. Open Settings → Developer and turn on Developer mode.
  2. The Connection card shows the command that registers Astral with your agent, for example claude mcp add --scope user astral -- "/Applications/Astral.app/Contents/MacOS/astral-mcp".
  3. Use Share with AI in the panel header to choose which tabs the agent can see. The scope is chosen on the same screen.

Every call an agent makes shows up in the activity feed and in the audit log. Each tool group (read, navigate, interact, network, console, screenshot, evaluate, script, tests) can be switched on or off in Settings → Developer.

3. Connect your agent

astral-mcp setup writes the right entry for the client you use. Pick yours, copy the command and run it in a terminal.

astral-mcp setup --client claude-code --project .

Writes .mcp.json in the project. Without --project it prints the official claude mcp add --scope user command instead of editing Claude Code's own state file.

astral-mcp setup --list shows every supported client and whether it is installed; --client all-detected sets up all of them, and --dry-run shows the diff first. Manual snippets, the check that it worked and clients that are not in the list (OpenCode, any other MCP client) are on Connect your agent.

4. A first prompt to try

With a tab shared and your agent connected, ask something like:

Open https://example.com in Astral, read the page, and tell me
what is on it. Then check its layout on a mobile viewport and
list any problems you find.

Once that works, ask for a real test:

Test the sign-up flow on my local app at http://localhost:3000.
Write it as a test with a step per screen, expect no console or network
errors, record the actions, and show me the report.

Continue with test runs to see what the agent writes and what it leaves behind.

Every docs page is also available as Markdown, so you can hand its URL to an AI agent: add .md to the page URL, or give the agent llms.txt, an index of all the pages.