honcho-cli
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.
How do I install this agent skill?
npx skills add https://github.com/plastic-labs/honcho --skill honcho-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The honcho-cli skill provides a command-line interface for inspecting and debugging Honcho workspaces, including capabilities for managing Docker stacks and integrating Honcho with other local agents. While it performs significant system operations, these are aligned with its role as an AI memory management tool. A low-severity risk of indirect prompt injection exists because the skill processes untrusted data from session transcripts and peer memories.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 3 issues
What does this agent skill do?
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:
0success ·1client error (bad input, not found) ·2server error ·3auth error - Config:
~/.honcho/config.json(shared with other Honcho tools). The CLI ownsapiKeyandenvironmentUrlat the top level; runhoncho initto confirm or set them. Per-command scope (workspace / peer / session) is via-w/-p/-sflags orHONCHO_*env vars.
Command groups
honcho config— CLI configurationhoncho install— find the AI agents on this machine and add Honcho to them;honcho install --listonly reports which agents have Honchohoncho start/stop/status— local Docker stack (does not changeenvironmentUrl). First start pins the Honcho image digest and writesconfig.tomlinto the profile. Pass--setup basicor--setup advancedfor an interactive config wizard (TTY only; writes.envoverrides).honcho statuslists every profile; pass--profilefor one.honcho workspace— inspect, delete, search, chat, replay (copy to another workspace or instance)honcho peer— inspect, card, chat, searchhoncho session— inspect, view (transcript), context, summarieshoncho scope— list, create, inspect, sessions, add-sessions, remove-session, statushoncho message— list and gethoncho conclusion— list, search, create, deletehoncho dream— list, inspect (what each dream changed; workspace or admin key)honcho ingest(experimental: needsHONCHO_EXPERIMENTAL=1) — import, status, derive, reset, link, unlink: load source records into an auto workspace, review them, derive (workspace or admin key).honcho peer exclude/honcho session excludestop derivation about an imported person or session beforeingest derive
Rules
- Always pass
--jsonwhen processing output programmatically. - Run
honcho peer inspectbeforehoncho peer chatto understand context. - Use
honcho session contextto see exactly what an agent receives. - Never run
honcho workspace deletewithouthoncho workspace inspectfirst. honcho ingest importholds back bot records no person interacted with (--bots interacted, the default);--bots allimports every record.- After
honcho ingest import, runhoncho ingest statusand exclude what shouldn't be modeled beforehoncho ingest derive: exclusions apply only to records not yet released. - To make two imported accounts one person:
honcho ingest link <kept> <other> --reset --yes, thenhoncho ingest importagain. A link never moves imported messages, so it's refused without the reset. Resolve the people before any separateingest reset: a reset re-sorts the numbered list. - Compare peer card with conclusions to understand memory state.
- After
honcho scope add-sessions, checkhoncho scope status <name>before a scopedchat: apendingbackfill means the scope has not caught up yet, not that there is nothing to recall. honcho startdoes not rewriteenvironmentUrl. UseHONCHO_BASE_URL=http://127.0.0.1:8000to 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
When a fact appeared, vanished, or the card changed and nothing in the transcript explains it, check the dreams:
honcho dream list -p <peer_id> --json # newest first
honcho dream inspect <run_id> --json # created (with sources), removed, card before/after
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
7. Copy a workspace
honcho workspace replay re-sends a workspace's messages into another workspace, which derives its own memory from them. Conclusions and peer cards are not copied.
# Always dry-run first: it reads both sides and writes nothing
honcho workspace replay --from <src> --to <dst> --dry-run --json | jq '.actions, .messages_to_send'
# Another instance, e.g. managed Honcho (configured) to a self-hosted one.
# The configured key is never sent to it; set HONCHO_TO_API_KEY if its auth is on
honcho workspace replay --from <src> --to-url http://localhost:8000 --json
# Only the N sessions with the most recent message
honcho workspace replay --from <src> --to <dst> --num-sessions 20 --json
- Each session's
actionin the dry run iscreate,resume,up_to_dateorconflict. A conflict means the destination has different messages under that session ID; a replay skips it and exits1. Pass a different--to. - A rerun resumes: messages already in the destination are skipped.
- Conclusions and peer cards written through the API are not recreated, because they have no source message.
not_copied.conclusions_in_sourcein both reports counts every conclusion in the source; Honcho does not mark which ones were written through the API. - The destination session has the source's current members from its first message. A peer that joined late and observes others gets conclusions from messages sent before it joined.
- Derivation on the destination continues after the command exits. The result's
check_derivationfield is thequeue-statuscommand to poll.
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/plastic-labs/honcho/honcho-cli">View honcho-cli on skillZs</a>