Agent Skills › plastic-labs/honcho › honcho-cli

honcho-cli

GitHub

提供 Honcho CLI 使用指南，涵盖工作区、对等体及会话状态的检查与调试。适用于排查记忆循环、验证对话质量及诊断部署问题，支持本地 Docker 栈管理与 JSON 输出处理。

skills/honcho-cli/SKILL.md plastic-labs/honcho

Trigger Scenarios

需要检查 Honcho 工作区或节点状态调试代理记忆或会话上下文验证本地 Honcho 部署是否正常运行

Install

npx skills add plastic-labs/honcho --skill honcho-cli -g -y

More Options

Use without installing

npx skills use plastic-labs/honcho@honcho-cli

指定 Agent (Claude Code)

npx skills add plastic-labs/honcho --skill honcho-cli -a claude-code -g -y

安装 repo 全部 skill

npx skills add plastic-labs/honcho --all -g -y

预览 repo 内 skill

npx skills add plastic-labs/honcho --list

SKILL.md

Frontmatter

{
    "name": "honcho-cli",
    "description": "Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, or dialectic quality — any task that requires introspection of a Honcho deployment, including verifying that a recall\/record memory loop is actually working.",
    "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 start / stop / status — local Docker stack (does not change environmentUrl). First start pins the Honcho image digest and writes config.toml into the profile. Pass --setup basic or --setup advanced for an interactive config wizard (TTY only; writes .env overrides). honcho status lists every profile; pass --profile for one.
honcho workspace — inspect, delete, search
honcho peer — inspect, card, chat, search
honcho session — inspect, view (transcript), 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.
Compare peer card with conclusions to understand memory state.
honcho start does not rewrite environmentUrl. Use HONCHO_BASE_URL=http://127.0.0.1:8000 to talk to local stack.

Inspection tour

When orienting to a Honcho deployment, walk outside-in:

1. Understand the workspace

honcho workspace inspect --json

2. Find the peer

honcho peer list --json
honcho peer inspect <peer_id> --json

3. Check peer's memory

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

honcho session inspect <session_id> --json
honcho session view <session_id> --last 20 --json
honcho session view <session_id> --page 2 --size 50 --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

honcho workspace search "query" --json
honcho peer search <peer_id> "query" --json

Debugging playbook

Peer not learning?

# Is observation enabled?
honcho peer inspect <peer_id> --json | jq '.configuration'

# What conclusions exist?
honcho conclusion list --observer <peer_id> --json
honcho conclusion search "expected topic" --observer <peer_id> --json

Session context looks wrong?

# 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?

# 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