xCreen

xCreen local CLI and JSON interface

The xcreen command talks to the running xCreen app over a private, same-user Unix socket. Use it from a terminal, a script or an agent with shell access.

The installer copies it to ~/.local/bin/xcreen. There is no network listener and no HTTP API. Full reference: docs/cli.md.

Commands

usage: xcreen [--json] COMMAND
  status                         live app-owned state (never cached status.json)
  integrity [get|on|off]          off is explicit capture consent, subject to macOS gates
  session visibility [get|on|off]  show/hide the same Hermes session (default off)
  connection connect|disconnect|reconnect  (also accepted as top-level commands)
  models [list] | model select PROVIDER MODEL   (select also saves the xCreen default)
  model default [get] | model default PROVIDER MODEL  xCreen-session default only
  server [show]                   xCreen server URL, reachability and upload queue
  server set URL [--token-stdin | --token-file PATH]   token is stored in the Keychain
  flush                          upload everything still queued now
  settings [show] | settings set python|root|vault|timezone VALUE   (paths on the server)
  settings autodetect | autodetect   find Hermes and the vault on the server
  ask QUESTION [--wait-ms 0..30000]  explicit submission to the existing xCreen session
  history [--after CURSOR]        bounded sanitized history pages
  batches [--after BATCH_ID]      up to 20 durable batch metadata records
  batches retry                   verify, then re-queue only receipt-proven zero-effect batches
  verify                         read-only receipt reconciliation; no inference/note writes
  cancel
  images [list|open ID]           reply attachment metadata/open through the app
  panel [show|hide]
  start | stop | restart | quit
  logs [-n N] [--no-follow] [--gateway | --server]   (server logs only for a local server)

With Hermes on another machine, the app forwards Hermes, model, batch and settings commands to xcreen-server over its HTTP protocol; xcreen server shows which server and whether it is reachable.

JSON output

Put --json before the command. You get the app's full response as one JSON object:

{
  "ok": true,
  "error": null,
  "reply": "…answer text, for ask…",
  "snapshot": {
    "app": "…", "connected": true, "integrity": true, "capture": "…",
    "message": "…", "models": [{"provider": "…", "model": "…"}],
    "currentModel": {"provider": "…", "model": "…"},
    "defaultModel": {"provider": "…", "model": "…"}, "defaultModelApplied": true,
    "settings": {"python": "…", "root": "…", "vault": "…"},
    "images": [{"id": "…", "timestamp": "…"}],
    "sessionVisible": false, "sessionVisibilityPending": false
  }
}

Without --json, the CLI prints the reply if there is one, otherwise the snapshot. Errors go to stderr as xcreen: … with exit code 1. Values shown as "…" vary; fields may be absent when unknown (for example actualSessionVisible).

Examples

xcreen --json status
xcreen --json ask "What was the error I saw in the build log this morning?" --wait-ms 30000
xcreen --json history
xcreen --json batches
xcreen verify
xcreen integrity on

ask submits to the one existing xCreen session in your Hermes Agent and waits at most 30 seconds; a timeout does not cancel the question, so read the answer later with history. xcreen integrity off starts capture and is your consent; scripts and agents should never run it for you.

Use with Hermes Agent

Inside xCreen's own Hermes session, the model already has scoped tools for OCR search, nearby screenshots and capture coverage. Other Hermes chats with terminal access can run xcreen --json ask "…" to ask that session.

Planned: MCP server

xCreen does not have an MCP server today. A read-only one is planned, with these tools:

It will not change Integrity or settings. Track it in the roadmap.

What xCreen is · FAQ · Alternatives