Browser Plan

Browser Plan is Hasna's native agentic browser control plane. It lives in the open-chrome repo and remains an internal open-source Chromium fork project for the hasna organization.

The repository now contains a lightweight fork control plane plus an initial native agentic browser/profile app. Chromium source is tracked from upstream main only and is not vendored into this branch.

Current Strategy

• Track upstream Chromium main only.
• Prefer the canonical upstream remote: https://chromium.googlesource.com/chromium/src.git.
• Use the GitHub mirror only as a fallback: https://github.com/chromium/chromium.git.
• Avoid all-branches, all-tags, full-history clones by default.
• Keep local Chromium source checkouts/build checkouts separate from this docs branch unless Andrei approves importing a Chromium source branch.

The local checkout for this project has an upstream remote configured with a main-only fetch refspec and blob:none partial clone settings:

git remote add upstream https://chromium.googlesource.com/chromium/src.git
git config remote.upstream.fetch '+refs/heads/main:refs/remotes/upstream/main'
git config remote.upstream.tagOpt --no-tags
git config remote.upstream.promisor true
git config remote.upstream.partialclonefilter blob:none
git remote set-url --push upstream DISABLED

To update the upstream pointer without downloading Chromium's full branch/tag universe:

git fetch --filter=blob:none --no-tags upstream main
git log --oneline -1 upstream/main

For a disposable minimal source checkout outside this repo:

git clone \
  --origin upstream \
  --single-branch \
  --branch main \
  --filter=blob:none \
  --no-tags \
  https://chromium.googlesource.com/chromium/src.git \
  chromium-src

Add --depth=1 when the checkout is disposable and you do not need merge or rebase history. Omit --depth=1 for long-lived fork work where we expect to rebase local patches over upstream main.

For a buildable Chromium checkout, follow Chromium's depot_tools flow and use fetch --nohooks --no-history chromium. That path is heavier than the control plane repo, but it is the official way to obtain Chromium's dependency graph.

See docs/FORK_STRATEGY.md for the full investigation, tradeoffs, and sync workflow.

App And CLI

Install dependencies:

bun install

Run checks:

bun run check

Start the local Browser Plan API/control server:

bun run start

Default diagnostic URL:

http://127.0.0.1:4973

Create and inspect profiles:

browserplan profile create "Research Agent" \
  --owner-type agent \
  --owner-id research-agent \
  --owner-name "Research Agent" \
  --assignee-type agent \
  --assignee-id research-agent \
  --assignee-name "Research Agent" \
  --machine apple03 \
  --homepage https://example.com \
  --json

browserplan profile list
browserplan profile show <profile-id>

CLI output is compact by default so agent terminals do not get flooded with nested profile records, audit logs, scripts, or chat payloads. List and search commands show a capped table plus a total and next-page hint. Use --limit and --cursor to page through human output, show or detail commands for one record, --verbose for full human-readable JSON-style details, or --json for the stable full machine-readable payload.

Examples:

browserplan profile list --limit 10
browserplan profile list --cursor 10 --limit 10
browserplan profile show <profile-id> --verbose
browserplan profile list --json
browserplan chrome ask <profile-id> "Summarize the browser task"
browserplan chrome ask <profile-id> "Summarize the browser task" --json

Manage app settings:

browserplan settings get --json
browserplan settings set \
  --default-machine apple03 \
  --provider codewith \
  --remote-control true \
  --secrets-namespace hasna \
  --json

Remote control defaults to disabled. Enable it explicitly after reviewing the target machine route and workspace.

Plan a remote Apple03 start with OpenMachines route and workspace evidence:

browserplan remote start --machine apple03 --json

Execute it when routing is healthy:

browserplan remote start --machine apple03 --execute --json

Manage profiles through a running remote Browser Plan API:

browserplan profile list \
  --api http://127.0.0.1:4973 \
  --token "$OPEN_CHROME_TOKEN" \
  --json

browserplan profile launch <profile-id> \
  --api http://127.0.0.1:4973 \
  --token "$OPEN_CHROME_TOKEN" \
  --json

Ask Codewith in the profile's browser conversation:

browserplan chrome ask <profile-id> \
  "Summarize the current browser task and next safe action." \
  --provider codewith \
  --json

Local launch requires Chromium, Chrome, ChatGPT Atlas, or optional Playwright Chromium. Set OPEN_CHROME_CHROMIUM=/path/to/chromium to force a binary. When Browser Plan launches a profile, it loads the bundled Browser Plan Chrome extension into that real browser profile. The extension adds the Browser Plan toolbar entry, right-click menu items, and the native Chromium side panel chat. The web page at 127.0.0.1:4973 is a control and diagnostic surface, not the primary browser UI.

Runtime data defaults to:

~/.hasna/open-chrome

Use OPEN_CHROME_HOME=/path/to/state for tests or isolated local runs.

Native Profile Model

Browser Plan owns native Chromium profiles:

• user-data-dir isolation;
• owner and assignee typed as human or agent;
• machine assignment;
• policy gates for sensitive actions;
• profile locks;
• audit log;
• secret refs without raw secret values.

Browser Plan's Chrome side panel runs normal Codewith chat turns through @hasna/codewith-sdk, persists the Codewith thread ID per conversation, and shows a compact action transcript for each assistant turn inside the launched browser. Browser-mutating agent actions remain approval-gated by default; a profile policy must explicitly allow agent execution before background actions start.

See docs/ARCHITECTURE.md.

Browser Plan CLI Direction

The browserplan CLI makes Chromium programmatic and agentic, with direct CLI management of isolated browser profiles as the headline feature.

The CLI plan remains in docs/BROWSERPLAN_CLI_PLAN.md, and the current implementation begins that plan with profile lifecycle, settings, chrome ask, machine, secrets, remote API targeting, and remote-start scaffolding.

License

Repository additions are licensed under the BSD 3-Clause License. Chromium source and third-party code remain under their upstream licenses when fetched or imported.