honcho-cli
The honcho-cli skill provides command-line access to the Honcho Python SDK for inspecting and debugging multi-agent deployments. Use it when you need to examine workspace state, investigate peer memory and card representations, review session context and message history, check queue status for stalled derivations, or search conclusions across a Honcho workspace. The tool outputs human-readable tables by default and structured JSON when piped or flagged with `--json`.
git clone --depth 1 https://github.com/plastic-labs/honcho /tmp/honcho-cli && cp -r /tmp/honcho-cli/.claude/skills/honcho-cli ~/.claude/skills/honcho-cliSKILL.md
# 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 <peer_id> --json ``` ### 3. Check peer's memory ```bash honcho peer card <peer_id> --json honcho conclusion list --observer <peer_id> --json honcho conclusion search "topic" --observer <peer_id> --json ``` ### 4. Debug a session ```bash honcho session inspect <session_id> --json honcho message list <session_id> --last 20 --json honcho session context <session_id> --json honcho session summaries <session_id> --json ``` ### 5. Search across workspace ```bash honcho workspace search "query" --json honcho peer search <peer_id> "query" --json ``` ## Debugging playbook ### Peer not learning? ```bash # Is observation enabled? honcho peer inspect <peer_id> --json | jq '.configuration' # Is the deriver queue processing messages? honcho workspace queue-status --json # What conclusions exist? honcho conclusion list --observer <peer_id> --json honcho conclusion search "expected topic" --observer <peer_id> --json ``` ### Session context looks wrong? ```bash # Raw context an agent would receive honcho session context <session_id> --json # Summaries feeding the context honcho session summaries <session_id> --json # Recent message history honcho message list <session_id> --last 50 --json ``` ### Dialectic giving bad answers? ```bash # What the peer card says honcho peer card <peer_id> --json # Conclusions on the specific topic honcho conclusion search "topic" --observer <peer_id> --json # Exercise the dialectic directly honcho peer chat <peer_id> "what do you know about X?" --json ```
Integrate Honcho memory and social cognition into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, implementing the dialectic chat endpoint for AI agents, or wiring Honcho into bot frameworks (nanobot, openclaw, picoclaw, etc).
Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or get_config methods.
Migrates Honcho TypeScript SDK code from v1.6.0 to v2.1.1. Use when upgrading @honcho-ai/sdk, fixing breaking changes after upgrade, or when errors mention removed APIs like .core, getConfig, observations, or snake_case properties.
Gives AI agents persistent memory across conversations using Honcho. Automatically saves and retrieves user context so the AI remembers preferences, history, and facts between sessions. Use when you need the AI to remember past conversations, recall what a user has told it, inject relevant context into prompts, or manage separate memory spaces for different topics.