Skip to content

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.

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.md
index 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 configurable
Compiled-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.md
index 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 page
diff --git a/docs/guide/features/profile.md b/docs/guide/features/profile.md
new file mode 100644
index 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.md
index 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, do
not 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 the
panel's `/` picker. `RunContext.agentSkillId` is an opaque id the daemon minted while listing
the 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 the
run 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 agent
already holds, with the id `page_attachFile` takes. The reports themselves travel in the
message ([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 the
side 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, a
stops 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 its
session 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 the
user's own words:
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 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 |