honcho-cli

agentsplastic-labs

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.

Install

npx skills add https://github.com/plastic-labs/honcho --skill honcho-cli

SKILL.md

---name: honcho-clidescription: 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, chat
honcho peer — inspect, card, chat, search
honcho session — inspect, view (transcript), context, summaries
honcho scope — list, create, inspect, sessions, add-sessions, remove-session, status
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.
After honcho scope add-sessions, check honcho scope status <name> before a scoped chat: a pending backfill means the scope has not caught up yet, not that there is nothing to recall.
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 workspace chat "what themes show up across peers?" --json
honcho workspace chat "what happened in this project?" --scope my-project --json
honcho peer search <peer_id> "query" --json

6. Bound recall with a scope

honcho scope list --json
honcho scope inspect <name> --json                       # members + backfill summary
honcho scope create <name> --sessions <id1>,<id2> --json
honcho scope status <name> --json                        # wait until nothing is pending
honcho workspace chat "what happened here?" --scope <name> --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
honcho peer chat <peer_id> "what happened here?" --scope my-project --json
honcho workspace chat "what themes show up across peers?" --json