diff --git a/.claude/skills/honcho-cli/SKILL.md b/.claude/skills/honcho-cli/SKILL.md new file mode 100644 index 00000000..e2276669 --- /dev/null +++ b/.claude/skills/honcho-cli/SKILL.md @@ -0,0 +1,117 @@ +--- +name: honcho-cli +description: Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, queue status, or dialectic quality — any task that requires introspection of a Honcho deployment. +allowed-tools: Bash(honcho:*), Bash(jq:*), Read, Grep +--- + +# Honcho CLI + +`honcho` wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation. Use it to inspect workspace state, debug peer memory, and diagnose the dialectic. + +## Output & config + +- **TTY**: human-readable tables (default when interactive) +- **Piped / `--json`**: JSON — collection commands emit arrays, single-resource commands emit objects +- **Exit codes**: `0` success · `1` client error (bad input, not found) · `2` server error · `3` auth error +- **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars. + +## Command groups + +- `honcho config` — CLI configuration +- `honcho workspace` — inspect, delete, search +- `honcho peer` — inspect, card, chat, search +- `honcho session` — inspect, messages, context, summaries +- `honcho message` — list and get +- `honcho conclusion` — list, search, create, delete + +## Rules + +- Always pass `--json` when processing output programmatically. +- Run `honcho peer inspect` before `honcho peer chat` to understand context. +- Use `honcho session context` to see exactly what an agent receives. +- Never run `honcho workspace delete` without `honcho workspace inspect` first. +- Check queue status when derivation seems stalled. +- Compare peer card with conclusions to understand memory state. + +## Inspection tour + +When orienting to a Honcho deployment, walk outside-in: + +### 1. Understand the workspace + +```bash +honcho workspace inspect --json +``` + +### 2. Find the peer + +```bash +honcho peer list --json +honcho peer inspect --json +``` + +### 3. Check peer's memory + +```bash +honcho peer card --json +honcho conclusion list --observer --json +honcho conclusion search "topic" --observer --json +``` + +### 4. Debug a session + +```bash +honcho session inspect --json +honcho message list --last 20 --json +honcho session context --json +honcho session summaries --json +``` + +### 5. Search across workspace + +```bash +honcho workspace search "query" --json +honcho peer search "query" --json +``` + +## Debugging playbook + +### Peer not learning? + +```bash +# Is observation enabled? +honcho peer inspect --json | jq '.configuration' + +# Is the deriver queue processing messages? +honcho workspace queue-status --json + +# What conclusions exist? +honcho conclusion list --observer --json +honcho conclusion search "expected topic" --observer --json +``` + +### Session context looks wrong? + +```bash +# Raw context an agent would receive +honcho session context --json + +# Summaries feeding the context +honcho session summaries --json + +# Recent message history +honcho message list --last 50 --json +``` + +### Dialectic giving bad answers? + +```bash +# What the peer card says +honcho peer card --json + +# Conclusions on the specific topic +honcho conclusion search "topic" --observer --json + +# Exercise the dialectic directly +honcho peer chat "what do you know about X?" --json +``` diff --git a/docs/v3/documentation/introduction/vibecoding.mdx b/docs/v3/documentation/introduction/vibecoding.mdx index 86af6483..5c5bde1a 100644 --- a/docs/v3/documentation/introduction/vibecoding.mdx +++ b/docs/v3/documentation/introduction/vibecoding.mdx @@ -66,6 +66,24 @@ claude mcp add honcho \ --- +## CLI + +Inspect and debug a running Honcho deployment from your terminal. The honcho CLI wraps the Python SDK with agent-friendly defaults — JSON output, structured errors, and commands for every primitive (workspaces, peers, sessions, messages, conclusions). + +**Get started:** + +```bash +uv tool install honcho-cli +honcho init # configure apiKey + environmentUrl +honcho doctor # verify connectivity +``` + +The CLI also ships an agent skill. Install it with `npx skills add plastic-labs/honcho` and pick `honcho-cli` from the list. + +See the [full CLI reference](/v3/documentation/reference/cli) for all commands, flags, and environment variables. + +--- + ## Claude Code Plugin Use Honcho to build with Honcho! The [plugin](/v3/guides/integrations/claudecode) provides Claude Code persistent memory that survives context wipes and session restarts. @@ -109,6 +127,12 @@ curl -o ~/.claude/skills/honcho-integration.md https://raw.githubusercontent.com Invoke with `/honcho-integration` in your coding agent. +#### honcho-cli + +**For inspection & debugging.** Teaches your coding agent the right commands and flags for the [honcho CLI](#cli) — peer memory, session context, queue status, dialectic quality. + +Invoke implicitly when you ask your agent to inspect a Honcho deployment. + #### migrate-honcho-py / migrate-honcho-ts **For SDK upgrades.** Migrates code from v1.6.0 to v2.0.0 (required for Honcho 3.0.0+). Use when upgrading the SDK or seeing errors about removed APIs like `observations`, `Representation`, `.core`, or `get_config`. @@ -140,6 +164,7 @@ I want to start building with Honcho - an open source memory library for buildin - Core repo: https://github.com/plastic-labs/honcho - Python SDK: https://github.com/plastic-labs/honcho-python - TypeScript SDK: https://github.com/plastic-labs/honcho-node +- CLI (inspect & debug a deployment): https://github.com/plastic-labs/honcho/tree/main/honcho-cli - Discord bot starter: https://github.com/plastic-labs/discord-python-starter - Telegram bot example: https://github.com/plastic-labs/telegram-python-starter diff --git a/honcho-cli/README.md b/honcho-cli/README.md index 8271d200..804e2285 100644 --- a/honcho-cli/README.md +++ b/honcho-cli/README.md @@ -19,16 +19,6 @@ As a standalone tool (recommended): uv tool install honcho-cli ``` -As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project): - -```bash -uv add honcho-ai[cli] -# or -pip install honcho-ai[cli] -``` - -Either way, you'll get the `honcho` command on your PATH. - ## Quick Start ```bash @@ -142,6 +132,16 @@ Non-interactive onboarding: HONCHO_API_KEY=hch-v3-xxx honcho init --base-url https://api.honcho.dev ``` +## Agent skill + +`honcho-cli` ships with a skill that teaches agents the right commands and conventions for inspecting and debugging a Honcho deployment. Install it anywhere skills are accepted (Claude Code, other skill-aware agents): + +```bash +npx skills add plastic-labs/honcho +``` + +The picker lists every skill for Honcho — select `honcho-cli` . + ## Environment Variables All `HONCHO_*` env vars work at runtime — no config file required. diff --git a/honcho-cli/src/honcho_cli/skills/CONTEXT.md b/honcho-cli/src/honcho_cli/skills/CONTEXT.md deleted file mode 100644 index 59e5fdcd..00000000 --- a/honcho-cli/src/honcho_cli/skills/CONTEXT.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: honcho-cli -version: 0.1.0 -description: A terminal for Honcho — memory that reasons. ---- - -# Honcho CLI — Agent Interface - -## Overview - -`honcho` is a CLI for administering and debugging Honcho workspaces. It wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation. - -## Output Modes - -- **TTY**: Human-readable tables (default when interactive) -- **Piped/scripted**: JSON automatically -- `--json`: Force JSON output - -## Exit Codes - -- 0: Success -- 1: Client error (bad input, not found) -- 2: Server error -- 3: Auth error - -## Config - -Shared with other Honcho tools at `~/.honcho/config.json`. The CLI owns only -`apiKey` and `environmentUrl` at the top level. Host-specific -entries under `hosts` are untouched. - -Run `honcho init` to confirm or set those two values. Workspace / peer / -session are per-command — pass them via flags or env vars: - -```bash -honcho peer card -w my-workspace -p my-peer -# or -export HONCHO_WORKSPACE_ID=my-workspace -export HONCHO_PEER_ID=my-peer -honcho peer card -``` - -## Command Groups - -- `honcho config` — Manage CLI configuration -- `honcho workspace` — Inspect, delete, search workspaces -- `honcho peer` — Inspect, card, chat, search peers -- `honcho session` — Inspect, messages, context, summaries -- `honcho message` — List and get messages -- `honcho conclusion` — List, search, create, delete conclusions diff --git a/honcho-cli/src/honcho_cli/skills/honcho-debug.md b/honcho-cli/src/honcho_cli/skills/honcho-debug.md deleted file mode 100644 index 31ce2203..00000000 --- a/honcho-cli/src/honcho_cli/skills/honcho-debug.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: honcho-cli-debug -version: 0.1.0 -description: Debug Honcho peer representations and memory ---- - -# Honcho CLI — Debug Skills - -## Rules - -- Check queue status when derivation seems stalled -- Compare peer card with conclusions to understand memory state - -## Debugging Memory Issues - -### Peer not learning? - -```bash -# Check if observation is enabled -honcho peer inspect --json | jq '.configuration' - -# Check queue — are messages being processed? -honcho workspace queue-status --json - -# Check what conclusions exist -honcho conclusion list --observer --json -honcho conclusion search "expected topic" --observer --json -``` - -### Session context looks wrong? - -```bash -# See raw context -honcho session context --json - -# Check summaries -honcho session summaries --json - -# Check message history -honcho message list --last 50 --json -``` - -### Dialectic giving bad answers? - -```bash -# Check what the peer card says -honcho peer card --json - -# Check conclusions for the specific topic -honcho conclusion search "topic" --observer --json - -# Try the dialectic directly -honcho peer chat "what do you know about X?" --json -``` diff --git a/honcho-cli/src/honcho_cli/skills/honcho-inspect.md b/honcho-cli/src/honcho_cli/skills/honcho-inspect.md deleted file mode 100644 index 14c0cb94..00000000 --- a/honcho-cli/src/honcho_cli/skills/honcho-inspect.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: honcho-cli-inspect -version: 0.1.0 -description: Inspect Honcho workspace state for debugging ---- - -# Honcho CLI — Inspection Skills - -## Rules - -- Always use `--json` when processing output programmatically -- Run `honcho peer inspect` before `honcho peer chat` to understand context -- Use `honcho session context` to see exactly what an agent receives -- Never run `honcho workspace delete` without `honcho workspace inspect` first - -## Inspection Workflow - -### 1. Understand the workspace - -```bash -honcho workspace inspect --json -``` - -### 2. Find the peer - -```bash -honcho peer list --json -honcho peer inspect --json -``` - -### 3. Check peer's memory - -```bash -honcho peer card --json -honcho conclusion list --observer --json -honcho conclusion search "topic" --observer --json -``` - -### 4. Debug a session - -```bash -honcho session inspect --json -honcho message list --last 20 --json -honcho session context --json -honcho session summaries --json -``` - -### 5. Search across workspace - -```bash -honcho workspace search "query" --json -honcho peer search "query" --json -```