Agent Host Protocol CLI — a thin command-line wrapper around the official @microsoft/agent-host-protocol client for managing AHP server connections, sessions, and agent interactions.

ahpx is a command-line client for the Agent Host Protocol (AHP) — a WebSocket-based JSON-RPC protocol for managing AI agent sessions. Use ahpx to connect to AHP servers, create sessions, send prompts, stream responses, and handle tool confirmations from your terminal.

ahpx is a thin CLI wrapper: the protocol client itself is the official @microsoft/agent-host-protocol package. ahpx focuses on the command-line experience — connection profiles, session persistence, output formatting, fleet health, dev tunnels — and delegates the wire protocol to the official client.

Not a library. ahpx no longer ships an exported SDK. If you need to speak AHP programmatically, depend on @microsoft/agent-host-protocol directly. ahpx exposes only the ahpx CLI.

• 🔌 Connect to AHP servers via WebSocket with saved connection profiles
• 💬 Interactive and one-shot prompting with streaming output
• 📡 Multi-session management — concurrent sessions on a single connection
• 🔄 Event forwarding — webhook and WebSocket targets for dashboards and pipelines
• 🏗️ Fleet management — health checks, status monitoring, and server tagging
• 💾 Session persistence — resume sessions, export/import history
• 🔒 Configurable permission modes — approve-all, approve-reads, deny-all, autopilot
• 🔑 Automatic auth — token resolution from env vars, CLI, or interactive prompt
• 🌐 Dev Tunnel support — connect to remote agent hosts via Dev Tunnels
• ⚙️ Session config — agent-specific settings (auto-approve, isolation, mode)
• 🧩 Customizations — auto-discovered agent and skill files from .github/

npm install -g @tylerl0706/ahpx

# Add a server
ahpx server add local --url ws://localhost:8082 --default

# Start prompting
ahpx "what files are in this directory?"

Or use exec for one-shot tasks that create and dispose of a session automatically:

ahpx exec "summarize this repo"

Prompt options: -s <server>, -n <session-name>, -S <session-id>, -f <file>, --cwd <dir>, --config <key=value> (repeatable), --approve-all, --approve-reads, --deny-all, --idle-timeout <seconds>, --tag <key=value>, --forward-webhook <url>, --forward-ws <url>, --forward-filter <types>, --forward-headers <json>

Use -S <session-id> to target a session by its ID instead of name — useful for scripting and automation.

exec also accepts: -p <provider>, -m <model>, --config <key=value>

server add options: --token <token>, --default, --tag <tag> (repeatable), --tunnel <tunnel-id>

Connect to remote AHP agent hosts via Dev Tunnels. Discovers tunnels tagged with protocolv5. Requires GITHUB_TOKEN, GH_TOKEN, or gh auth token.

# Save a tunnel as a named server connection
ahpx server add my-remote --tunnel <tunnel-id>

# Use the remote server for sessions
ahpx session new -s my-remote -n remote-session --cwd C:/Users/me/project
ahpx prompt -s my-remote -n remote-session "fix the bug"

session new options: -s <server>, -p <provider>, -m <model>, -n <name>, --cwd <dir>, -t <timeout>, --config <key=value> (repeatable), --no-customizations

Set agent-specific configuration at session creation or modify it on an active session.

ahpx session new -n my-session --cwd /path/to/repo --config autoApprove=autopilot --config isolation=worktree
ahpx session config -n my-session              # view config
ahpx session config set autoApprove autopilot -n my-session   # update config

Available config keys depend on the agent. For copilotcli: autoApprove (default/autoApprove/autopilot), isolation (folder/worktree), mode (interactive/plan), branch, permissions.

Every completed turn is persisted locally with its complete prompt and response text (not just a preview), so the full transcript survives session close and host disposal.

ahpx session history my-session                 # compact: one truncated line per turn
ahpx session history my-session --full          # complete prompt + response for every turn
ahpx --format json session history my-session   # adds the full `response`/`prompt` per turn

ahpx session export my-session                          # json record (re-importable, full turns)
ahpx session export my-session --format markdown        # human-readable transcript to stdout
ahpx session export my-session --format markdown --out transcript.md

session export and session history accept the session name positionally. Records written before 0.4.0 only have a 200-char preview; those turns render the preview with a clear "full text not recorded — pre-0.4.0 session" note (no migration required).

ahpx automatically discovers .github/agents/*.md and .github/skills/*/SKILL.md files in the workspace and loads them into the agent session. Use --no-customizations to skip discovery.

ahpx session customization list -n my-session
ahpx session customization toggle <uri> -n my-session

ahpx is a CLI, not a library — it does not export an SDK. To speak the Agent Host Protocol from your own Node.js or TypeScript code, depend on the official client directly:

npm install @microsoft/agent-host-protocol

import { AhpClient } from '@microsoft/agent-host-protocol/client';
import { WebSocketTransport } from '@microsoft/agent-host-protocol/ws';

// See the @microsoft/agent-host-protocol docs for the full client API.

ahpx itself is built on top of this package and simply adds a polished command-line experience (connection profiles, session persistence, output formatting, fleet health, dev tunnels) around it.

ahpx uses semantic exit codes so scripts and automation can react to failures:

See docs/errors.md for the full error reference.

ahpx uses a layered configuration system. Settings are resolved in order of precedence:

1. CLI flags — highest priority (e.g. --format json)
2. Project config — .ahpxrc.json in the current directory or git root
3. Global config — ~/.ahpx/config.json
4. Defaults — built-in fallback values

# Initialize global config
ahpx config init

# View resolved config with source annotations
ahpx config show

Recognized keys: defaultServer, defaultProvider, defaultModel, permissions, timeout, format, verbose, and defaultSessionConfig.

The Agent Host Protocol exposes per-session agent configuration (the server advertises a schema — e.g. copilotcli has an isolation property with allowed values folder/worktree). You can pass these per session with -c key=value, but defaultSessionConfig lets you persist a default once so it applies to every new session automatically.

# Persist a default once (dotted path sets a nested member):
ahpx config set defaultSessionConfig.isolation folder

# Equivalent, setting the whole map as JSON:
ahpx config set defaultSessionConfig '{"isolation":"folder"}'

# Read it back:
ahpx config get defaultSessionConfig.isolation   # -> folder

# Now every new session runs in folder mode — no -c needed:
ahpx exec "fix the tests"

# A per-call -c always wins over the persisted default:
ahpx exec -c isolation=worktree "fix the tests"  # this session uses a worktree

Precedence (lowest → highest):

1. defaultSessionConfig from global config (~/.ahpx/config.json)
2. defaultSessionConfig from project config (.ahpxrc.json) — shallow-merged per-key over global (each key overrides individually; other keys survive)
3. Explicit -c key=value flags on the command (always win)

The merged map is applied at session creation everywhere a session is made (session new, prompt, exec, and the implicit prompt path). Keys are sent to the server as-is; the server validates them against its advertised schema, so an unknown key surfaces the server's own error rather than crashing the client.

Canonical example: persisting isolation=folder makes copilotcli sessions run in-place in your working directory instead of creating a git worktree — handy when you want the agent to operate directly on your checkout.

ahpx resolves auth tokens automatically, checked in order:

1. Connection profile token (from ahpx server add --token)
2. AHPX_TOKEN env var
3. GITHUB_TOKEN env var
4. GH_TOKEN env var
5. gh auth token CLI output
6. Interactive prompt

No explicit login command is needed — just ensure one of the above is available.

When an agent calls a tool, ahpx handles approval based on the tool's confirmation status:

• Server-confirmed tools — show [auto-approved] and proceed without prompting.
• Unconfirmed tools — show Allow Tool: ...? (y/N): and wait for user input.

Override with flags or session config:

ahpx exec --approve-all "fix the tests"                         # skip all prompts
ahpx exec --config autoApprove=autopilot "fix the tests"        # server-side auto-approval

Requires Node.js ≥ 20.

npm install          # Install dependencies
npm run build        # Build with tsup
npm run dev          # Watch mode
npm run typecheck    # Type check with tsc
npm run lint         # Lint with Biome
npm test             # Run tests with Vitest

All four quality gates must pass before committing:

npm run typecheck && npm run lint && npm test && npm run build

Project knowledge lives in .github/ so both humans and agents can find it:

• .github/skills/ahp-protocol/ — AHP protocol fundamentals
• .github/skills/ahpx-architecture/ — Codebase architecture and design
• .github/skills/capture-ahp-wire-frames/ — Debugging the wire protocol: tee-proxy capture of the exact frames ahpx sends (uses scripts/ahp-wire-tee.mjs)
• .github/agents/team-lead.md — Team lead agent with quality gates and workflow

Read the relevant skill docs before making changes — they'll save you time.

MIT