Getting started

One-line installCopy Anchor Link

Prefer to skip the manual steps? Two bootstrap scripts take a fresh machine from zero to a working agentproto (Node check/install, the CLI, the daemon, agentproto doctor) non-interactively:

# macOS / linux
curl -fsSL https://raw.githubusercontent.com/agentproto/ts/main/scripts/bootstrap/install.sh | bash

# Windows 10/11 (PowerShell 5.1+)
irm https://raw.githubusercontent.com/agentproto/ts/main/scripts/bootstrap/install.ps1 | iex

Both are idempotent (safe to run twice, never downgrade an existing valid Node), install nothing but Node and the CLI, and print the manual command on every failure path.

From npm install to working setupCopy Anchor Link

From npm install to a working install — daemon running, an agent harness ready, your coding client wired to agentproto over MCP, skills installed — with one command: agentproto setup. The manual path is kept below for when you want to do (or understand) each step yourself.

Looking for the other direction — agentproto driving Claude Code, Codex, or Hermes as an adapter instead of being called by them — see verbs/install.md and verbs/run.md. This walkthrough is: your existing coding CLI calls into agentproto over MCP.

1. Install the CLICopy Anchor Link

npm i -g @agentproto/cli
agentproto --version

Requires Node.js ≥ 20.9.0. The binary is named agentproto; --help (no args, or -h) prints the full verb list.

2. Run the setup wizardCopy Anchor Link

cd /path/to/your/project
agentproto setup

It checks everything agentproto doctor checks, proposes only what's missing, and applies your choices with the same verbs you'd run by hand:

Re-running resumes: steps that are already fine are skipped. Useful flags: --dry-run (show the plan, change nothing), --yes (take the defaults, unattended — never applies secrets), --only/--skip <step>. See verbs/setup.md.

Check your install: agentproto doctorCopy Anchor Link

agentproto doctor

The same checklist as the wizard, read-only — Node, workspace, daemon, agent harnesses, auth, MCP clients, skills — with the exact command to fix each gap. Re-run it anytime; attach agentproto doctor --json to bug reports. See verbs/doctor.md.

Manual installCopy Anchor Link

The same result, one verb at a time — what agentproto setup runs for you.

Register your workspaceCopy Anchor Link

A workspace is a registered project directory other verbs can target by slug instead of by absolute path.

cd /path/to/your/project
agentproto workspace add . --slug my-project
agentproto workspace list

See verbs/workspace.md.

Start the daemonCopy Anchor Link

The daemon boots a local HTTP gateway — sessions, MCP, events — bound to the workspace you just registered.

On macOS and Windows, let the OS keep it running in the background (agentproto daemon install — launchd plist on macOS, a per-user scheduled task at logon on Windows):

agentproto daemon install

On Linux (or anywhere, one-off), run serve in the foreground or detached:

agentproto serve --workspace /path/to/your/project

This runs in the foreground (Ctrl-C to stop) — good for a first run. It writes <workspace>/.agentproto/runtime.json with the live port and a per-boot bearer token; MCP tool calls from 127.0.0.1/localhost don't need that token, it's only required for mutating HTTP routes called from a non-localhost origin.

For an always-on background service instead (macOS launchd today), see verbs/daemon.md — same binary, same flags, just supervised by the OS.

Leave the daemon running and open a second terminal for the next steps.

Register the MCP server in Claude Code (project-scoped)Copy Anchor Link

Claude Code speaks the MCP Streamable HTTP transport natively, so it can call the daemon directly at http://127.0.0.1:18790/mcp — no bridge process needed.

Project scope means the config lives in the repo and applies to every contributor who opens it in Claude Code. Create .mcp.json at the project root:

{
  "mcpServers": {
    "agentproto": {
      "type": "http",
      "url": "http://127.0.0.1:18790/mcp"
    }
  }
}

Adjust the port if you passed --port to serve. Restart your Claude Code session — the agentproto server appears in its MCP panel and its tools become available immediately.

For Codex, Cursor, Claude Desktop, or Hermes instead — including a user-scoped (not project-scoped) Claude Code registration — see the full guide: guides/mcp-in-coding-cli.md. agentproto install-mcp --yes also automates this step (and the equivalent for every other coding CLI it detects on the machine) if you'd rather not hand-write the config.

Verify — read-only checksCopy Anchor Link

Confirm the daemon is up and the tool surface is reachable before trusting an agent to use it. Neither command below mutates anything.

curl -s http://127.0.0.1:18790/health | python3 -m json.tool
# → { "status": "ok", "workspace": "...", "registered": [...], "uptimeMs": ... }

curl -s -X POST http://127.0.0.1:18790/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | grep -o '"name":"[a-z_]*"' | head -20

The MCP endpoint uses the Streamable HTTP transport — both application/json and text/event-stream must be present in Accept or it responds 406 Not Acceptable.

From inside Claude Code itself: type /mcp in the chat input and confirm agentproto is listed, or just prompt the agent — "List the MCP tools available from agentproto."

Install the skill packCopy Anchor Link

Skills teach the agent how to use the tools you just exposed — orchestration patterns, session supervision, delegation conventions.

# List the skills in the pack, no writes:
agentproto install skill/agentproto-pack --list

# Install it:
agentproto install skill/agentproto-pack

Without --target, this fans out to every installed adapter that declares a metadata.skills block. See verbs/install.md.

agentproto setup does all of the above in one guided pass (agentproto onboard is its alias).

What's nextCopy Anchor Link

• Persistent sessions you can detach + reattach: verbs/sessions.md
• Orchestrating a multi-agent swarm from a manifest: concepts/swarms.md + verbs/run-swarm.md
• Gating whether a spawned agent may itself delegate to sub-agents: concepts/roles.md
• What a session's transcript captures and how to export it: concepts/session-transcripts.md
• Hosting your CLI for a remote agent over a tunnel: verbs/serve.md + verbs/auth.md
• Driving an adapter directly instead of being called via MCP: verbs/install.md + verbs/run.md