Copy this into your coding agent:
Set up https://github.com/browser-use/agency and start Agency.
Create a me.md file and make the first 10 suggestions.
Agency finds useful work. It learns what you care about and prepares fixes, replies and ideas.
Read the Agency skill, then follow the setup below. The package starts empty. It includes no personal profile, tickets, customer media or credentials.
Requires Node.js 22.13 or later and npm.
git clone https://github.com/browser-use/agency.git
cd agency
npm ci
npm run dev -- --hostname localhost --port 3100Open http://localhost:3100. If occupied, choose an unused port and set RADAR_URL to the server's
actual URL. Reuse the intended checkout and server. The local SQLite/D1 database initializes under
.wrangler/; no Cloudflare account or hosted deployment is required.
Keep the app on loopback. This is a trusted single-user app with unauthenticated routes, not a
multi-user service. Do not expose it with 0.0.0.0 or a public tunnel. Only ingest trusted agent
content. A private repository does not protect an exposed server.
node scripts/install-skill.mjs --codex
# Or:
node scripts/install-skill.mjs --claudeThe installer copies skills/agency/, including its approval and layout defaults, to your own skill directory.
It refuses to overwrite an existing installation. Review and back up an existing copy before updating;
a new agent session loads installed changes. You can also read the skill directly from this checkout.
There is one Agency skill, with an editable
approval policy and layout.
Installation grants no service access and creates no worker or schedule. Use your own authorized
accounts. The existing standalone no-ai-slop skill can help with copy; it is not bundled or required
to run this app.
Keep one coding-agent session responsible for Agency. Use the prompt above.
Use the checkout and app URL chosen during setup. A cloud worker cannot automatically reach your laptop's localhost, files or signed-in browser.
The coding agent starts by reading the skill, infers a short editable profile from relevant context, and creates the first cards. The website also lets you enter a dream. Save dream saves that brief; it does not launch an agent. There is no installed background worker, automatic thread injection or built-in connector wizard. The active coding agent reads jobs, assigns workers and verifies their results.
The agent reads your brief, relevant Codex or Claude prompts, feedback and past work to learn your goals, role and everyday tools. It learns your words from your prompts and sent messages, keeping a few short examples in a private profile. Subagents research and prepare useful cards in parallel; one coordinator handles duplicates and approvals. You need not finish an interview first.
Startup discovers available connectors, APIs, CLIs and authorized sessions, then verifies useful sources with a live read. Those may include Gmail, Slack, Granola, Calendar, repositories, support, analytics and Linear. For a useful missing connection, it explains the benefit and offers a verified setup path while continuing elsewhere. It follows fresh and older leads to prepare replies, posts, fixes, outreach or briefs, checking why each matters now. Setup chores do not count as suggestions.
The agent investigates, writes small fixes, builds private briefs and prepares demos before asking. Cards show the result and the remaining decision. Larger projects can start with a researched scope. Replies include the incoming message; uncertain decisions offer useful alternatives. Send approves the shown reply, Apply approves the shown change, and Merge needs the actual diff. Before a message, post or shared change is visible to others, it needs your approval for that action. Clear feedback can approve edits and execution together, such as "shorten this and send it". Before acting, the agent checks for newer replies, fixes or changed plans. It reuses approval through harmless changes and revisits material ones.
If ongoing work is useful, agree to a four-hour cadence or choose another. The agent uses its runner's scheduler, reuses any matching schedule and records the real checkout, app URL, profile and approval-policy/layout paths. It reports a meaningful result or blocker, not empty periodic updates. A cadence written in a profile does not itself run anything.
| File | Purpose |
|---|---|
| SKILL.md | How Agency learns, delegates, proves results and handles decisions |
| LAYOUT.md | Editable card appearance, graphics, typography and explanation style |
| APPROVALS.md | Editable defaults for what the agent may do and when it asks |
me.md, private |
Your dream, writing style, preferences, sources and constraints |
| This README | Setup, profile synchronization, access and the app API |
Keep evidence, exact drafts, one-off approvals and outcomes in local card/job history. Keep credentials in your runner's secret store.
For personal approval settings, copy the default to a private location such as checkout-root
approvals.local.md and tell the agent its absolute APPROVALS_PATH. That filename and me.md
are Git-ignored. The installer also gives you your own editable policy beside the installed skill.
The agent reads the policy; the app does not enforce it. Current explicit restrictions and runner
rules take precedence. Do not infer broader permission from past acceptance.
The default asks for big useful graphics, short labels, original messages, exact changes and clear choices. Cards use as little text as needed; supporting evidence can expand. No theme selection is needed. Each card must explain the full decision on its own.
Just tell Agency what to change. It edits your local skill or layout. For example:
- “Make the title four words. Use bigger graphics. Put the context behind an expand button.”
- “Show the original customer message and the exact reply before I approve.”
- “When the answer is uncertain, offer a few different options.”
- “Make my cards look like Pokémon cards, with a big illustration and very little text.”
The example above shows one short title, a big before/after, expandable context, the exact fix, the reply and an action. The skill guides the agent; it chooses a layout and action labels that fit the work. Agency shows one preview before a broad redesign.
The shared default is skills/agency/LAYOUT.md. To keep a personal version outside the shared
skill, copy it to checkout-root layout.local.md and tell the agent its absolute LAYOUT_PATH.
That filename is Git-ignored. Use one selected layout, not competing instructions in me.md;
your goals and outgoing writing voice remain in the private profile.
The coordinator reads the layout at startup and passes the resolved path to every card-making or reviewing worker. They read it before working and again after changes. These are agent instructions, not automatic file injection, a website setting or a CSS theme engine. Updating the file alone does not restyle existing cards or update older installed skill copies. Themes change presentation, not approvals, evidence, scores or host controls.
Use ME_PATH for your private file and RADAR_URL for the running app. The default profile path
is checkout-root me.md. Check both sides before selecting a direction.
export RADAR_URL=http://localhost:3100
export ME_PATH=/absolute/path/to/me.md
node scripts/sync-me.mjs --check- Existing file into a fresh app:
node scripts/sync-me.mjs --file-to-app. - Newly entered app dream into a new file:
node scripts/sync-me.mjs --app-to-file. - No flag: synchronize whichever side has the newer timestamp.
An empty source cannot overwrite a nonempty profile. Legacy --pull (file to app) and --push
(app to file) remain supported. The agent handles this copying; the user need not manage it.
Synchronize before work waves and after authorized profile edits. The agent learns from evidence
and edits the relevant profile section; it does not keep a diary or copy whole private threads.
Start with the sources that serve your goal, not a checklist of every service.
| Goal | Useful sources |
|---|---|
| Product pain | Repositories, support tickets, Slack and authorized telemetry |
| Writing and relationships | Your sent emails, Slack messages and relevant prior sessions |
| Distribution | Live social conversations, docs, examples and working integrations |
The agent checks registered tools and authorized browser sessions. It distinguishes an exposed tool from an authenticated account and a successful live read. A Chrome login does not prove a connector has access or uses the same account.
For missing access, it explains what a connection unlocks and provides the real connection URL returned by that integration. No invented links, password requests or bypassing consent/MFA. Naming Slack or Gmail in the dream does not connect it. Unavailable sources remain "not checked"; work on other sources continues.
Agency's app uses the local database. An active agent can also use your authenticated Linear connector, API or CLI for shared tickets, owners and status. The short Linear instructions cover finding and linking issues, scoped updates and one-off transfers. The agent chooses the tools and timing within your existing authorization; there is no Linear bridge or continuous synchronization.
Teammates can collaborate on the native Linear issues. Agency's profile, full decision history and visual assets remain local, so another person's Agency is not automatically the same feed. The agent shares selected material only with the authorized audience and verifies the result. Starting Agency or opening the website never migrates your private records to Linear by itself.
Use Browser Harness with real local Chrome.
Follow its setup guide
and installed skill; diagnose with browser-harness --doctor.
Keep task tab IDs, use the default daemon and coordinate shared-page or native-UI operations. Do not take over the user's tab. Close only unneeded task-created tabs. Use cloud isolation when needed, with authorized access and spend. Local logins do not transfer automatically; cookie or private-state uploads require approval. Follow the runtime's cleanup rules. Documented APIs and CLIs need no browser.
Cards show who is affected, the problem, draft or proposed outcome and exact action. They can use real screenshots, short diagrams, SVG animations, messages, full colorful diffs or recorded demos. The body may vary; feedback and navigation stay consistent. New arrivals preserve the selected card.
A successful decision click queues work and advances the feed. View-only Open buttons stay on the card. A queued approval is not yet a completed ticket: the agent must execute and verify it. Auto-improve and Skip do not count as Done. The host supplies those two card controls; the agent chooses the other actions. Auto-improve queues a request to use the skill. The website adds no next-step buttons or fixed reply options.
Hover over supported controls to see their shortcut. S skips, I improves, and left/right arrows navigate while you are not typing. Enter outside editable controls focuses feedback; Enter in the feedback field sends it, while Shift+Enter inserts a newline. No keyboard shortcut is assigned to New task, Start, task-composer Send or arbitrary in-card actions.
Use the supplied app root and RADAR_URL. Inspect the current routes if this checkout differs;
a cloud worker does not automatically have local app access. Keep the app on loopback.
Include x-radar-local-agent: 1 for local agent requests.
GET /api/agent-jobsreturns available latest jobs, not an exclusive claim. ReadcardContext,userFeedback,buttonLabel,instructionand orderedhistory. History results are truncated to 600 characters; use full local history read-only when a missing detail matters.GET /api/stateexposes current context, cards and decisions with view/light-dependent coverage. Inspect its response and route before treating it as the complete archive. Search all statuses, versions, feedback, jobs and source anchors for duplicates; fall back to bounded read-only local database queries when necessary.- One coordinator assigns each job.
POST /api/agent-jobswith{"id":123,"status":"running"}starts work; repeated running updates renew its six-hour lease. GET may return expired running work asreclaimed: true, subject to ten concurrent slots. The API has no exclusive worker token. Coordinate other active agents and recheck live state; do not assume a successful running update prevents another worker from acting. - Reuse the canonical
dedupeKey, based on project, subject, problem, outcome and stable anchors. A different title, timestamp or agent is not new work. Enrich existing New/Working cards; revive completed/rejected work only when fresh evidence addresses the prior outcome or rejection.
POST the job ID, result and one of these combinations after claiming it:
| status | ticketOutcome | Meaning / card lane |
|---|---|---|
| done | completed | Exact promised outcome verified; Done and completion points |
| done | review | Prepared/revised work awaiting a decision; New |
| failed | blocked | Precise blocker; New, visibly blocked |
A missing successful outcome defaults to review. Skip creates no job and never counts as Done. An Improve or ordinary Change needs a complete replacement and review outcome when evidence and duplicate checks establish readiness. Otherwise keep the revision private and use the blocked path; do not present unchecked send actions. A Change containing exact merge/send approval can be completed only after that action and its validation succeed. Terminal updates cannot resurrect a job; a same-terminal-status retry does not rewrite the result. Results are limited to 20,000 characters. Check newer jobs before finalizing or acting on old approval.
If work is complete, record the result without inventing a new decision. If the premise changed or work is blocked, replace the misleading card with the current facts and any meaningful next option. Never add an Acknowledge/Keep blocked no-op. Keep actual in-flight checks Working until they finish.
Write one HTML file and a metadata JSON file in the configured app. The metadata requires
project, category, headline, dedupeKey, the four rise components, and cardHtmlFile
relative to the JSON file. Include effortSeconds, effortReason, agentContext, sourceLabel,
sourceUrl and agentName where useful. Run:
RADAR_URL=http://localhost:3100 npm run card:push -- path/to/card.jsonThe script reads the file and POSTs cardHtml to /api/ideas. HTML must be 80-250,000 characters;
private agentContext is limited to 100,000. Store enough exact sources, files, validation, prior
work and action scope to continue without asking the user to retell the task. Keep private evidence
out of outgoing messages and public artifacts; use only the useful private excerpt on local cards.
Ordinary upsert retains ID, increments version, replaces content/metadata and returns the card to
New with a fresh timestamp. It does not enforce expectedVersion. Coordinate writes and reread
before replacement; do not use it for a cosmetic update that reopens completed or skipped work.
Use a supported state-preserving presentation path when available, otherwise keep that redesign
private. Never edit approval text during a presentation-only change.
For a blocked replacement, first finish the latest job as failed/blocked. Then push the same
dedupeKey, actual blockedJobId, current expectedVersion, a visible
data-radar-state="blocked" element and no Do action. This guarded update preserves status,
score, ordering and job outcome. On 409, reread; do not guess a new version or replay approval.
New Task snapshots may omit version, so retrieve the current card first.
Use standalone HTML/CSS and local assets. No scripts, event handlers, iframes, forms, object/embed, meta/base/link, inline svg/math, anchor tags, remote fonts, remote media or automatic external requests. For navigation use an Open button; for SVG use a local image file.
data-radar-action="do"plusdata-radar-prompt: queues the exact shown action.data-radar-action="open"plusdata-radar-url: view-only HTTP(S) link, with a visible ↗.- No card-level Change, Improve or Skip. The host owns those controls and the feedback field.
Decision-ready cards need at least one meaningful Do action at the actual boundary. A blocked card may have no action under the guarded exception above. A clicked card goes Working while the user continues through New. Preserve selected ID across new cards, resorting and replacement; update its content directly and retain feedback/expanded details. Do not alter host sort to move attention.
The API stores rise.reach, rise.impact, rise.strategicFit, rise.ease from 0-25 and their
0-100 sum. The host displays Score = rounded rise.impact / 2.5 (0-10), plus estimated Effort in
human decision seconds. Set impact to desired Score × 2.5 and estimate the other components honestly.
Do not paint another score inside the card. High impact needs proven benefit, not speculative reach.
Downscore single-source evidence; one strong reproduction does not prove a widespread problem.
effortSeconds is the actual predicted review burden; effortReason explains it. Count exact copy,
diff scope, video duration, risks and required external reading. The host displays the agent’s estimate
unchanged; missing estimates show no value. The active-time counter is separate.
Default UI sorting is displayed score, then stored total, then ID; the user may choose effort or
newest. Backend result order is not necessarily the user's current order.
GET /api/topics returns topic names (label) and descriptions (hint). Reuse topics; for a
new lane use POST /api/topics {label,hint}. Set the card category to the full topic ID or
name, for example Support. The agent chooses it; the app does not match keywords. New
installs have no preset topics. Existing topics stay editable. Unmatched cards stay in All.
Do not rename/delete the user's topics without approval.
Authoritative source paths in the configured checkout: app/api/{agent-jobs,ideas,state,topics},
lib/job-lifecycle.ts, lib/blocked-card.ts, lib/rise.ts, lib/card-focus.ts and
scripts/{push-card,sync-me}.mjs. The agent authors each card’s HTML and actions.
npm run build
npm run lintThe local .openai/hosting.json declares only local
bindings; it contains no shared hosting project. The included build helper is required by Vite.
Each checkout has its own database, profile and assets. Keep backups private. Never commit
.wrangler, me.md, personal approval settings, environment files, browser state or customer media.
Sharing this source does not share your cards or credentials.
The private .agents/skills/design/ bundle and local migration state are ignored too; do not force-add
them. Shared defaults belong in the tracked Agency instructions, without personal ticket examples.
See COMMIT_SCOPE.md for the source included and what remains local.