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(schedules): scheduled tasks beside the timers, what has to be running, the approval card nobody is watching, and the wake-up helper

Shahriar3ca315f6f64f
diff --git a/docs/guide/features/README.md b/docs/guide/features/README.md
index c0ecb38..168abb4 100644
--- a/docs/guide/features/README.md
+++ b/docs/guide/features/README.md
@@ -30,7 +30,7 @@ first.
| | |
| --- | --- |
| [Monitoring](monitoring.md) | Watching an upload, a build or a deploy in the background |
-| [Scheduling](scheduling.md) | Doing something in ten minutes, or every two, without an agent sitting there |
+| [Scheduling](scheduling.md) | Tasks that run on their own — every weekday at nine, or once tomorrow — plus the timers an agent sets for itself |
| [Site maps](site-maps.md) | Teaching it a site once, so later sessions already know their way around |
| [Recordings](recordings.md) | Doing a repetitive job once yourself, then "do it like last time" |
diff --git a/docs/guide/features/scheduling.md b/docs/guide/features/scheduling.md
index 684500d..6b8a283 100644
--- a/docs/guide/features/scheduling.md
+++ b/docs/guide/features/scheduling.md
@@ -11,6 +11,70 @@ check the deploy queue every five minutes and tell me when something lands
in ten minutes, reload this and tell me whether the build passed
```
+There are two kinds. A **scheduled task** is one you set up and leave running — every weekday, every
+Friday evening, once tomorrow morning. A **timer** is one the agent sets for itself in the middle of a
+conversation. Tasks come first on this page.
+
+---
+
+## Scheduled tasks
+
+Open the **Schedules** tab in the side panel and press **New task**. Or turn on the clock beside the
+message box and send: what you typed becomes the task, and you pick when. **Repeat this…** under a
+message you already sent, and **Schedule** on a recording, do the same.
+
+```
+every weekday at 09:00, open github.com/pulls and summarise what is waiting on my review
+```
+
+Each run opens its own background tab on the task's page, does the job and closes the tab. The result
+arrives as a notice on the page you are looking at, and every run lands in the task's history — when it
+ran, how it went, its one-line result and, for the last three runs, the whole transcript. Scheduled
+runs never fill up the History tab.
+
+| | |
+| --- | --- |
+| **What it does** | An instruction the agent follows, or a recording replayed step by step. A replay needs no agent and spends no tokens; when a step no longer fits the page, the agent takes over from there |
+| **When** | Once at a set time, on chosen days at chosen times, or every so often — optionally only between two times of day. Five minutes is the shortest interval |
+| **Afterwards** | Tell you every run, only when one fails, or never. Skip a missed run, or run it once when things are back. Stop after some runs, or on a date |
+
+The editor shows the next three runs before you save, and for an instruction how many agent runs a
+week the schedule adds up to — each one spends tokens.
+
+The daemon keeps the schedule, in `~/.browsentic/schedules.json`, so one list covers every browser
+paired with it. `browsentic tasks` lists the tasks from a terminal, and pauses, resumes or deletes one.
+
+### What has to be running
+
+A run needs the browser open and the daemon up. The daemon starts itself when the browser needs it:
+`browsentic setup` registers a small helper that Chrome, Edge, Brave and Firefox can launch, and
+`browsentic status` says which browsers have it.
+
+A run that falls due while the browser is closed or the computer is asleep is logged as **missed**. By
+default it then runs once when both are back; a task set to **Skip it** just waits for its next time.
+
+### Approvals with nobody watching
+
+A scheduled run follows the same [guardrails](../approvals.md) as one you start yourself. When an
+action needs your OK, a card appears on the page you are looking at, with **Allow**, **Deny** and
+**Always on ‹site›**. With no answer in ten minutes the action is declined and the run says so. The
+card only takes a real click, and none in its first moment on screen, so the page underneath cannot
+press **Allow** for you.
+
+A scheduled run never gets Live tools, and it is told to end on one line that stands alone, because
+that line is what the notice and the history show.
+
+### Task or timer?
+
+| | Scheduled task | Timer |
+| --- | --- | --- |
+| Set by | you, in the Schedules tab | the agent, during a conversation |
+| Runs in | a fresh background tab each time | the conversation that set it |
+| When | clock times, days of the week, intervals | "in ten minutes", "every two minutes" |
+| Lasts | until you delete it | until its conversation ends, a day at most |
+
+The rest of this page is about timers.
+
---
## What happens
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index cbcd0bf..555a0d4 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -29,6 +29,7 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d
| "This browser has no speech service" | Brave and some Chromium builds ship speech recognition without a transcription service behind it | Type instead, or use Chrome or Edge for dictation |
| `EXTENSION_OFFLINE` | Browser closed, or not paired | Open the browser; `browsentic sessions` to check pairing |
| After a reboot the panel stays offline until you run a command | The browser has no helper registered to start the daemon | Run `browsentic setup` once. `browsentic status` then lists the browsers under `wake-up:` |
+| A scheduled task shows **Missed** | The browser was closed, the computer asleep, or no daemon was running at that time | Nothing to fix — it runs once when things are back unless the task says **Skip it**. `browsentic status` shows whether the browser can start the daemon itself |
| "Load unpacked" cannot see `~/browsentic` | A Flatpak or Snap browser, sandboxed away from your home directory. Snap Chromium is the Ubuntu default | Grant it: `flatpak override --user --filesystem=~/browsentic com.google.Chrome`. Or install somewhere the sandbox can read: `browsentic setup --dir ~/snap/chromium/common/browsentic-extension` |
| The folder picker does not show `~/browsentic` | It is there; some pickers open elsewhere by default | macOS: press ⇧⌘G and paste the path. Linux: Ctrl+L |
| Updated with `npx`, but the browser still runs the old build | Chrome never auto-reloads an unpacked extension | `browsentic status` names both versions. Press ↻ on the Browsentic card |
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index f207bdb..7278a86 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -81,7 +81,8 @@ it is the documented escape hatch.
## The panel's tabs
-`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Settings**.
+`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Schedules**,
+**Settings**.
Adding one is a variant in `PanelTab`, an entry in `TABS`, and a branch in the side panel's body —
there is no router.
@@ -93,8 +94,8 @@ learned, which is what keeps the strip from flapping between two fits at one pan
practice five labels want ~485 px and one wants ~225 px, so a side panel at its usual size lands on
the middle fit.
-**Settings** is two halves with nothing in common. **Guardrails** is the only panel state that
-lives on the daemon rather than in extension storage: it reads and writes `~/.browsentic/config.json`
+**Settings** is two halves with nothing in common. **Guardrails** lives on the daemon rather than in
+extension storage, like the Schedules tab's tasks: it reads and writes `~/.browsentic/config.json`
through two bridge ops, `guardrails` and `setGuardrail`, which forward to the socket frames of the
same name. The extension holds no copy — every write returns the daemon's fresh view, which is what
the panel then renders, and the whole half is empty until the daemon is up. **Appearance** never
@@ -225,6 +226,27 @@ entry leaves the registry.
Closing the side panel does **not** — the tab is the anchor. While a run is going, its tab carries a
dot on the toolbar badge and on its favicon.
+## Scheduled runs
+
+The daemon owns the schedule and the clock (`src/daemon/schedules/`); the extension only runs what it
+is handed. A due task arrives as a `runTask` frame, answered like an `invoke`. `startTaskRun` in
+`run-port.ts` opens a background tab and tags its session with the task. An instruction then goes
+through `startTurn` like the Send button's; a recording replays through `invokeForHarness`, step by
+step, handing a failed step to the agent. When the run settles, `finishTask` reports `taskDone`, files
+the transcript under `browsentic:taskRuns` instead of History, shows the notice and closes the tab.
+
+The task list reaches the panel the same way the agent state does: the daemon pushes `taskList` on
+connect and after every change, and the extension caches it in `browsentic/tasks` so the tab still
+renders while the daemon is down.
+
+An approval raised by a scheduled run is drawn as a toast on the page in front, not only in the panel.
+Its buttons answer through `answerApproval`, the panel's own path. Only the tab the card was drawn
+on can answer, only with `isTrusted` clicks, and none in its first 800 ms.
+
+`nativeMessaging` is what lets a browser start a daemon that is down. When no port answers,
+`giveUp` calls `wakeDaemon`, which asks the browser to run the `com.browsentic.daemon` host that
+`browsentic setup` registered. That host runs `ensureDaemon` and exits.
+
---
## Next
diff --git a/docs/internals/state.md b/docs/internals/state.md
index d76e57c..192873f 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -11,6 +11,7 @@ Nothing lives in the repository.
├── config.json optional, hand-written
├── 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
├── native-host/ the helper a browser launches to start the daemon
├── daemon.log run starts, routed skills, every tool call and its outcome
├── skills/ hand-written skill overrides
@@ -33,6 +34,7 @@ Nothing lives in the repository.
| `config.json` | You, and the agent picker | Re-read before every run — no restart needed. [Reference](../guide/configuration.md) |
| `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 |
| `native-host/` | `browsentic setup` | A launcher that runs this CLI with the `PATH` setup saw. Each browser gets a manifest in its own `NativeMessagingHosts` folder (a registry key on Windows) naming the extension origins allowed to use it; pairing adds the new one. `browsentic uninstall` removes both |
| `cli/`, `bin/`, `runtime/` | [Browsentic.app](../guide/mac-app.md) | Replaced whole on every app update. `cli/.browsentic-app.json` is what makes `installKind()` answer `app`, which turns the npm self-update off |
| `daemon.log` | The daemon | `browsentic logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index b940bc8..57b8bdb 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -101,11 +101,14 @@ configurations written against the older name keep working.
| `browsentic skills` | Every skill the router can see, tagged `bundled`, `user` or `uploaded` |
| `browsentic approvals` | The "always on this site" grants |
| `browsentic approvals clear [host]` | Forget them, all or one site's |
+| `browsentic tasks` | Scheduled tasks, when each runs next and how it last went |
+| `browsentic tasks pause\|resume [id]` | Pause or resume one task, or every task at once. An id prefix is enough |
+| `browsentic tasks delete <id>` | Delete a task |
| `browsentic downloads` | Files captured from pages, with notes and where they landed |
| `browsentic downloads clear` | Delete all of them |
| `browsentic token` | The control token, for MCP clients. Not for the browser |
-`agent`, `skills`, `approvals` and `downloads` take `--json`. It is what the [macOS app](../guide/mac-app.md)
+`agent`, `skills`, `approvals`, `tasks` and `downloads` take `--json`. It is what the [macOS app](../guide/mac-app.md)
reads, so the app and a terminal can never disagree about what is on disk.
## Lifecycle
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
index 51284d9..0c8f053 100644
--- a/docs/reference/errors.md
+++ b/docs/reference/errors.md
@@ -59,8 +59,17 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve
| `SESSION_TAB_CLOSED` | Extension | Every tab this conversation was working in has been closed |
| `TAB_IN_USE` | Extension | That tab belongs to another Browsentic conversation |
| `RUN_INACTIVE` | AgentSession | The run was cancelled while a tool call was in flight |
+| `APPROVAL_TIMEOUT` | AgentSession | A scheduled run asked for approval and nobody answered within ten minutes, so the action was declined. The agent is told to stop and say what it was about to do |
| `SKILL_UNKNOWN` | AgentSession | The attached agent skill's id no longer resolves — the file moved, changed agents, or outgrew the size cap. Reopen the `/` picker and choose again |
+## Scheduled tasks
+
+| Code | Origin | Meaning and next move |
+| --- | --- | --- |
+| `TASK_NOT_FOUND` | Daemon | No task with that id — deleted from another browser or from `browsentic tasks` |
+| `TASK_LIMIT` | Daemon | 25 tasks are already scheduled. Delete one first |
+| `REPLAY_UNAVAILABLE` | Extension | The task's recording is gone, was never turned into steps, or needs a value the task does not hold |
+
## Agents
| Code | Origin | Meaning and next move |