aihand

The hand of AI. Your agent can read files but can't see the running page, edits text but can't safely move a symbol, guesses at the UI instead of looking at it.

aihand gives the model the three things a human does with their hands: read the code, refactor it, drive the running app — all over plain HTTP, from one CLI. Add one Vite plugin. Done.

aihand read      panel | source <file:line> | tree     understand code (read-only)
aihand refactor  move-file | rename | move-symbol       change source (AST, never regex)
aihand runtime   screen | click | fill | wait | check   inspect & drive your running app
aihand probe     open <url> | screen | click | eval     drive ANY website (its own chromium)

Every command and flag: aihand <module> --help. The full codemap gets injected into your CLAUDE.md / AGENTS.md on install — the agent reads it there, not here.

Why it's fast

The bottleneck in agentic coding isn't the model or the engine — it's round-trips. Guess, check, correct: every cycle is a wasted turn (~11s each). aihand collapses them:

• See the app, don't guess it. screen returns a semantic, spatial sketch of the live UI — view, modals, focus, every clickable knob — so the agent reads the page instead of asking you to describe it.
• One round-trip per action. Click-and-observe is fused: an action returns the delta it caused (and for async flows, the trajectory until it settles). No re-screening to find out what happened.
• Refactors that can't silently break. rename / move-symbol go through ts-morph, rewrite every importer, and refuse unsafe edits with a reason — never a broken tree.
• POST /chain runs a known N-step sequence (login, search) in one round-trip.

vs. Playwright (in an agent loop)

Measured full-chain — from "want to do X" to "confirmed done, and know the result", not single-dispatch latency. Same real app (a React + MobX chat), same tasks, same harness. aihand over HTTP (curl /__aihand/*); Playwright over MCP tools (browser_*, CDP):

| task | aihand | Playwright MCP | speedup | |---|:---:|:---:|:---:| | switch chat → group (a click) | 177ms / 1 rt | 39.7s / 3 rt | ~224× | | open settings panel | 182ms / 1 rt | 25.1s / 2 rt | ~138× | | open knowledge-base panel | 181ms / 1 rt | 19.5s / 2 rt | ~108× | | send a message (real LLM async) | 3.4s / 1 rt | 57.9s / 5 rt | ~17× |

Playwright's raw click engine (~52ms) is actually faster than aihand's /click — the weight isn't the browser. It's the MCP tool boundary: the full chain gets sliced into 3–5 round-trips, each forcing a full-page a11y snapshot the agent must eyeball-diff to confirm what happened. aihand fuses act-and-observe into one round-trip — the receipt carries the state delta (mode: chat → im, opened modal, the async stream trajectory), so a simple click lands in ~180ms and one turn instead of 3 turns × ~13s of agent time. The win is round-trips, not milliseconds.

Install

npm i -D aihand

// vite.config.ts
import { aihand } from 'aihand/vite'

export default defineConfig({ plugins: [aihand()] })

One registration serves the runtime probe (/__aihand/* in dev) and injects the codemap into your AI context files (CLAUDE.md, AGENTS.md). First run auto-detects those files, adds markers, and writes aihand.config.ts:

// aihand.config.ts
import { defineConfig } from 'aihand'

export default defineConfig({
    // aihand = three capability modules. Each: true (on, defaults) · false (off) · { ...overrides }.
    // Most repos only need the three switches below — tuning knobs have smart defaults.

    // Codemap injection into CLAUDE.md/AGENTS.md
    read: true,
    // AST refactor commands (move-file / rename / move-symbol)
    refactor: true,
    // Inspect & drive the running app (runtime browser probe — needs the vite plugin);
    // set false on repos without a dev server.
    // Non-MobX store factory? runtime: { storeMarker: 'getState' } — the reactive
    // fingerprint field on the store's return type (zustand 'getState', default '_loading').
    runtime: true,

    // Need to tune read? Open it up (all optional, shown with defaults):
    // read: {
    //   include: ['src/**'],          // what to scan (root config files always included)
    //   ignore: [],                    // extra skips (.gitignore already applied)
    //   maxTokens: 5_000,              // budget — auto-downgrades less important files
    //   injectCodemap: true,           // false → keep Overview + Control Panel resident, pull tree/signatures/full on demand via `aihand read`
    // },
})

License

MIT