{
  "markdown": "# @hua-labs/tap\n\n[![npm version](https://img.shields.io/npm/v/@hua-labs/tap.svg)](https://www.npmjs.com/package/@hua-labs/tap)\n[![npm downloads](https://img.shields.io/npm/dm/@hua-labs/tap.svg)](https://www.npmjs.com/package/@hua-labs/tap)\n[![license](https://img.shields.io/npm/l/@hua-labs/tap.svg)](https://github.com/HUA-Labs/tap/blob/main/LICENSE)\n\n`@hua-labs/tap` is a lightweight CLI that lets multiple AI agent runtimes, such\nas Claude and Codex, exchange messages through a shared file-backed\ncommunication directory.\n\nIt focuses on safe setup, durable delivery evidence, and runtime-specific\ndiagnostics without requiring a central daemon for every runtime.\n\n## Preview Status\n\n`0.6.x` is an advanced operator preview.\n\n- Public defaults use neutral concrete agents such as `agent-a` and `agent-b`.\n- `setup` is dry-run-first and only applies reviewed tap-managed changes.\n- Profile packs are data-only validation inputs; tap does not run commands from\n  a profile pack in `0.6.x`.\n- Codex App / Desktop live delivery is experimental and strict-gated by runtime\n  health and route freshness.\n- Gemini CLI support is legacy/deprecated in this release line. If your\n  workflow has moved to Antigravity CLI, treat it as a custom profile-pack\n  surface until tap ships a dedicated adapter.\n\nFor detailed AI-operator troubleshooting, concepts, and advanced runtime notes,\nread [AI_GUIDE.md](./AI_GUIDE.md). AI operators should read it before claiming\nlive delivery or runtime readiness.\n\n## Requirements\n\n- Node.js `>=22.6.0`\n- A git repository for setup-managed MCP config\n\n## Quick Start\n\nRun inside an existing git repository. For a new test directory only:\n\n```bash\ngit init\n```\n\nThen inspect and apply setup:\n\n```bash\n# 1. Inspect setup changes first\nnpx @hua-labs/tap setup --profile codex-cli --dry-run --json\n\n# 2. Apply only reviewed setup-safe changes\nnpx @hua-labs/tap setup --profile codex-cli --apply --json\n\n# 3. Check setup readiness\nnpx @hua-labs/tap doctor --setup --profile codex-cli --json\nnpx @hua-labs/tap status --json\n```\n\nTo add and verify a concrete runtime lane later:\n\n```bash\nnpx @hua-labs/tap add codex --name agent-a\nnpx @hua-labs/tap ready --surface codex-cli --agent agent-a --apply --json\nnpx @hua-labs/tap comms-doctor --all-known --json\n```\n\n## What Setup Changes\n\n`tap setup` is dry-run by default. With `--apply`, the reviewed public setup\npath creates tap-owned directories, an initial tap state file, and guarded\ntap-managed repo `.mcp.json` entries.\n\nIt does **not** start receiver, projection, uplink, bridge, app-server,\nheadless runner, or remote panel processes. It does not publish presence,\nrepair route tuples, send messages, or read credentials.\n\nMost users should start with `setup`. Use `init` only when you want to manually\ncreate or reset the shared communication directory and local tap state.\n\n## Supported Public Setup Profiles\n\n| Profile          | Use when                                                                |\n| ---------------- | ----------------------------------------------------------------------- |\n| `codex-cli`      | Codex CLI or headless CLI will use MCP tools plus inbox/receiver paths. |\n| `codex-app`      | Codex App/Desktop route readiness should be inspected read-only.        |\n| `claude-channel` | Claude/channel readiness should be inspected read-only.                 |\n\n## Common Commands\n\n### `setup`\n\nInspect and optionally apply first-run public deployment changes.\n\n```bash\nnpx @hua-labs/tap setup --profile codex-cli --dry-run --json\nnpx @hua-labs/tap setup --profile codex-cli --apply --json\nnpx @hua-labs/tap setup --profile codex-cli --profile-pack ./tap-profile-pack.json --json\n```\n\ntap refuses to mutate user-managed or ambiguous MCP entries.\n\n### `ready`\n\nPrepare or verify a concrete agent on a runtime surface.\n\n```bash\nnpx @hua-labs/tap ready --surface codex-cli --agent agent-a --json\nnpx @hua-labs/tap ready --surface codex-cli --agent agent-a --apply --json\n```\n\nBy default, `ready` reports the current or planned readiness state. With\n`--apply`, it applies reviewed readiness changes for the selected surface and\nagent.\n\n### `init`\n\nCreate or reset the shared comms directory and `.tap-comms/` state.\n\n```bash\nnpx @hua-labs/tap init\nnpx @hua-labs/tap init --comms-dir /path/to/comms\nnpx @hua-labs/tap init --permissions safe\nnpx @hua-labs/tap init --permissions full\n```\n\n### `add <runtime>`\n\nAdd a runtime instance and patch the runtime config when verification allows it.\n\n```bash\nnpx @hua-labs/tap add claude\nnpx @hua-labs/tap add codex --name agent-a\nnpx @hua-labs/tap add codex --name agent-b --port 4520\n```\n\n`gemini` remains accepted for legacy compatibility, but new first-run docs do\nnot recommend it as a default runtime.\n\n### `status`\n\nShow installed runtimes and their status.\n\n```bash\nnpx @hua-labs/tap status\nnpx @hua-labs/tap status --json\n```\n\n### `doctor`\n\nDiagnose setup, config drift, bridge health, managed MCP wiring, and runtime\nstate.\n\n```bash\nnpx @hua-labs/tap doctor\nnpx @hua-labs/tap doctor --setup --profile codex-cli --json\n```\n\n### `comms-doctor`\n\nExplain delivery by runtime surface, including local inbox evidence and live\nadapter readiness.\n\n```bash\nnpx @hua-labs/tap comms-doctor --all-known --json\nnpx @hua-labs/tap comms-doctor --agent agent-a --plan-send --json\n```\n\n### `flow-doctor`\n\nDiagnose one receiver/promoter lane without mutating process state.\n\n```bash\nnpx @hua-labs/tap flow-doctor --agent agent-a --json\n```\n\n`flow-doctor` is read-only by default. Its reviewed cleanup mode only archives\nstale non-lane presence records with a manifest and prunes matching stale\nheartbeat entries.\n\n### `reviews register`\n\nRegister formal review outcomes into a discoverable review evidence stream.\n\n```bash\nnpx @hua-labs/tap reviews register --source ./tap-comms --dry-run --json\n```\n\n### `serve`\n\nStart the bundled tap MCP server on stdio.\n\n```bash\nnpx @hua-labs/tap serve\n```\n\n### `bridge start|stop|restart`\n\nManage Codex app-server bridge lifecycle.\n\n```bash\nnpx @hua-labs/tap bridge start codex --agent-name agent-c\nnpx @hua-labs/tap bridge stop codex --keep-server\nnpx @hua-labs/tap bridge restart codex\n```\n\n## Core Concepts\n\n- **Runtime**: an AI tool or environment tap can connect to, such as Claude or\n  Codex.\n- **Agent**: a named participant, such as `agent-a`, that sends or receives\n  messages.\n- **Surface**: a specific runtime interface, such as `codex-cli` or\n  `codex-app`.\n- **Comms directory**: the shared file-backed message store for inboxes,\n  reviews, handoffs, and evidence.\n- **Profile**: a setup target that describes which runtime surface tap should\n  inspect or prepare.\n- **Profile pack**: a data-only input for validating custom operator\n  environments.\n\n## Permissions\n\nSafe mode reduces destructive local file operations. It is not a\nnetwork-isolated mode.\n\n- `safe` is the default.\n- `full` enables less restricted local runtime settings and should only be used\n  on trusted machines.\n\nSee [AI_GUIDE.md](./AI_GUIDE.md#permissions-and-safety) for details.\n\n## JSON Output\n\nMost operational commands support `--json` for machine-readable output.\n\n```bash\nnpx @hua-labs/tap status --json\n```\n\nExit codes use `0` for ok and `1` for error. Error codes use the `TAP_*`\nprefix.\n\n## Supported Runtimes\n\n| Runtime | Status                    | Notes                                      |\n| ------- | ------------------------- | ------------------------------------------ |\n| Claude  | supported                 | Uses `.mcp.json` / channel-style delivery. |\n| Codex   | supported                 | Uses CLI, MCP, and app-server surfaces.    |\n| Gemini  | legacy / deprecated       | Kept for compatibility only.               |\n| Other   | custom profile-pack input | Use data-only profile packs in `0.6.x`.    |\n\nAntigravity CLI is not a bundled adapter in `0.6.x`. Model it as a custom\nprofile-pack surface until a dedicated integration is released.\n\n## Examples\n\n- Generic profile pack:\n  [`examples/tap-profile-pack.example.json`](./examples/tap-profile-pack.example.json)\n- Narrative examples:\n  [`examples/`](./examples/)\n\nThe narrative examples are real collaboration stories, not setup defaults.\n\n## Recent Changes\n\nSee [CHANGELOG.md](./CHANGELOG.md) for full release history.\n\nHighlights in `0.6.x`:\n\n- dry-run-first public setup profiles;\n- `ready`, `comms-doctor`, and `flow-doctor` for surface-specific diagnostics;\n- explicit `tap reviews register` evidence registration;\n- profile-pack validation for custom environments;\n- stricter broad-role and stale-presence guards;\n- packaged AI operator guide and npm provenance publishing.\n\n## License\n\nMIT\n",
  "bytes": 8633,
  "sha": "21eb2ac68e15f1ce1382d92c2d7284e8b1a7f4fc29830fb31fafa2eab65196a1",
  "repo_slug": "hua-labs/tap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hua_labs_tap_tap_be6fe9e5/readme"
}