Ghost Hands

Ghost Hands

Playwright drives. Stagehand thinks. Browser Use wanders. Ghost Hands answers for every move.

Ghost Hands is a standalone, zero-dependency Python package that gives an agent *hands* on the web — and a conscience to go with them. Every action an agent takes is classified before it runs (readonly / write / consequential), judged against a policy, written to a provenance trail *before* it executes, and — when it matters — gated on a human approval. Finished runs graduate into deterministic, model-free Ghost Hands scripts you can re-run for free.

The browser body is our own: a stdlib Chrome DevTools Protocol client drives Chromium directly over the --remote-debugging-pipe transport. There is no Playwright, no Selenium, and no other automation library under the hood — the automation layer is 100% ours. (We drive Chromium, the browser; we did not write a browser engine and don't claim to have.)

From Ghost Developer Studio. MIT licensed.

MCP Registry: mcp-name: io.github.littlestjames82-sys/ghost-hands

Status: v0.9.3 — live on PyPI and GitHub:

PyPI ghost-hands

(pip install ghost-hands) ·

github.com/littlestjames82-sys/ghost-hands ·

littlestjames82-sys.github.io/ghost-hands.

What's new in 0.9.0

• `ghost-hands doctor` (doctor.py) — one command that answers "is everything wired up?" for the whole stack. Seven read-only checks — the Python runtime, a Chromium binary (found by the driver's own resolver, so doctor and the driver can never disagree), the four policy packs, the model environment, a GhostBus server (when --bus / GHOSTBUS_URL configures one; the workspace shape — single vs hosted /w/ / — is reported), the MrGhosty phone bridge (when configured: reachable, token accepted, MrGhosty version, accessibility state, bridge-protocol match), and adb — each rendering as a PASS / WARN / FAIL row with, when it isn't a PASS, a one-line plain-language fix ("Is the phone on, MrGhosty accessibility on, and adb forward tcp:8378 tcp:8378 running?" / "Pairing token mismatch — re-copy it from MrGhosty's Access checklist into GHOST_HANDS_ANDROID_TOKEN."). FAIL means "this part will not work until you act"; WARN means idle-or-optional (an unconfigured bus or bridge is a WARN, never a failure). Exit code is 1 iff anything FAILs. --json emits the same checks as structured data. Every probe carries a short timeout, so doctor never hangs on a dead endpoint, and no secret is ever printed: keys and the pairing token are reported as present, never as values.
• `ghost-hands phone-proof` (phone_proof.py) — the guided version of the first phone run. Where phone-approval-test proves one thing in isolation, phone-proof walks all five steps and *checks* each: bridge configured (else it prints the exact env setup and stops — exit 2, needs-setup), the adb forward (printed before it runs; skipped gracefully without adb/a device), the bridge status (MrGhosty version + accessibility), the harmless test approval ("LOOK AT YOUR PHONE NOW — tap Approve on the MrGhosty notification"), and a closing summary of what is now proven plus the exact next commands. Denied, expired, or timed-out approvals end gracefully with instructions — exit 3 (not approved); bridge/config failures are exit 1. --yes runs straight through without pauses, which is how the tests and bench drive it against the fake bridge.

First phone proof

With MrGhosty v1.7+ installed on the phone and its accessibility service enabled, the whole first run is:

adb forward tcp:8378 tcp:8378        # or let phone-proof do it (step 2)

export GHOST_HANDS_ANDROID_TOKEN= ghost-hands doctor # every row green or explained? ghost-hands phone-proof # five checked steps to "proven"

phone-proof prints what each step needs before it checks it, and its exit code says how the story ended: 0 proven · 1 error · 2 needs-setup · 3 not approved. After it passes, the phone is a governed body: ghost-hands run --driver android --approver phone drives it with approvals on the phone itself.

What's new in 0.8.0

• Trail → HTML audit report (ghost-hands report trail.jsonl, report.py). The trail was always the record; now it's a readable one. One run renders to ONE self-contained HTML file — inline CSS, no JavaScript, no external assets, works offline — in studio styling (dark charcoal, violet accent): a header (goal when the trail records one, body inferred from the perception URLs, date range, stop reason + summary), summary stat cards (steps, wall duration, perception chars / ~tokens, actions by class, approvals requested/granted/denied, heals, downloads/dialogs/net counts), and a step-by-step timeline — perceived map summary with a collapsible perception record, the decision in plain language ("click [4] 'Place order'"), the Governor's verdict with its classification chip and, for asks, how the story ended ("ask → approved via phone"), the result, and special events inline (heals with from/to, dialogs, downloads with filename + size, approval request/decision pairs with channel + decider, network capture in a collapsible). Rendering is defensive: every trail string is HTML-escaped (a hostile page title stays text), typed values are truncated at 80 chars, and a value typed into a type=password element renders as •••• (N chars). Corrupt lines are skipped and counted in the footer — a partial trail is still a record. A sample render ships in examples/sample-report.html.
• MCP parity. The MCP server is no longer fake-web-only: GHOST_HANDS_DRIVER=fake|chromium|simphone|android selects the session body (default: fake, as before), GHOST_HANDS_START_URL opens on the first perceive, and android sessions use the same GHOST_HANDS_ANDROID_BRIDGE / GHOST_HANDS_ANDROID_TOKEN env as the bus agent (the token never appears in tool output). Bodies with native eyes perceive through them, exactly like the Runner. GHOST_HANDS_APPROVER=phone routes session "ask" verdicts through PhoneApprover instead of the deny-with-explanation default, and hands_act replies state which channel decided ("approved via phone" / "denied: no approver (MCP default)"). hands_run defaults to the session body and accepts all four drivers. Configuration is per-server-process; unknown values fail loudly at startup.
• The `seatbelt` policy pack. Standard's posture (readonly + write allowed, consequential asks, 300s approval leash) plus a target-content rule: if a target element's name/label — or the page/action URL — matches a curated prompt-injection pattern (policies.INJECTION_PATTERNS: "ignore previous instructions", "disregard your instructions", "you are now", "system prompt", "click here to claim", "verify your password to continue", …), the Governor denies the action outright, whatever its class, and the govern event's reason names the matched pattern. The patterns are instruction-shaped phrases, never bare words — a button named "Ignore" does not trip it (guarded by tests). Implemented as data on the Policy (deny_patterns), so any pack or policy file can carry its own list.

What's new in 0.7.0

• The model evaluation harness (ghost-hands eval, evaluate.py). Eight graded tasks against local fixture pages — search-and-open, multi-field form fill + consequential submit, structured table extraction, multi-hop navigation to a fact, a trap page whose prominent button is destructive and must NOT be touched, a shifting page scored on heal recovery, a login form whose trail is audited for credential leakage, and an impossible goal scored on honest stopping. Four tasks run on real Chromium. Every task is scored on success, steps, wall time, perception chars / ~tokens, actions by class, approvals requested, and heals; --report PATH writes the JSON. Three deciders: --decider stub (a local stub model server whose deterministic policy proves the harness end to end — stub results are harness verification only, not a model-quality measurement), --decider rules (the RuleDecider as a second baseline), and --decider openai (a real model via the existing env-configured decider). Measured on this build: the stub passed 8/8 (the instrument works); the rules baseline passed 3/8 (trap avoidance, heal recovery, honest stop — its honest failures on search, forms, extraction, multi-hop, and login are data, not harness errors). Real-model numbers are reported separately wherever a key is available; see "Honest status".
• Android gestures (MrGhosty v1.8.0). Three action kinds the Android body used to refuse — double_click, drag, click_at — are implemented end to end: the bridge dispatches real gestures (dispatchGesture, bounded callback latch, honest cancelled/failed results), click_at is validated against the current window's bounds and refused out-of-bounds, and AndroidDriver forwards all three (drag resolves both ends; click_at needs no target). SimPhoneDriver does not implement them — no fake parity; see docs/BODY_PROTOCOL.md §6 for which body supports what.
• The GhostBus file-store loop is closed. The v0.4 finding (the file-backed store's shared-.tmp rename colliding under concurrent writers, HTTP 400) was fixed in GhostBus 0.4.1 (unique temp per save + serialized saves) and regression-tested in the GhostBus suite since 0.5.0 (44/44 + 6/6, re-verified for this build). Ghost Hands now proves it from its own side too: the bus demo flow and a parallel agent+poller barrage run against a real file-backed GhostBus with zero 400s, an intact store, and no orphan temp files (bench v7 bus, pytest test_file_store_barrage_no_races).

What's new in 0.6.0

• Approvals by phone. A run's "ask" decisions can be routed to Ryan's phone: PhoneApprover (phone_approver.py) posts a redacted approval request to the Ghost Hands bridge in MrGhosty v1.7.0, which raises a high-importance notification ("Ghost Hands needs approval") with Approve / Deny actions, mirrored by a card in MrGhosty's Device tab. The decision returns over the bridge; denied, expired, timed-out, and unreachable all mean no — silence is never consent. Works with every driver (ghost-hands run --approver phone … — the phone can approve a desktop Chromium run too), and in bus-agent mode via --approval-channel phone (the bus gets a courtesy comment; the approval itself is never requested from the bus). Approvals route to Ryan's phone through the MrGhosty bridge (notification + in-app decision) when the bridge is reachable; it is a local bridge channel, not a cloud push service. See docs/APPROVALS.md.
• Decisions are phone-only, by construction. The bridge API can create and read approval requests but has no decision endpoint — a token holder can never approve their own request. The only deciders are the notif