DevScope

Local Chrome side-panel for Claude Code, Cursor, Codex, and Antigravity sessions.

Three pieces:

1. Chat — sessions in the side panel, streamed from your local CLI
2. Browser — bind a tab; Claude can read and click through MCP
3. Connection — a loopback-only Python bridge on 127.0.0.1:7878

The bridge launches your already-installed CLI/IDE adapters (claude, cursor-agent, codex, or Antigravity headless mode). Nothing is sent to a DevScope cloud — there isn’t one. Auth is a local token (~/.dev-bridge/token, chmod 0600). The process refuses to bind anywhere except loopback.

---

Where this is going

The side panel is the surface. The goal underneath it is a standing colleague — an assistant and developer that works on its own initiative, on your machine, with your accounts, and comes back with work already done instead of waiting to be told what to do.

A chat tool answers when spoken to. Turning that into a colleague takes three things, and all three are in this repo today:

Property	What it means	Where it lives
A heartbeat	Something wakes the agent on a timer, so it can act with nobody typing	orchestrator.py — a tick loop driving a Manager-of-Managers → Domain Manager → Worker hierarchy
Durable state	Work outlives a single conversation, a restart, or a crashed process	task_store.py — a task board with parent/child trees, logs, and stuck-worker reconciliation
Explicit limits	Autonomy you can leave running, because the dangerous actions stop and ask	agent_policies.py — workers must call task_request_approval before sending, buying, deleting, or spending

Reading, researching, navigating, and filling forms without submitting are autonomous. Sending, publishing, deleting, and anything touching money pause for you. That line is the whole design: the agent should be able to run all day unattended without any single step being one you'd want to undo.

Honest status

Working today: the tick loop, the task hierarchy, the approval gate, per-site playbooks that remember selectors and workflows across runs (schedule_playbook.py), and an autonomous-employee layer that can report to Notion, WhatsApp, or email (employee_config.py — off by default).

Not there yet, and the difference between "runs unattended" and "genuinely doesn't wait for instructions":

• Self-originating work. Tasks still mostly arrive from you. The agent can already read mail, messages, and calendar through MCP; what's missing is the step that turns an observation into a proposed task on its own.
• Memory of you. Playbooks remember websites. Nothing yet remembers your preferences, your past decisions, or how you like things done.
• Judgement about when to interrupt. A colleague who asks about everything is as tiring as one who asks about nothing.

What stays true regardless

Local-first, permanently. The bridge binds loopback only and refuses anything else. The agent is the claude CLI you already installed and logged into — this project ships no model, no account, and no server of its own. Autonomy here means your machine doing more on your behalf, not your work moving somewhere you can't see it.

---

What you need

Thing	Why
macOS or Linux, Python 3.11+	Runs the bridge
Claude CLI logged in (claude login)	Claude sessions
Chrome	Hosts the side panel
Node.js 18+	Builds the extension once
Cursor CLI (optional)	Cursor sessions
Codex CLI (optional)	Codex sessions and app-server resume/steering
Antigravity IDE/CLI (optional)	Antigravity headless sessions

Verify the adapters you plan to use are available:

which claude && claude --version
which cursor-agent && cursor-agent --version   # optional
which codex && codex --version                 # optional

---

1. Install the bridge

From this folder:

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

That puts devscope-bridge on PATH inside the venv.

Start it once (foreground)

devscope-bridge
# or: python -m devscope_bridge.main

It prints:

Dev Bridge started. Token: <hex>

and writes the same value to ~/.dev-bridge/token (chmod 0600). The token is reused across restarts — you only paste it into the extension once.

Keep this terminal open, or install the macOS service in step 4.

Check:

curl http://127.0.0.1:7878/health
# {"ok":true,"version":"0.1","uptime_s":…}

Environment (optional)

Variable	Default	Purpose
BRIDGE_HOST	127.0.0.1	Bind address. Loopback only — other hosts are rejected.
BRIDGE_PORT	7878	TCP port
BRIDGE_EXTENSION_ID	placeholder	Chrome origin added to CORS, e.g. chrome-extension://abcdef…
CURSOR_BIN	macOS Cursor.app path	Cursor CLI binary

Copy .env.example → devscope_bridge/.env.local if you prefer a file (gitignored).

Do not run the bridge with uvicorn --workers 2+. PTY terminals and WebSockets live in one process. workers=1 is required.

---

2. Build and load the Chrome extension

cd extension
npm install
npm run build

In Chrome:

1. chrome://extensions
2. Enable Developer mode (top right)
3. Load unpacked → select extension/dist/ (the built folder, not src/)
4. Copy the ID shown on the DevScope card (32 characters)

Pin the icon if you want. Click it to open the side panel.

---

3. Connect extension ↔ bridge

Restart the bridge so CORS trusts this install:

export BRIDGE_EXTENSION_ID="chrome-extension://PASTE_THE_ID_HERE"
devscope-bridge

In the side panel: gear (Settings) → paste:

cat ~/.dev-bridge/token

into Bridge token → Save / Test connection.

The connection pip in the header turns green when the WebSocket is live.

First chat: New chat → pick a project folder (your code) → send a message. Claude runs in that folder. For browser tools, bind the current tab with the globe control in the composer.

If it stays Offline

Symptom	Fix
/health times out or connection refused	Bridge not running — start it, or see ~/.dev-bridge/bridge.log
403	Token mismatch — paste cat ~/.dev-bridge/token again
Pip grey, health 200	CORS — restart bridge with BRIDGE_EXTENSION_ID=chrome-extension://<id>
claude not found	which claude; LaunchAgent PATH is small — use scripts/install-macos-service.sh
503 Browser client not connected	Open the side panel and bind a tab

---

4. Run the bridge in the background (macOS)

After the venv is installed:

chmod +x scripts/install-macos-service.sh
./scripts/install-macos-service.sh

This writes ~/Library/LaunchAgents/com.devscope.bridge.plist, starts at login, keeps the process alive, and raises the open-files limit.

# logs
tail -f ~/.dev-bridge/bridge.log

# stop
launchctl bootout "gui/$(id -u)/com.devscope.bridge"

# start again
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.devscope.bridge.plist"

If you rebuild the Python package, kickstart:

launchctl kickstart -k "gui/$(id -u)/com.devscope.bridge"

On Linux, run devscope-bridge under systemd/user or a tmux session. There is no Linux unit in this snapshot.

---

5. Browser tools (MCP)

Claude only sees browser tools if an MCP config is loaded.

Option A — this repo as the chat’s project folder
.mcp.json already lists browser-control. In DevScope → New chat → Project = this directory.

Option B — your own repo
Copy .mcp.json into that project, then set the chat’s project path to that repo.

Option C — register globally for the Claude CLI

source .venv/bin/activate
python -m devscope_bridge.setup_mcp
claude mcp list

Use the same Python that has devscope_bridge installed. If .mcp.json says python3 -m devscope_bridge.…, that python3 must resolve to the venv (activate it, or edit .mcp.json to .venv/bin/python).

Bind a tab with the globe control in the composer. Without a bound tab, browser tools return 503.

---

Autonomy layer

Beyond chat + browser + connection, the repo ships the pieces described in Where this is going. All of it is off by default — a fresh install behaves exactly like a side panel with a chat in it.

Piece	What it does	Settings
Orchestrator	Tick loop, 3-tier agent hierarchy, worker dispatch, concurrency cap, quota throttling	~/.dev-bridge/orchestrator_config.json
Task board	Persistent tasks, subtasks, logs, approval requests	~/.dev-bridge/*.db
Schedules	Recurring runs with a learned per-site playbook	~/.dev-bridge/*.db
Autonomous employee	Board sync (Notion) and reporting over panel / WhatsApp / email	~/.dev-bridge/employee_config.json
Cockpits	WhatsApp, Gmail, Calendar, Meta Ads — read/act through MCP	OAuth tokens in ~/.dev-bridge/

Turn the orchestrator on and it starts waking agents on its own. Read agent_policies.py first — it is the document that defines what an unattended worker may and may not do without asking you. WORKER_SAFETY_POLICY is the default; the _E2E variant relaxes sending and posting and is a deliberate choice, not a default.

OAuth tokens (if you use the cockpits) land in ~/.dev-bridge/ and must never be committed.

---

Layout

devscope_bridge/     Python package (FastAPI bridge + MCP stdio servers)
  main.py            App, lifespan, loopback bind
  session_http.py    REST: sessions, transcript, browser actions
  ws_session.py      Chat WebSocket
  pty_ws.py          Interactive terminal
  session_manager*.py Claude/Cursor/Codex/Antigravity process adapters
  orchestrator*.py   Tick loop + pure decision logic for the agent hierarchy
  agent_policies.py  System prompts and the worker approval policy
  task_store.py      Persistent task board
extension/           Chrome MV3 side panel (Vite)
scripts/             macOS LaunchAgent installer
.mcp.json            Claude Code MCP (this repo)

Data on disk (all local):

• ~/.dev-bridge/token
• ~/.dev-bridge/sessions.json
• ~/.dev-bridge/bridge.log
• ~/.dev-bridge/chat-transcripts/
• ~/.dev-bridge/*.db

---

Tests

source .venv/bin/activate
pip install pytest
pytest

Empirical tests that spawn a real claude process stay skipped unless RUN_EMPIRICAL=1.

---

Step-by-step setup guide: docs/SETUP.md (English) · docs/SETUP.he.md (עברית)

Contributing & security

PRs welcome — see CONTRIBUTING.md. To report a vulnerability, see SECURITY.md. Setup help: SUPPORT.md.

License

MIT — see LICENSE.

Privacy

See extension/store/privacy-policy.md.