Geode On-device Transcribe & Summary

GeodeCLI Transcription — OpenClaw Integration Guide#

This document describes the recommended async integration between OpenClaw, GeodeCLI, and Geode.app.

Architecture:

• GeodeCLI: the CLI entry called by OpenClaw.
• Geode.app: the worker app, launched with --worker.
• Shared storage: the App Group container group.com.privycloudless.privyecho.

If the Geode app is not installed, OpenClaw should guide the user to install it from the Mac App Store:

• App Store URL (macOS): https://apps.apple.com/app/apple-store/id6752685916?pt=127800752&ct=openclaw&mt=8

---

1. Shared Paths#

Both GeodeCLI and Geode.app use the same App Group container:

• App Group ID: group.com.privycloudless.privyecho
• Shared root: ~/Library/Group Containers/group.com.privycloudless.privyecho/
• Recommended audio inbox: ~/Library/Group Containers/group.com.privycloudless.privyecho/CLIInbox/
• Task JSON directory: ~/Library/Group Containers/group.com.privycloudless.privyecho/CLITasks/
• Transcript / summary output directory: ~/Library/Group Containers/group.com.privycloudless.privyecho/CLITranscriptions/

If the source audio is outside the shared container, copy it into CLIInbox/ first.

---

2. Async API#

2.1 Submit one task#

OpenClaw should call the bundled GeodeCLI:

bash

"/Applications/Geode.app/Contents/Helpers/GeodeCLI" --enqueue-transcription \
  --audio "/Users/.../Library/Group Containers/group.com.privycloudless.privyecho/CLIInbox/audio.m4a" \
  --language zh \
  [--format txt|md|docx] [--summary]

GeodeCLI auto-detects the enclosing Geode.app and launches Geode --worker automatically.

Only during development or non-default installs, you may need:

bash

"/path/to/GeodeCLI" --enqueue-transcription \
  --audio "/Users/.../CLIInbox/audio.m4a" \
  --language zh \
  --app-bundle "/path/to/Geode.app"

Behavior:

• Async mode accepts exactly one --audio per task.
• GeodeCLI persists a task JSON file into the App Group container.
• GeodeCLI launches Geode --worker and returns immediately.

2.2 Success output#

• stdout: TASK_ID=<uuid>
• exit code: 0

Example:

text

TASK_ID=123e4567-e89b-12d3-a456-426614174000

2.3 Error output#

• stderr: Error: <CODE> plus optional English detail lines
• Exit code:
  • 1: runtime error
  • 2: invalid arguments

Common async-specific codes:

• TASK_CREATE_FAILED
• TASK_READ_FAILED
• WORKER_LAUNCH_FAILED

---

3. Query Status#

After receiving a task id, OpenClaw should poll:

bash

"/Applications/Geode.app/Contents/Helpers/GeodeCLI" --task-status 123e4567-e89b-12d3-a456-426614174000

3.1 Success output#

• stdout: one JSON object
• Exit code: 0

Example:

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "recordingId": "6a9b17c5-6c9d-4f0b-8401-f0d7f06a5e48",
  "audioPath": "/Users/.../Library/Group Containers/group.com.privycloudless.privyecho/CLIInbox/audio.m4a",
  "language": "zh",
  "outputFormat": "txt",
  "summarize": true,
  "status": "summarizing",
  "transcriptPath": "/Users/.../Library/Group Containers/group.com.privycloudless.privyecho/CLITranscriptions/audio_2026-03-18T07-00-00Z.txt",
  "summaryPath": null,
  "errorCode": null,
  "errorDetail": null,
  "workerId": "pid-12345",
  "createdAt": "2026-03-18T07:00:00Z",
  "updatedAt": "2026-03-18T07:02:10Z",
  "startedAt": "2026-03-18T07:00:02Z",
  "finishedAt": null
}

3.2 Status values#

StatusMeaningqueuedTask is persisted and waiting for a worker.runningTranscription is in progress.summarizingTranscript is written; AI summary is still running.succeededTask completed successfully.failedTask failed. Check errorCode / errorDetail.cancelledReserved for future use.

3.3 Task status error#

• stderr: Error: TASK_NOT_FOUND
• Exit code: 1

---

4. Common Error Codes#

These codes may appear in task status JSON:

CodeMeaningINVALID_ARGSMissing required arguments or invalid usage.AUDIO_NOT_FOUNDAudio file does not exist.AUDIO_UNREADABLEAudio file cannot be opened.NOT_LOGGED_INUser is not logged in to Geode.INSUFFICIENT_QUOTANot enough transcription quota.EMPTY_RESULTTranscription returned no text.OUTPUT_DIR_CREATE_FAILEDFailed to create the output directory.OUTPUT_WRITE_FAILEDFailed to write an output file.TRANSCRIPTION_FAILEDInternal transcription failure.SUMMARY_NOT_LOGGED_INUser is not logged in for AI summary.SUMMARY_INSUFFICIENT_QUOTANot enough AI summary quota.SUMMARY_FAILEDAI summary generation failed.WORKER_INTERRUPTEDThe worker stopped before finishing the task.

---

5. Recommended Workflow#

When the user wants to transcribe an audio file and later retrieve the result:

1. Copy the source audio into: ~/Library/Group Containers/group.com.privycloudless.privyecho/CLIInbox/

2. Call: /Applications/Geode.app/Contents/Helpers/GeodeCLI --enqueue-transcription --audio "P" --language <lang> [--format ...] [--summary]

3. Read TASK_ID=<uuid> from stdout.

4. Poll: /Applications/Geode.app/Contents/Helpers/GeodeCLI --task-status <uuid>

5. When status becomes succeeded:

   • read transcriptPath
   • read optional summaryPath
   • copy result files to the user-requested destination if needed

6. When status becomes failed:

   • use errorCode for branching logic
   • use errorDetail for logs or user-facing context

Recommended polling behavior:

• first poll after 1 to 2 seconds
• then every 2 to 5 seconds
• stop polling when status is succeeded, failed, or cancelled

6. Summary#

• OpenClaw should call the bundled GeodeCLI inside Geode.app for async submission and status polling.
• GeodeCLI returns TASK_ID=<uuid> immediately.
• Geode.app performs the actual transcription in --worker mode.
• Audio, task JSON, transcript, and summary files all live in the shared App Group container.

7. Agent Instructions#

• This skill is designed for asynchronous transcription. Tasks may take a long time to complete.

Submission behavior#

• When the user requests audio transcription, use --enqueue-transcription to submit a task.
• Always return the TASK_ID immediately after submission.
• Do NOT wait for transcription to finish (non-blocking behavior).
• After submission, allow the conversation to continue normally.

Progress & retrieval#

• Only check task status when:
  • the user explicitly asks for progress or results, OR
  • you proactively decide to check in the background (without blocking the user conversation).
• Poll task status using --task-status <TASK_ID>.

While task is running#

• If the task is still in queued, running, or summarizing:

  • Inform the user that the task is still in progress.
  • Suggest checking again later.
  • Do NOT block or repeatedly poll in a tight loop.

Completion#

• When status is succeeded:

  • Return the transcriptPath.
  • Return summaryPath if available.

Failure handling#

• When status is failed:

  • Explain the failure using errorCode.
  • Include errorDetail if available.
  • Suggest corrective actions if applicable (e.g., login, quota, file issues).

Environment handling#

• If the Geode app is not installed:
  • Guide the user to install it from the App Store before retrying.