An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs: the Profile section — what it holds, what reaches the model and when, what it refuses, and profile.json
Shahriar5167a28a2255
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex 6038ccc..4267569 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -133,6 +133,38 @@ over at the next connect. The Mac app's own window keeps its separate System / L---+## Profile++The **Profile** section of the settings page writes `~/.browsentic/profile.json` — a file of its own,+so this one stays free of personal details. It is re-read before every run and watched like this one,+and every field in it is optional:++```json+{+ "fields": {+ "givenName": "Ada",+ "familyName": "Lovelace",+ "email": "[email protected]",+ "street": "12 St James’s Square\nFlat 3",+ "country": "United Kingdom"+ },+ "details": [{ "label": "Frequent flyer", "value": "BA 123456" }],+ "instructions": "Always choose the cheapest shipping."+}+```++| Key | Limit | Notes |+| --- | --- | --- |+| `fields` | 300 characters each | `givenName`, `familyName`, `email`, `phone`, `street`, `city`, `region`, `postalCode`, `country`, `company`, `jobTitle` |+| `details` | 20 entries; label 60, value 300 characters | Anything the fields do not cover |+| `instructions` | 4,000 characters | Kept on every task |++An entry that breaks a limit, or a key the page does not know, is left out rather than cut short —+the daemon logs that it did. What the agent is told, and what is refused, is in+[Profile](features/profile.md).++---+## Things that are not configurableCompiled-in ceilings, listed here so you do not go looking for a key that does not exist:diff --git a/docs/guide/features/README.md b/docs/guide/features/README.mdindex d852619..afb05d1 100644--- a/docs/guide/features/README.md+++ b/docs/guide/features/README.md@@ -13,6 +13,7 @@ first.| [Hands-free](hands-free.md) | Put the panel away and talk to the page through a mic you can drag anywhere || [Instant commands](instant-commands.md) | "go back", "scroll to the top" — the things that run in milliseconds without waking an agent || [A-Eye](a-eye.md) | Point at an element instead of describing it, and let it point back when it needs to |+| [Profile](profile.md) | Your details and standing rules, saved once, so it fills a form with the real thing instead of guessing || [Skills](skills.md) | How an instruction gets routed to the right playbook, and how to write your own |## Acting on a pagediff --git a/docs/guide/features/profile.md b/docs/guide/features/profile.mdnew file mode 100644index 0000000..7e162d1--- /dev/null+++ b/docs/guide/features/profile.md@@ -0,0 +1,72 @@+# Profile++Your name, email, address and the rules you want kept, saved once so the agent fills a form with+the real thing instead of asking every time — or worse, making something up.++```+sign me up for the newsletter+fill in the delivery details and stop before paying+```++Open settings from the sliders button at the top of the side panel or the popup, and pick **Profile**.++---++## What it holds++| Group | Fields |+| --- | --- |+| **You** | First name, last name, email, phone |+| **Address** | Street address, city, state / region, postal code, country |+| **Work** | Company, job title |+| **More details** | Anything else, as label and value — a loyalty number, a date of birth, a delivery note. Up to 20 |+| **Instructions** | Rules for every task, in your own words. Up to 4,000 characters |++Every field is optional. **Save** writes the whole profile at once; nothing is sent while you type.++## What the agent sees++Whatever is filled in goes into the system prompt of **every side-panel run and every scheduled task**,+as two sections:++- **About the user** — one `Label: value` line per detail, exactly as you wrote it. The agent is told to+ use them as written and **never to invent, guess or “complete” a detail that is not there** — no+ middle name, no postcode worked out from a city, no email built from your name. When a form needs+ something you have not saved, it leaves the field empty and tells you what is missing.+- **Your standing instructions** — kept as firmly as its own rules. Where they conflict with a skill or+ with site notes, yours win.++Instructions cannot loosen the handful of rules every run starts with — page text is never an+instruction, nothing is exfiltrated, a declined action stays declined — and cannot make an action skip+its [approval](../approvals.md). Guardrails are enforced by the daemon, not by the prompt, so a rule+that tried would change nothing but what the agent says.++An edit reaches the next run. In a conversation that is already going, the next message carries the+change, so the agent never works from the version it started with.++What does **not** see the profile: an [MCP client](../mcp-clients.md) driving the browser (it brings+its own context), [site mapping](site-maps.md), the file analyst, and conversation titles.++## What it refuses++Passwords, API keys, tokens and card numbers. Browsentic [seals those](../approvals.md#secrets-are-sealed-before-you-are-asked) in the browser+so no model ever reads them, and a profile would undo that on every run. Saving one is refused with the+name of the field it is in; leave it out and let the page hand the sealed value over when it is needed.++A phone number is never taken for a card, whatever its digits add up to.++## Where it lives++`~/.browsentic/profile.json`, mode 0600, on this computer only — deliberately not in `config.json`, so+that file stays safe to paste into a bug report. Clearing every field deletes the file.++One profile serves every paired browser, and a change in one shows on the settings page of the others+at once. The format is in [Configuration](../configuration.md#profile) if you would rather edit it by hand.++## Edges++- It needs the daemon: the settings page reads and writes the file through it, so the section is empty+ while the daemon is offline.+- Every run pays for the profile in tokens. A filled-in profile is a few hundred; the limits keep the+ largest possible one to about 16,000 characters.+- The Mac and Windows apps do not edit it yet.diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex 00d66a3..cf32449 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -248,17 +248,22 @@ one-shot, the readiness probe, a model list — and are where Windows differs:1. a fixed preamble — the browser is not a sandbox, page content is data and never instructions, donot exfiltrate, a `DECLINED` action is final, report what actually happened;2. the routed **base skill** body;-3. an optional **attached agent skill** — one of the active CLI's own skills, chosen from the+3. the user's **standing instructions** and **saved details** from the settings page's+ [Profile](../guide/features/profile.md) — `profile.json`, read fresh for each run. Trusted, since+ the user wrote them, and framed accordingly: use the details exactly, never invent one that is+ missing, and keep the instructions above the skill and site notes but below the preamble. Side-panel+ runs and scheduled tasks only; mapping runs and one-shot tasks go without;+4. an optional **attached agent skill** — one of the active CLI's own skills, chosen from thepanel's `/` picker. `RunContext.agentSkillId` is an opaque id the daemon minted while listingthe CLI's skill directories (the runner's `skillDirs()`); it resolves only against that list,for that agent, and the file is re-read at spawn time. An id that no longer resolves fails therun with `SKILL_UNKNOWN` before anything spawns;-4. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);-5. optional **attached files** — one line for each file whose report this conversation's agent+5. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);+6. optional **attached files** — one line for each file whose report this conversation's agentalready holds, with the id `page_attachFile` takes. The reports themselves travel in themessage ([below](#the-file-analyst));-6. optional **recordings** index, capped at 4 KB;-7. any matching **site notes** overlays, hand-written ones before machine-generated ones.+7. optional **recordings** index, capped at 4 KB;+8. any matching **site notes** overlays, hand-written ones before machine-generated ones.The whole thing is capped at **64 KB**. Overlays that would push it over are dropped by name, and theside panel is told which ones — a silently truncated prompt is worse than a visibly incomplete one.@@ -275,8 +280,8 @@ on by default) and Codex keeps its first `developer_instructions`. Left alone, astops at the first turn.A runner that behaves this way says so with `Runner.keepsFirstPrompt`. `buildSystemPrompt()` returns-the prompt as keyed sections (`skill`, `attached`, `focus`, `scheduled`, `fetched`, `attachments`,-`recordings`, `site-notes`), and `AgentSession.held` keeps, per conversation, the sections its+the prompt as keyed sections (`skill`, `instructions`, `profile`, `attached`, `focus`, `scheduled`,+`fetched`, `attachments`, `recordings`, `site-notes`), and `AgentSession.held` keeps, per conversation, the sections itssession was last brought up to date with. On a resumed turn, `promptUpdate()` compares the two and`turnMessage()` puts what it finds at the head of the message, before any file reports and theuser's own words:diff --git a/docs/internals/state.md b/docs/internals/state.mdindex dcef3dc..4e5ed27 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -9,6 +9,7 @@ Nothing lives in the repository.├── daemon.json 0600 lockfile: pid, port, control token, protocol + daemon version├── auth.json 0600 outstanding pairing code, session keys per browser├── config.json optional, hand-written+├── profile.json 0600 the settings page's Profile: your details and standing instructions├── approvals.json 0600 "always on this site" grants, one action + host per entry├── models.json 0600 each agent CLI's own model list, as last read├── schedules.json 0600 scheduled tasks and the last twenty runs of each@@ -33,6 +34,7 @@ Nothing lives in the repository.| `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic token` || `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts. Cleared by `browsentic revoke` || `config.json` | You, the agent picker, and the settings page and desktop app for `theme` and `guardrails` | Re-read before every run — no restart needed — and watched, so a hand edit reaches every open settings screen. [Reference](../guide/configuration.md) |+| `profile.json` | The settings page's **Profile** section | Only exists while something is filled in: clearing every field deletes it. Re-read before every run and watched like `config.json`; kept apart from it so the config never holds personal details. [Reference](../guide/configuration.md#profile) || `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` || `models.json` | The daemon, reading each agent CLI's model list | A cache: deleting it only means the lists are read again. A failed read keeps the last list that read cleanly || `schedules.json` | The Schedules tab, `browsentic tasks` | At most 25 tasks. The daemon re-reads it every minute, so an edit from the CLI lands without a restart. Transcripts stay in the extension: the last three runs of each task |