GHOST HANDS

Ghost Hands

Last updated November 12, 2026

A standalone, zero-dependency Python package that gives an agent hands on the web, and a conscience to go with them.

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

What it does

Every action an agent takes is classified before it runs (readonly, write, or 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 scripts you can re-run for free.

• Eyes: numbered element maps from a walk of the page's composed DOM tree, including shadow roots and iframes, or from the CDP accessibility tree. The map needs no screenshots and no vision model.
• Hands: typed JSON actions: navigate, click, type, press with chords, fill forms, set files, download, extract text, lists, tables, and network data, take screenshots and PDFs, set viewport presets, wait, manage tabs, and save or load sessions.
• Governor: classification and policy run before execution, behind a domain allowlist. Form submits and pay, send, delete, publish, and transfer shapes are consequential.
• Trail: a JSONL provenance trail, recorded before the action executes, with per-run accounting. Since 1.0.0 every event is hash-chained to the one before it, so editing, deleting, or reordering any part of a record breaks the chain, and the ghost-hands verify-trail command proves a trail is intact.
• Bodies: FakeDriver, ChromiumDriver, SimPhoneDriver, and an AndroidDriver through the MrGhosty bridge.
• Brains: ScriptedDecider, RuleDecider, and an OpenAI-compatible decider.
• Runner: a step budget, stuck detection, and self-healing targets.
• Replay: finished runs export as deterministic, model-free scripts.
• Plan cache: since 1.0.0, a finished run also stores its proven steps, and an identical goal replays them through the full Governor with no model calls at all, re-finding each element by identity and falling back to the live decider when the page has changed.
• Secrets: since 1.0.0, an agent types a placeholder such as {{secret:NAME}} and never sees the real value; it is resolved from the environment only at the moment the action executes, and anything a page echoes back is scrubbed before it reaches the trail.
• Verify: since 1.0.0, a readonly verify action lets a run prove its own result, checking that expected text or an element is present, or that the page is at the expected address, before it may claim the work is done.
• Policy packs: readonly, standard, strict, and seatbelt.
• Audit report: an HTML report generated from a trail.
• Bus mode: a GhostBus bus-agent mode for agent teams.
• MCP server: a stdio server with four tools: hands_perceive, hands_act, hands_run, and hands_trail.

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. In the README's words: "We drive Chromium, the browser; we did not write a browser engine and don't claim to have."

Approvals are real gates. Silence is never consent: an ask with no approver is a denial. Phone approvals are decided only on the phone, and the bridge API has no decision endpoint.

Quickstart

The README's quickstart, verbatim:

from ghost_hands import ChromiumDriver, Runner, ScriptedDecider
driver = ChromiumDriver()  # finds Chromium/Chrome; $GHOST_HANDS_CHROME overrides
runner = Runner(driver, ScriptedDecider([
    {"kind": "navigate", "url": "https://example.com"},
    {"kind": "extract"},
    {"kind": "done", "summary": "looked at the page"},
]))
report = runner.run("look at example.com")
print(report.stop_reason, report.summary)

Get it

Version 1.11.0. MIT license. Python 3.10 or later, zero dependencies.

pip install ghost-hands

New in 1.0.0: the trail is hash-chained and tamper-evident, with a verify-trail command to prove a record is intact; secret placeholders keep real credentials out of the model's sight; a verify action makes a run prove its result before claiming done; and finished runs are cached as governed plans that replay with no model calls.

New in 1.1.0: focused perception, which keeps the goal-relevant elements when a page map runs long, and the decider now perceives through it; the run report header and the MCP trail tool both carry the trail’s hash-chain verdict; and the governed plan cache now works over MCP as well as the command line.

MCP server (stdio):

ghost-hands mcp

Claude Code wiring, from the README:

claude mcp add ghost-hands -e GHOST_HANDS_DRIVER=chromium -e GHOST_HANDS_APPROVER=phone -e GHOST_HANDS_POLICY=standard -- ghost-hands mcp

• GitHub repository
• GitHub releases
• PyPI: ghost-hands
• Project site

In development

Between releases, Ghost Hands is built in waves on the public main branch, and the development notes track each wave as it lands: what it adds, and the tests and bench cases behind it. Read the Ghost Hands development notes.

Proof and listings

• Official MCP Registry: listed and active under the name io.github.littlestjames82-sys/ghost-hands.
• Glama: TDQS grade B, 3.4 out of 5 (as of November 2026).
• M8ven: grade B, 89 out of 100, Verified Publisher (as of November 2026).
• MCP Rush: a Grade A listing (as of November 2026), on the studio's publisher page.
• Real-model eval (November 12, 2026): Meta's Muse Spark 1.3 drove the graded fixture suite through the production prompt and action parser: 3 of 4 tasks passed (multi-hop research, trap avoidance, and an honest stop on an impossible goal), with the fourth failure published, not hidden. 64 model calls; 37,776 prompt and 50,506 completion tokens, API-reported; about $0.26 at list prices. The full scorecard is in the repository.

How Ghost Hands stacks up against the browser tools it is most often compared with, including where each of them wins: the honest comparison.

Honest limits

A real model has now driven the graded local fixture suite (3 of 4 tasks, November 12, 2026, above). Driving live public sites end to end is still unproven, and the suite's Chromium-body tasks have not yet had a live-model run. The README says so.

On-device Android proof is pending the maintainer's install.

Questions? See the Hub help center.