git:20260624.09226fc to git:20260624.9017fed

- description: Two audiences. (A) MCP DEVELOPER — add agent-connector as a framework dependency inside a developer-branded MCP package, write the server/hooks/surfaces ONCE with defineConnector({...}), and ship install/doctor/uninstall through the branded package/bin (for example `npx @acme/acme-db-mcp install`) across every detected AI-agent CLI in the 42 registered deploy adapters, with default local-first per-tool token telemetry for YOUR OWN wrapped stdio server. package.json name/mcpName/bin/version are the default metadata source; explicit id/mcp.hostAlias/version are advanced overrides only. (B) AGENT-CLI END USER — with NO connector at all, run `agent-connector usage` to see per-CLI / per-model token totals scanned read-only from each agent CLI's own session logs. Use this when a developer wants one integration to reach many agent hosts and to see which of their own server's tools cost the most context, OR when any agent-CLI user wants whole-conversation token totals per CLI/model with zero setup.

- agent-connector serves two distinct audiences and the work forks between them:

-

- - **(A) MCP developer** — depends on agent-connector as a framework inside their

- own branded MCP package, writes an integration once with `defineConnector()`,

- and ships their MCP server + lifecycle hooks (+ commands / skills / subagents /

- memory) across every detected agent CLI through their own package/bin. It solves two dev problems: (1) each agent host re-invents

- MCP registration + lifecycle hooks with incompatible config files, root keys, formats

- (JSON/JSONC/TOML/YAML/exported TS), and event names; (2) no host reports per-tool

- token usage back to an MCP server. Write the integration once; the branded CLI renders it into

- each installed host's native dialect and measures the developer's OWN wrapped stdio

- server's per-tool token footprint locally.

- - **(B) Agent-CLI user** — has NOT authored a connector and just runs an agent CLI

- (Claude Code, Codex, Cursor, …). Their entire supported surface is one connector-free

- command, `agent-connector usage`, which reads each agent CLI's own session logs

- read-only to show per-CLI / per-model token totals. No `defineConnector`, no install,

- no config file.

-

- The one accuracy-critical line between them: if you BUILD an MCP integration,

- agent-connector is the framework underneath your branded package/bin, which deploys

- it everywhere and measures your own server's per-tool tokens. If you just USE agent CLIs, agent-connector reads their logs to show you per-CLI /

- per-model token totals — whole-conversation only, never itemized per MCP or per tool.

-

- ## When to reach for it

-

- - **(A) MCP developer** wants to ship ONE MCP server (and/or hooks / slash commands /

- Agent Skills / subagents / standing memory guidance) across many agent CLIs without

- hand-authoring N config dialects → `defineConnector` + a branded package/bin

- command such as `npx @acme/acme-db-mcp install`.

- - **(A) MCP developer** asks "which of MY OWN server's tools cost the most context?" →

- `telemetry report --by tool` / `telemetry leaderboard --by mcp|tool`. Requires a

- declared connector with a wrapped stdio server (per-tool counts exist only for the

- server your connector declares and wraps; remote http/sse/ws servers are not wrapped).

- - **(B) Agent-CLI user (no connector needed)** wants to compare token spend across the

- agent CLIs on their machine → `usage` (alone). This reports WHOLE-CONVERSATION totals

- per CLI / model / project / session / day — it does NOT and cannot itemize cost per

- individual MCP server or per tool, because agent CLIs do not log per-tool token

- attribution. For per-MCP/per-tool numbers, that MCP must be deployed and wrapped via a

- connector (the developer track above).

-

- Do NOT use it to author a brand-new MCP server protocol — it deploys + measures an

- existing server command/URL and wraps lifecycle hooks; it does not implement tools.

-

- ## Write once: defineConnector({...})

-

- Create `agent-connector.config.mjs` (or `.js` / `.json`) at the project root:

-

- ```ts

- import { defineConnector } from "@ken-jo/agent-connector";

-

- export default defineConnector({

- // package.json name/mcpName/bin/version are the default metadata source.

- // Set id or mcp.hostAlias only for legacy configs or multi-instance aliases.

-

- // MCP server — declared once, transport-polymorphic. Omit for a hooks-only connector.

- server: {

- transport: "stdio", // stdio | http | sse | ws

- command: "npx", // stdio: command required; remote: url required

- args: ["-y", "@acme/acme-db-mcp"],

- env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" }, // universal ${env:VAR} / ${env:VAR:-default}

- tools: { include: ["*"] },

- timeoutMs: 30_000,

- // wrapForTelemetry defaults true for stdio when telemetry is on

- },

-

- // Lifecycle hooks — 13 canonical events (SessionStart, SessionEnd, UserPromptSubmit,

- // PreToolUse, PostToolUse, PreCompact, Stop, Notification, PermissionRequest,

- // PostToolUseFailure, SubagentStart, SubagentStop, PostCompact); the framework

- // synthesizes the right entrypoint per host paradigm (json-stdio binary /

- // ts-plugin module / skip on mcp-only). Hosts without a native analog skip-warn —

- // never silently dropped.

- hooks: {

- PreToolUse: {

- matcher: "acme_write", // regex on tool name; empty = all

- async handler(evt) {

- return evt.toolName === "acme_write"

- ? { decision: "ask", reason: "Confirm Acme DB write" } // allow|deny|modify|context|ask

- : { decision: "allow" };

- },

- },

- SessionStart: {

- async handler() {

- return { decision: "context", additionalContext: "Acme DB schema v12 loaded." };

- },

- },

- },

-

- // Content surfaces (all optional, content-only files; written where supported).

- commands: [

- { name: "db-report", description: "Summarize the schema", prompt: "Report on {{schema}}.", argumentHint: "[schema]" },

- ],

- skills: [

- { name: "db-helper", description: "Guides DB queries; use when the user asks about the schema.",

- body: "# DB helper\nUse acme_query first...", resources: { "references/api.md": "..." } },

- ],

- // subagents: [{ name: "db-auditor", description: "...", prompt: "..." }],

-

- // Standing guidance (memory) — written ONCE as a marker-fenced, hash-stamped

- // managed block into the memory file each host actually reads: the standard

- // AGENTS.md on most supporting hosts, CLAUDE.md on Claude Code (opt-in

- // `platforms["claude-code"].memory.mode: "agents-import"` manages an @AGENTS.md

- // bridge instead), GEMINI.md on Gemini CLI. User edits inside the block are

- // hash-detected and never clobbered (`install --force` overrides after a backup);

- // uninstall excises exactly your block. 16 KiB hard cap / 4 KiB soft warn.

- memory: [

- { content: "Use the acme-db MCP tools for schema questions; never hand-edit migrations." },

- ],

-

- telemetry: { enabled: true, modelFamilyHint: "auto", measureToolDefs: true }, // ON by default

-

- // Per-platform escape hatches: disable a surface, force scope, merge `extra`

- // verbatim; `nativeHooks` wires ANY host hook event outside the 13 normalized

- // ones by its verbatim name on adapters with supportsNativeHooks; `configPatch`

- // patches claude-code host-exclusive settings keys (set-if-absent + skip-warn,

- // refcounted ownership, sensitive-key denylist, reversible uninstall).

- platforms: {

- warp: { hooks: false },

- "claude-code": {

- nativeHooks: {

- TaskCompleted: { async handler(evt) { /* evt.raw = host JSON, verbatim */ } },

- },

- configPatch: [{

- key: "statusLine", // dotted LEAF path into settings.json

- value: { type: "command", command: "acme-db statusline" },

- reason: "Render the Acme meter in Claude Code's status line",

- }],

- // memory: { mode: "agents-import" }, // or memory: { path: "docs/AGENTS.md" }

- },

- },

- targets: "auto", // "auto" = all detected, or e.g. ["claude-code","codex"]

- });

- ```

-

- A connector must declare at least one of `server`, `hooks`, `commands`, `skills`,

- `subagents`, or `memory` (or a per-platform `nativeHooks` / `configPatch`

- declaration). `defineConnector` validates eagerly and throws `ConnectorConfigError`

- on bad ids or missing derivable package identity, non-function handlers, duplicate surface names, oversized skill

- descriptions (>1024 chars), unsafe skill `resources` paths, memory content over the

- 16 KiB hard cap (or containing the literal managed-block marker tokens), a

- `nativeHooks` key that names one of the 13 normalized events (use `hooks` for

- those), or a `configPatch` key in the agent-connector namespace (`hooks*`,

- `mcpServers*` — the sensitive-key denylist is enforced at install).

-

- ## CLI workflow

-

- ```bash

- npm install @ken-jo/agent-connector # framework dependency of your MCP package

- cd my-mcp-project

-

- npx @acme/acme-db-mcp detect # user-facing path: your branded package/bin

- npx @acme/acme-db-mcp install --dry-run # preview every change, everywhere (nothing written)

- npx @acme/acme-db-mcp install # deploy across detected hosts

- npx @acme/acme-db-mcp doctor [--probe] # health checks; --probe spawns the real stdio server: initialize → ping → tools/list

- npx @acme/acme-db-mcp uninstall # full inverse — removes everything install wrote

-

- npx @ken-jo/agent-connector install --dry-run --connector ./agent-connector.config.mjs

- # development fallback / CI-debug path; not the foreground install brand for users

- ```

-

- `--scope` is `user` (default) or `project`. `--targets` is a comma-separated

- PlatformId list. `--dry-run` works on install/upgrade/uninstall. `--connector <path>`

- points at a config explicitly; otherwise it's found by walking up from the project.

- `install --force` additionally overwrites USER-EDITED memory managed blocks (hash

- drift) after a timestamped backup — the default is warn-and-leave. Canonical

- flag-level reference: `llms-full.txt` §3 / the docs site `/docs/dev/cli`.

-

- ## Telemetry, leaderboards, usage

- There are two completely separate token-measurement axes, split by audience. They

- measure DIFFERENT things and are NEVER summed.

- **Axis 1 — `telemetry` / 🔌 (MCP-developer track, the developer's OWN wrapped server).**

- Telemetry is ON by default: stdio servers are wrapped with `agent-connector serve` so

- every `tools/call` is measured (args in, results out, plus the one-time `tools/list`

- schema cost) and tokenized locally. This is the ONLY source of per-MCP and per-tool

- numbers, and it exists only for a server a registered connector declares and wraps —

- `serve` loads the connector by id and every record requires a connector id, so an

- arbitrary third-party MCP the user didn't author produces nothing here. Wrapping is

- stdio-only; remote (http/sse/ws) servers are registered but never wrapped. Every record

- carries a confidence tag (`tokenizer-exact | tokenizer-calibrated | tokenizer-approx |

- heuristic | host-native`).

- ```bash

- agent-connector telemetry report --by tool --since 7d # ranked per-tool footprint (also session|project)

- agent-connector telemetry export --format csv --out tel.csv

- agent-connector telemetry leaderboard --by mcp # which of YOUR servers costs most (also --by tool | --by surface)

- ```

- **Axis 2 — `usage` / 🖥️ (agent-CLI-user track, host-log scan, NO connector needed).**

- Reads each agent CLI's OWN session logs/DBs read-only and aggregates WHOLE-CONVERSATION

- totals. It groups ONLY by `platform | project | session | model | day` — there is NO

- per-MCP or per-tool dimension, because agent CLIs do not log per-tool token attribution.

- Use this for "which agent CLI / model is burning the most tokens?"; never read it as

- "which MCP/tool costs the most." Local readers report host-logged counts; a few are

- host-estimated (shown in the CONFIDENCE column); 5 "synced" platforms (cursor,

- antigravity, antigravity-cli, trae, warp) are skipped as "requires sync" unless a local

- cache already exists.

- ```bash

- npm i -g @ken-jo/agent-connector # optional: connector-free token telemetry utility

- agent-connector usage report --by platform --since 7d # whole-conversation totals from CLI logs (also project|session|model|day)

- agent-connector usage leaderboard --by platform # which CLI/host spent the most (also --by model)

- agent-connector usage export --format csv --out usage.csv

- ```

- The unified `agent-connector leaderboard` shows three origin-labeled boards with

- DIFFERENT prerequisites — never summed: 🔌 per-MCP (needs a connector + serve traffic),

- 🛰️ live host-native turns (needs the opt-in usage hook, installed only by the Gemini CLI

- and Antigravity adapters, and a connector at runtime), and 🖥️ host usage (the only board

- that works with no setup — same whole-conversation, per-CLI/per-model scan as `usage`).

- For a plain agent-CLI user with no connector, 🔌 and 🛰️ are empty; `usage` is the

- primary end-user entry point precisely because only its data source is connector-free.

- ## Operating model

- - **Home-dir single binary.** Runtime installs once under `~/.agent-connector`

- (override `AGENT_CONNECTOR_DATA_DIR`). Every host config we write is a thin

- pointer to that one stable binary, so one managed `agent-connector upgrade`

- propagates everywhere — never silent auto-update.

- - **Per-project data.** Telemetry/state is keyed by project identity (git remote or

- normalized path), stored under the home data-root — survives `git clean`, shared

- across hosts opening the same project. Native host config files are never relocated.

- - **Windows-first.** No symlinks, no POSIX-only assumptions.

- ## Privacy / opt-out

- Aggregate counts only — raw tool arguments and results are never stored or

- transmitted. Local-first, zero network egress by default. Opt out via

- `AGENT_CONNECTOR_TELEMETRY=0` or `telemetry: { enabled: false }`. Network

- calibration (Anthropic `count_tokens`) and host-native turn capture are opt-in only.