Neo

Appearance

neo --json Protocol ​

neo --json is the machine-facing local integration surface for Neo.

  • Transport: newline-delimited JSON over stdin and stdout
  • stdout: protocol events only
  • stderr: operational diagnostics only
  • Human-facing modes remain separate:
    • neo for the interactive Ink UI
    • neo -p for one-shot print mode

Lifecycle ​

Recommended client flow:

  1. Send initialize
  2. Optionally send list_sessions, get_session, or resume_session
  3. Send run
  4. While a run is active, send cancel or permission_response as needed
  5. Send shutdown before process exit when you want deterministic cleanup

Compatibility note:

  • run still works without initialize
  • run with a new sessionId still creates a new public session

Requests ​

All requests are single JSON objects, one per line.

initialize ​

json
{"type":"initialize","requestId":"init-1","heartbeatIntervalMs":15000}

list_sessions ​

json
{"type":"list_sessions","requestId":"list-1"}

resume_session ​

json
{"type":"resume_session","requestId":"resume-1","sessionId":"public-1"}

get_session ​

json
{"type":"get_session","requestId":"session-1","sessionId":"public-1"}

run ​

json
{"type":"run","requestId":"req-1","sessionId":"public-1","message":"Reply with exactly: ok"}

permission_response ​

json
{"type":"permission_response","permissionRequestId":"perm-1","decision":"allow"}

cancel ​

json
{"type":"cancel","requestId":"req-1"}

shutdown ​

json
{"type":"shutdown","requestId":"bye-1"}