From 2e380b5fea0fc4dcd4a974c986bc95af75712a02 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 22 Aug 2026 14:45:31 +0000 Subject: [PATCH] docs: recommend MCP install over long-term CLI use Point the getting-started skill and README at kody install plus host search/execute. Refresh the scoped ship-pr and orchestrate skills from the Kody registry. Co-authored-by: Kent C. Dodds --- .agents/skills/orchestrate/SKILL.md | 9 ++-- .agents/skills/ship-pr/SKILL.md | 27 ++++++++--- README.md | 69 +++++++++++++++++----------- skills/kody/SKILL.md | 70 ++++++++++++++--------------- src/help.ts | 2 +- test/skill.test.ts | 5 ++- 6 files changed, 110 insertions(+), 72 deletions(-) diff --git a/.agents/skills/orchestrate/SKILL.md b/.agents/skills/orchestrate/SKILL.md index 86256c8..a323d8f 100644 --- a/.agents/skills/orchestrate/SKILL.md +++ b/.agents/skills/orchestrate/SKILL.md @@ -4,7 +4,8 @@ description: > Orchestrate sub-agents for large tasks inside a single environment: plan, delegate coding to cheap/fast models, parallelize the critical path, keep reviews lean, and close every loop. Use when acting as an orchestrator or - writing a kickoff for one. Prefer implement when fan-out does not clearly pay. + writing a kickoff for one. Prefer implement when fan-out does not clearly + pay. For multi-environment fleets, use conduct instead. --- # Orchestrate @@ -12,7 +13,7 @@ description: > This is the kody `orchestrate` skill, scoped to `@kodycodes/cli`. Fan out **sub-agents inside one environment** (shared checkout). This repo is -one package; multi-environment fleets are out of scope here. +one package; multi-environment fleets (`conduct`) are out of scope here. Two modes: **be** the orchestrator, or **spawn** one (smarter model) if you are optimized for cheap/fast execution. @@ -46,5 +47,5 @@ optimized for cheap/fast execution. ## Kickoff (when spawning an orchestrator) Keep it short: goals + constraints + out-of-scope; "you orchestrate, don't bulk -code"; preferred implementer model; single-environment; done = falsifiable. -Point at this skill. +code"; preferred implementer model; single-environment (not conduct); done = +falsifiable. Point at this skill. diff --git a/.agents/skills/ship-pr/SKILL.md b/.agents/skills/ship-pr/SKILL.md index 201d0c3..4313637 100644 --- a/.agents/skills/ship-pr/SKILL.md +++ b/.agents/skills/ship-pr/SKILL.md @@ -15,28 +15,43 @@ This is the kody `ship-pr` skill, scoped to `@kodycodes/cli`. Self-assess; user policy overrides. +**Kent's standing policy (2026-08-08):** auto-ship (squash-merge + verify +publish) once AI reviewer feedback is addressed and CI is green, unless +**high** risk. High risk still parks ready-for-review unless merge authority +was granted explicitly. + - **Low** — green CI; nits ignorable; squash-merge when policy allows. - **Medium** — wait for AI reviewer(s); address **valid** feedback (ignore insignificant nits / already-fixed / wrong); then merge when policy allows. - **High** — leave ready-for-review unless the user granted merge authority. +## AI reviewers + +Prefer **Cursor Bugbot** (`Cursor Bugbot` check / `cursor[bot]` review comments). +Trigger with `bugbot run` or `@cursor review` on the PR if it has not started. + +**CodeRabbit:** if it is rate-limited, errored, or otherwise unavailable, **do +not wait** on it for low/medium risk — proceed with Bugbot + CI. Only wait on +CodeRabbit when the change is **high** risk (or the user explicitly asks). + ## Loop 1. Mark ready — `kody:@kentcdodds/github/pr/set-review-status` `{ prUrl, status: 'ready' }` (or owner/repo/prNumber). 2. Wait for CI — `gh pr checks` (or compose `loop-on-ci` / `fix-ci`). -3. Fix failures; for **medium+**, wait on AI reviewer(s) and address valid - feedback. Rebase only when actually unmergeable. Local gate is - `npm run validate`. If the change touches login / MCP protocol, also smoke - `whoami`, `search`, and `execute` against `https://kody.codes/mcp`. +3. Fix failures; for **medium+**, wait on AI reviewer(s) (Bugbot first; see + above for CodeRabbit) and address valid feedback. Rebase only when actually + unmergeable. Local gate is `npm run validate`. If the change touches login / + MCP protocol, also smoke `whoami`, `search`, and `execute` against + `https://kody.codes/mcp`. 4. Green + (medium+: valid feedback cleared) → break. 5. Push → repeat. ## Gates ≠ CI Blocked on a release / trusted-publishing / calendar gate → **end the run** -and schedule a wake. Don't sleep-poll or code-thrash an intentional time -window. +and schedule a wake (Kody `job_schedule` + `createRun`). Don't sleep-poll or +code-thrash an intentional time window. ## Merge / publish diff --git a/README.md b/README.md index b8fd991..33881ba 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,27 @@ # @kodycodes/cli -Turn one-off agent work into something you can rerun: a local MCP client for -[Kody](https://kody.codes) with login, OS keychain token storage, `search`, and -`execute`. Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in -with Client ID Metadata Documents (SEP-991). +Install [Kody](https://kody.codes) as a remote MCP server in local agents. +Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in with Client +ID Metadata Documents (SEP-991). + +**Long term, use Kody through the host MCP connection** — `search` and +`execute` in Cursor, Claude Code, or another client. This CLI writes that +config. Keep `kody login` / `kody search` / `kody execute` for bootstrap, +scripts, or hosts that cannot run MCP. ```bash npx @kodycodes/cli install -npx @kodycodes/cli login -npx @kodycodes/cli search "what can you do" npx @kodycodes/cli skill install ``` Copyright © 2026 [Kent C. Dodds](https://kentcdodds.com). MIT licensed. -## Install +## Install the MCP server ```bash -npm install -g @kodycodes/cli -kody login +npx @kodycodes/cli install ``` -Or run via `npx @kodycodes/cli` without a global install. - -## Commands - -| Command | Purpose | -| --- | --- | -| `kody install` | Detect running local MCP clients, write their config, and start host OAuth. | -| `kody login` | Browser OAuth (CIMD + PKCE). Stores access and refresh tokens. | -| `kody logout` | Deletes stored credentials. | -| `kody status` | Shows login state without printing secrets. | -| `kody whoami` | Confirms the MCP connection and lists tools. | -| `kody search [query]` | Calls Kody `search`. | -| `kody execute` | Calls Kody `execute` (`--code`, `--file`, or stdin via `--file -`). | -| `kody skill install` | Copies the getting-started skill into Claude Code / Cursor / Agents. | - `kody install` lists **running local** agents (Cursor, Claude Desktop, VS Code, Goose, Claude Code, Codex, Windsurf, Zed, and similar) and writes each host's remote MCP entry for `https://kody.codes/mcp`. Common host formats go through @@ -46,12 +32,45 @@ After install, the CLI prints a prompt you can paste into the configured agent to continue onboarding. Host OAuth stays in that client — `kody login` is only for the CLI itself. +```bash +npx @kodycodes/cli skill install +``` + +copies the getting-started skill into Claude Code / Cursor / Agents. That skill +also tells the agent to prefer the MCP server over the CLI. + `--mcp-url` or `KODY_MCP_URL` overrides the default `https://kody.codes/mcp`. + +## CLI as a local client + +Optional. Use when you need a scripted or headless client instead of a host +MCP connection. + +```bash +npm install -g @kodycodes/cli +kody login +``` + +Or run via `npx @kodycodes/cli` without a global install. + +## Commands + +| Command | Purpose | +| --- | --- | +| `kody install` | Detect running local MCP clients, write their config, and start host OAuth. **Recommended long-term path.** | +| `kody skill install` | Copies the getting-started skill into Claude Code / Cursor / Agents. | +| `kody login` | Browser OAuth (CIMD + PKCE) for the CLI itself. Stores access and refresh tokens. | +| `kody logout` | Deletes stored CLI credentials. | +| `kody status` | Shows CLI login state without printing secrets. | +| `kody whoami` | Confirms the CLI MCP connection and lists tools. | +| `kody search [query]` | Calls Kody `search` from the CLI (prefer the host MCP tool). | +| `kody execute` | Calls Kody `execute` from the CLI (`--code`, `--file`, or stdin via `--file -`). | + `--json` prints structured MCP results. ## Token storage -Credentials are stored in the OS secret store: +CLI credentials are stored in the OS secret store: - macOS: Keychain - Windows: Credential Manager diff --git a/skills/kody/SKILL.md b/skills/kody/SKILL.md index 4599199..d4f8224 100644 --- a/skills/kody/SKILL.md +++ b/skills/kody/SKILL.md @@ -1,69 +1,69 @@ --- name: kody description: > - Use the Kody CLI to log in, search Kody capabilities, and execute - sandboxed modules against kody.codes. Use when the user mentions Kody, - kody.codes, durable agent tasks, or wants to search/execute via `kody`. + Install Kody as a remote MCP server, then use `search` and `execute` + from the host agent. Use when the user mentions Kody, kody.codes, + durable agent tasks, or wants to search/execute via Kody. --- -# Kody CLI +# Kody -Kody is a remote MCP personal assistant. This skill uses the `@kodycodes/cli` -package — a local MCP client — instead of configuring an MCP server by hand. +Kody is a remote MCP personal assistant. **Long term, install it as an MCP +server in this agent** and call `search` / `execute` directly. Do not keep +using the CLI as the everyday interface once the server is connected. -## Install +`@kodycodes/cli` is a bootstrapper: it writes host MCP config and can act as +a local client when MCP is not available. + +## Install the MCP server (recommended) ```bash -npm install -g @kodycodes/cli -# or -npx @kodycodes/cli --help +npx @kodycodes/cli install ``` -Then install this skill into the current host if it is not already present: +That command lists **running local** agents and writes each host's remote +MCP entry for `https://kody.codes/mcp`. Host OAuth stays in that client — +do not run `kody login` for the host connection. -```bash -npx @kodycodes/cli skill install -``` +After install, prefer the Kody MCP tools in this agent: -To add Kody as a remote MCP server in running local agents: +- `search` — discover capabilities, packages, and entity detail +- `execute` — run one-off modules against those capabilities -```bash -npx @kodycodes/cli install -``` +Prefer `search` before `execute`. If Kody is already connected here, skip +the CLI and use those tools. -That command only lists local clients that are currently running. For web-based -clients (ChatGPT, Claude.ai, Grok), point the user at +For web-based clients (ChatGPT, Claude.ai, Grok), point the user at https://kody.codes/onboarding. -## Login +To copy this skill into Claude Code / Cursor / Agents: ```bash -kody login +npx @kodycodes/cli skill install ``` -The CLI opens a browser for Kody OAuth (PKCE + Client ID Metadata Documents). -If a browser cannot open, it prints the URL. Tokens (access + refresh) are -stored in the OS keychain on macOS, Windows, and Linux. Linux without Secret -Service falls back to a `0600` file under `$XDG_CONFIG_HOME/kody`. - -Never ask the user to paste tokens into chat. +## CLI fallback -## Use Kody +Use the CLI only for bootstrap, scripting, or when this agent cannot reach +Kody over MCP. ```bash +npm install -g @kodycodes/cli +kody login kody search "what can you do" kody search --domain email kody execute --code "import { kody } from 'kody:runtime'\nexport default async function main() { return await kody.search({ query: 'what can you do' }) }" -``` - -`search` and `execute` are Kody's only MCP tools. Prefer `kody search` before -`kody execute`. Add `--json` when you need structured output. - -```bash kody status kody whoami kody logout ``` +The CLI opens a browser for Kody OAuth (PKCE + Client ID Metadata Documents). +If a browser cannot open, it prints the URL. Tokens (access + refresh) are +stored in the OS keychain on macOS, Windows, and Linux. Linux without Secret +Service falls back to a `0600` file under `$XDG_CONFIG_HOME/kody`. + +Never ask the user to paste tokens into chat. + Override the MCP URL with `--mcp-url` or `KODY_MCP_URL` for preview or local servers. Default: `https://kody.codes/mcp`. diff --git a/src/help.ts b/src/help.ts index 8cced59..321631f 100644 --- a/src/help.ts +++ b/src/help.ts @@ -4,7 +4,7 @@ import { readPackageVersion } from './package-info.js' export const usage = `Kody CLI ${readPackageVersion()} -A local MCP client for https://kody.codes — login once, then search and execute. +Install Kody as a remote MCP server in local agents, or use this CLI as a local client. Usage: kody login [--mcp-url ] [--no-browser] diff --git a/test/skill.test.ts b/test/skill.test.ts index 997f279..6ade8de 100644 --- a/test/skill.test.ts +++ b/test/skill.test.ts @@ -15,7 +15,10 @@ test('installSkill writes the bundled skill to user host directories', async () const targets = await installSkill({ home, sourcePath }) assert.equal(targets.length, userSkillTargets(home).length) for (const target of targets) { - assert.match(readFileSync(target.path, 'utf8'), /kody login/) + const body = readFileSync(target.path, 'utf8') + assert.match(body, /Install the MCP server \(recommended\)/) + assert.match(body, /npx @kodycodes\/cli install/) + assert.match(body, /kody login/) } })