1  # AGENTS.md
  2  
  3  Instructions for AI coding agents working with this codebase.
  4  
  5  ## Package Manager
  6  
  7  This 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  
 18  When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:
 19  
 20  1. `cli/src/output.rs` — `--help` output (flags list, examples, environment variables)
 21  2. `README.md` — Options table, relevant feature sections, examples
 22  3. `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`.
 23  4. `docs/src/app/` — the Next.js docs site (MDX pages)
 24  5. Inline doc comments in the relevant source files
 25  
 26  This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
 27  
 28  In 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.
 29  
 30  ## Dashboard (packages/dashboard)
 31  
 32  - Never use native browser dialogs (`alert`, `confirm`, `prompt`). Use shadcn/ui components (`Dialog`, `AlertDialog`, etc.) instead.
 33  - 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.
 34  
 35  ## Releasing
 36  
 37  Releases are manual, single-PR affairs. There is no changesets automation. The maintainer controls the changelog voice and format.
 38  
 39  To prepare a release:
 40  
 41  1. Create a branch (e.g. `prepare-v0.24.0`)
 42  2. Bump `version` in `package.json`
 43  3. Run `pnpm version:sync` to update `cli/Cargo.toml`, `cli/Cargo.lock`, and `packages/dashboard/package.json`
 44  4. 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.
 45  5. Add a matching entry to `docs/src/app/changelog/page.mdx` at the top (below the `# Changelog` heading)
 46  6. Open a PR and merge to `main`
 47  
 48  When 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`.
 49  
 50  ### Writing the changelog
 51  
 52  Review 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.
 53  
 54  Wrap 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:
 55  
 56  ```markdown
 57  ## 0.24.1
 58  
 59  <!-- release:start -->
 60  ### Bug Fixes
 61  
 62  - Fixed **baz** not working when qux is enabled (#1235)
 63  
 64  ### Contributors
 65  
 66  - @ctate
 67  <!-- release:end -->
 68  
 69  ## 0.24.0
 70  
 71  ### New Features
 72  
 73  - **Foo command** - Added `foo` command for bar (#1234)
 74  ```
 75  
 76  Include 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.
 77  
 78  Do not prefix entries with commit hashes. Do not use the changesets `### Patch Changes` / `### Minor Changes` headings. Use descriptive section names instead.
 79  
 80  ### Docs changelog
 81  
 82  The docs changelog at `docs/src/app/changelog/page.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
 83  
 84  - A `v` prefix on the version (e.g. `## v0.24.0`)
 85  - A date line with the full date: `<p className="text-[#888] text-sm">March 30, 2026</p>`
 86  - A `---` separator between entries
 87  
 88  Match the existing style in that file.
 89  
 90  ## Architecture
 91  
 92  This 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.
 93  
 94  ## Testing
 95  
 96  ### Unit Tests
 97  
 98  ```bash
 99  cd cli && cargo test
100  ```
101  
102  Runs all unit tests (~320 tests). These are fast and don't require Chrome.
103  
104  ### End-to-End Tests
105  
106  ```bash
107  cd cli && cargo test e2e -- --ignored --test-threads=1
108  ```
109  
110  Runs 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:
111  
112  - Chrome must be installed
113  - Must run serially (`--test-threads=1`) to avoid Chrome instance contention
114  - Tests are `#[ignore]`'d so they don't run during normal `cargo test`
115  
116  The 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.
117  
118  ### Linting and Formatting
119  
120  ```bash
121  cd cli && cargo fmt -- --check   # Check formatting
122  cd cli && cargo clippy            # Lint
123  ```
124  
125  ## Windows Debugging
126  
127  A 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.
128  
129  ### Prerequisites
130  
131  The instance must be provisioned first (one-time, by a human):
132  
133  ```bash
134  ./scripts/windows-debug/provision.sh
135  ```
136  
137  Requires: AWS CLI v2 configured with `ec2:*`, `iam:CreateRole`, `iam:AttachRolePolicy`, `ssm:SendCommand`, `ssm:GetCommandInvocation` permissions and a default VPC.
138  
139  ### Usage
140  
141  Start the instance (if stopped):
142  
143  ```bash
144  ./scripts/windows-debug/start.sh
145  ```
146  
147  Run a command on Windows:
148  
149  ```bash
150  ./scripts/windows-debug/run.sh "<powershell-command>"
151  ```
152  
153  Sync the current git branch and rebuild:
154  
155  ```bash
156  ./scripts/windows-debug/sync.sh
157  ```
158  
159  Stop the instance when done (avoids cost):
160  
161  ```bash
162  ./scripts/windows-debug/stop.sh
163  ```
164  
165  ### Common Workflows
166  
167  Run unit tests on Windows:
168  
169  ```bash
170  ./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml"
171  ```
172  
173  Run e2e tests on Windows:
174  
175  ```bash
176  ./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test e2e --manifest-path cli\Cargo.toml -- --ignored --test-threads=1"
177  ```
178  
179  Check bootstrap progress (first boot only):
180  
181  ```bash
182  ./scripts/windows-debug/run.sh "Get-Content C:\bootstrap.log"
183  ```
184  
185  The 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.
186  
187  <!-- opensrc:start -->
188  
189  ## Source Code Reference
190  
191  Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
192  
193  See `opensrc/sources.json` for the list of available packages and their versions.
194  
195  Use this source code when you need to understand how a package works internally, not just its types/interface.
196  
197  ### Fetching Additional Source Code
198  
199  To fetch source code for a package or repository you need to understand, run:
200  
201  ```bash
202  npx opensrc <package>           # npm package (e.g., npx opensrc zod)
203  npx opensrc pypi:<package>      # Python package (e.g., npx opensrc pypi:requests)
204  npx opensrc crates:<package>    # Rust crate (e.g., npx opensrc crates:serde)
205  npx opensrc <owner>/<repo>      # GitHub repo (e.g., npx opensrc vercel/ai)
206  ```
207  
208  <!-- opensrc:end -->