AGENTS.md

1# AGENTS.md
2 
3Instructions for AI coding agents working with this codebase.
4 
5## Package Manager
6 
7This project uses **pnpm**. Always use `pnpm` instead of `npm` or `yarn` for installing dependencies, running scripts, etc. (e.g., `pnpm install`, `pnpm run build`).
8 
9## Code Style
10 
11- Do not use emojis in code, output, or documentation. Unicode symbols (✓, ✗, →, ⚠) are acceptable.
12- In documentation and markdown, never use double hyphens (`--`) as a dash. Use an emdash (—) sparingly when needed. Prefer rewriting the sentence to avoid dashes entirely.
13- CLI colored output uses `cli/src/color.rs`. This module respects the `NO_COLOR` environment variable. Never use hardcoded ANSI color codes.
14- CLI flags must always use kebab-case (e.g., `--auto-connect`, `--allow-file-access`). Never use camelCase for flags (e.g., `--autoConnect` is wrong).
15 
16## Documentation
17 
18Do not hard-wrap prose in documentation files such as Markdown, MDX, and READMEs; let the editor or renderer wrap text naturally.
19 
20When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:
21 
221. `cli/src/output.rs` — `--help` output (flags list, examples, environment variables)
232. `README.md` — Options table, relevant feature sections, examples
243. `skill-data/core/SKILL.md` (and its `references/`) — so AI agents know about the feature when they load the core skill. Edit `skill-data/core/SKILL.md` for overview/workflow changes; edit `skill-data/core/references/*.md` for detailed reference content. Do **not** put feature content in `skills/agent-browser/SKILL.md` — that file is an intentionally thin discovery stub for `npx skills add` and exists only to redirect agents to `agent-browser skills get core`.
254. `docs/src/app/` — the Next.js docs site (MDX pages)
265. Inline doc comments in the relevant source files
27 
28This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
29 
30## CLI/MCP Parity
31 
32When adding or changing any CLI command, flag, behavior, output, environment variable, or parser semantics, update the MCP server in `cli/src/mcp.rs` in the same change. MCP tools should stay in sync with canonical CLI behavior by delegating through the normal CLI parser where possible. If a CLI command has no dedicated MCP tool, add one or document why it is intentionally omitted. Add or update tests that prove the CLI and MCP surfaces remain aligned.
33 
34In the `docs/src/app/` MDX files, always use HTML `<table>` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.
35 
36## Dashboard (packages/dashboard)
37 
38- Never use native browser dialogs (`alert`, `confirm`, `prompt`). Use shadcn/ui components (`Dialog`, `AlertDialog`, etc.) instead.
39- Use param-case (kebab-case) for all file and folder names (e.g., `session-tree.tsx`, not `SessionTree.tsx`). The `ui/` directory follows shadcn conventions which already uses param-case.
40 
41## Releasing
42 
43Releases are manual, single-PR affairs. There is no changesets automation. The maintainer controls the changelog voice and format.
44 
45To prepare a release:
46 
471. Create a branch (e.g. `prepare-v0.24.0`)
482. Bump `version` in `package.json`
493. Run `pnpm version:sync` to update `cli/Cargo.toml`, `cli/Cargo.lock`, and `packages/dashboard/package.json`
504. Write the changelog entry in `CHANGELOG.md` at the top, under a new `## <version>` heading, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry so only the new release has markers.
515. Add a matching entry to `docs/src/app/changelog/page.mdx` at the top (below the `# Changelog` heading)
526. Open a PR and merge to `main`
53 
54When the PR merges, CI compares `package.json` version to what's on npm. If it differs, it builds all 7 platform binaries, publishes to npm, and creates the GitHub release automatically. The GitHub release body is extracted from the content between the `<!-- release:start -->` and `<!-- release:end -->` markers in `CHANGELOG.md`.
55 
56### Writing the changelog
57 
58Review the git log since the last release and write the entry in `CHANGELOG.md`. Follow the existing format and voice. Group changes under `### New Features`, `### Bug Fixes`, `### Improvements`, etc. Bold the feature/fix name, then describe it concisely. Reference PR numbers in parentheses.
59 
60Wrap the release notes (everything between the `## <version>` heading and the previous version) in markers so CI can extract them for the GitHub release. Only the current release should have markers; remove the `<!-- release:start -->` and `<!-- release:end -->` markers from any previous release entry:
61 
62```markdown
63## 0.24.1
64 
65<!-- release:start -->
66### Bug Fixes
67 
68- Fixed **baz** not working when qux is enabled (#1235)
69 
70### Contributors
71 
72- @ctate
73<!-- release:end -->
74 
75## 0.24.0
76 
77### New Features
78 
79- **Foo command** - Added `foo` command for bar (#1234)
80```
81 
82Include a `### Contributors` section listing the GitHub usernames (with `@` prefix) of everyone who contributed to the release. Check the git log between the previous tag and HEAD to find them.
83 
84Do not prefix entries with commit hashes. Do not use the changesets `### Patch Changes` / `### Minor Changes` headings. Use descriptive section names instead.
85 
86### Docs changelog
87 
88The docs changelog at `docs/src/app/changelog/page.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
89 
90- A `v` prefix on the version (e.g. `## v0.24.0`)
91- A date line with the full date: `<p className="text-[#888] text-sm">March 30, 2026</p>`
92- A `---` separator between entries
93 
94Match the existing style in that file.
95 
96## Architecture
97 
98This is a Rust codebase. The browser automation daemon lives in `cli/src/native/` (daemon, actions, browser, CDP client, snapshot, state). The `--engine` flag selects Chrome vs Lightpanda. The `install` command downloads Chrome from Chrome for Testing directly.
99 
100## Testing
101 
102### Unit Tests
103 
104```bash
105cd cli && cargo test
106```
107 
108Runs all unit tests (~320 tests). These are fast and don't require Chrome.
109 
110### End-to-End Tests
111 
112```bash
113cd cli && cargo test e2e -- --ignored --test-threads=1
114```
115 
116Runs 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:
117 
118- Chrome must be installed
119- Must run serially (`--test-threads=1`) to avoid Chrome instance contention
120- Tests are `#[ignore]`'d so they don't run during normal `cargo test`
121 
122The e2e tests live in `cli/src/native/e2e_tests.rs` and cover: launch/close, navigation, snapshots, screenshots, form interaction, cookies, storage, tabs, element queries, viewport/emulation, domain filtering, diff, state management, error handling, and Phase 8 commands.
123 
124### Linting and Formatting
125 
126```bash
127cd cli && cargo fmt -- --check   # Check formatting
128cd cli && cargo clippy            # Lint
129```
130 
131## Windows Debugging
132 
133A remote Windows Server 2022 EC2 instance is available for debugging Windows-specific issues. It uses AWS Systems Manager (SSM) with no SSH or open ports. Commands run via `aws ssm send-command` and return stdout/stderr.
134 
135### Prerequisites
136 
137The instance must be provisioned first (one-time, by a human):
138 
139```bash
140./scripts/windows-debug/provision.sh
141```
142 
143Requires: AWS CLI v2 configured with `ec2:*`, `iam:CreateRole`, `iam:AttachRolePolicy`, `ssm:SendCommand`, `ssm:GetCommandInvocation` permissions and a default VPC.
144 
145### Usage
146 
147Start the instance (if stopped):
148 
149```bash
150./scripts/windows-debug/start.sh
151```
152 
153Run a command on Windows:
154 
155```bash
156./scripts/windows-debug/run.sh &quot;&lt;powershell-command&gt;&quot;
157```
158 
159Sync the current git branch and rebuild:
160 
161```bash
162./scripts/windows-debug/sync.sh
163```
164 
165Stop the instance when done (avoids cost):
166 
167```bash
168./scripts/windows-debug/stop.sh
169```
170 
171### Common Workflows
172 
173Run unit tests on Windows:
174 
175```bash
176./scripts/windows-debug/run.sh &quot;cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml&quot;
177```
178 
179Run e2e tests on Windows:
180 
181```bash
182./scripts/windows-debug/run.sh &quot;cd C:\agent-browser && cargo test e2e --manifest-path cli\Cargo.toml -- --ignored --test-threads=1&quot;
183```
184 
185Check bootstrap progress (first boot only):
186 
187```bash
188./scripts/windows-debug/run.sh &quot;Get-Content C:\bootstrap.log&quot;
189```
190 
191The repo lives at `C:\agent-browser` on the instance. Rust, Git, and Chrome are pre-installed. The `run.sh` wrapper automatically adds cargo and git to PATH.
192 
193<!-- opensrc:start -->
194 
195## Source Code Reference
196 
197Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
198 
199See `opensrc/sources.json` for the list of available packages and their versions.
200 
201Use this source code when you need to understand how a package works internally, not just its types/interface.
202 
203### Fetching Additional Source Code
204 
205To fetch source code for a package or repository you need to understand, run:
206 
207```bash
208npx opensrc &lt;package&gt;           # npm package (e.g., npx opensrc zod)
209npx opensrc pypi:&lt;package&gt;      # Python package (e.g., npx opensrc pypi:requests)
210npx opensrc crates:&lt;package&gt;    # Rust crate (e.g., npx opensrc crates:serde)
211npx opensrc &lt;owner&gt;/&lt;repo&gt;      # GitHub repo (e.g., npx opensrc vercel/ai)
212```
213 
214<!-- opensrc:end -->
215