SDK protocol (stream-json)

The lowest-level integration surface: drive hipmmcode over NDJSON on stdin/stdout. This is what the server and bridges use internally, and it's the right choice when you're embedding hipmmcode as an agent engine inside another program.

hipmmcode --input-format stream-json --output-format stream-json

Each line in is a control message or user turn; each line out is an event.

Messages you send

Message	Purpose
{"type":"user", "message":{…}}	A user turn (text and/or attachments)
initialize	Handshake: capabilities, session info
set_model	Switch provider/model mid-session
interrupt	Cancel the running turn
set_permission_mode	Switch default / acceptEdits / plan / bypass
control responses	Answers to permission / question round-trips (below)

Events you receive

Event	Meaning
system (subtype init)	Session started: session id, model, tools
assistant / text deltas	Streaming response content
tool-use events	Each tool call + its result
control_request → can_use_tool	Permission round-trip: reply allow/deny on stdin
control_request → ask_user_question	Structured question round-trip
result	Turn finished: final text, usage, cost, subtype (success / error / budget_exceeded / …)

Add --include-partial-messages for raw per-token frames, --include-hook-events for hook lifecycle frames, --replay-user-messages to have your own turns echoed back (useful for transcript builders).

One-shot structured pipelines

You don't need the full protocol for simple automation — headless exec emits the same envelopes:

hipmmcode --print --output-format stream-json "run the tests and summarize failures"
hipmmcode --print --json --json-schema '{"type":"object",…}' "…"   # schema-validated answer

Permission wiring

In protocol mode, permission decisions come to you as can_use_tool control requests — your host process is the approver. Alternatives: pre-set a mode (--permission-mode acceptEdits), pass rules in settings, or use --permission-webhook to move decisions to an HTTP service. Unanswered requests fail closed.

Embedding checklist

1. Spawn hipmmcode --input-format stream-json --output-format stream-json (optionally -p/-m, --resume <id>).
2. Send initialize, then a user message.
3. Stream events; answer control_requests.
4. On result, either send the next user turn (the session stays warm) or exit.
5. Persist the session_id if you want to --resume later.

The complete, always-current handbook — message schemas, examples, exit codes — is embedded in the binary:

hipmmcode integration | less