Agency

For Humans

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.

For Agents

Read the Agency skill, then follow the setup below. The package starts empty. It includes no personal profile, tickets, customer media or credentials.

Run locally

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 3100

Open 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.

Install the one skill

node scripts/install-skill.mjs --codex
# Or:
node scripts/install-skill.mjs --claude

The 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.

Start Agency

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.

Profile, layout and approval settings

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.

Customize the layout

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.

Synchronize My dream and me.md

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.

Connect useful sources

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.

Optional Linear workflow

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.

Browser setup

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 and shortcuts

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.

Agent API

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.

Read, coordinate and claim

• GET /api/agent-jobs returns available latest jobs, not an exclusive claim. Read cardContext, userFeedback, buttonLabel, instruction and ordered history. History results are truncated to 600 characters; use full local history read-only when a missing detail matters.
• GET /api/state exposes 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-jobs with {"id":123,"status":"running"} starts work; repeated running updates renew its six-hour lease. GET may return expired running work as reclaimed: 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.

Finish every job explicitly

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.

Push complete cards

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.json

The 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.

HTML and controls

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" plus data-radar-prompt: queues the exact shown action.
• data-radar-action="open" plus data-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.

Score, effort and topics

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.

Checks and storage

npm run build
npm run lint

The 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.