Cliplet

Cliplet is a lightweight desktop pet for Qoder and agent workflows. It keeps Codex Pets package compatibility, then adds a small foreground surface for agent status, user questions, new requirements, and Office orchestration.

The first product loop is intentionally narrow:

right-click Cliplet -> New Slides/Spreadsheet/DOCX/PDF -> Qoder new chat
  -> matching writing skill -> automatic Cliplet preview/result card

The generic assistant loop is:

right-click Cliplet -> New ACP Assistant... -> choose ACP client + prompt
  -> ACP stdio session -> desktop task cards on the pet

Cliplet is not an Office editor and does not vendor the Office stack. It owns the user-facing companion, local job contracts, and status replay. Office file generation stays in the writing skills, while rendering stays in office-canvas and Routa.

Highlights

• Desktop companion: transparent overlay, compact status badge, activity card, right-click actions, and a lightweight composer.
• Qoder-first provider: read-only status probing, visible AskUserQuestion answers, and new-chat deeplink submission.
• Office v1 orchestration: right-click actions create local jobs, ask Qoder to run slide, spreadsheets, docx, or pdf skills, and expose generated results.
• ACP assistant sessions: right-click action starts a standard ACP client and shows recent sessions as compact desktop task cards backed by $PET_HOME/acp.
• Codex Pets compatibility: validates pet packages, installs store pets, and keeps $pet skill workflows available.
• Open-source shape: MIT license, contribution guide, security policy, changelog, and CI checks.

Architecture

flowchart LR
  User["User"] --> Overlay["Cliplet overlay"]
  Overlay --> State["$PET_HOME state"]
  Overlay --> AcpRunner["acp_session_runner.js"]
  AcpRunner --> AcpClient["ACP client"]
  AcpRunner --> AcpSessions["$PET_HOME/acp/sessions"]
  Overlay --> Provider["Agent provider bridge"]
  Provider --> Qoder["Qoder new-chat deeplink"]
  Qoder --> Writer["Office writing skill"]
  Writer --> Artifact[".pptx / .xlsx / .docx / .pdf"]
  Artifact --> ClipletCli["@autodev/cliplet CLI"]
  Overlay --> ClipletCli
  ClipletCli --> Runner["office_action_runner.js"]
  Runner --> Jobs["$PET_HOME/office/jobs/<jobId>"]
  Runner --> CanvasSkill["office-canvas skill"]
  CanvasSkill --> Routa["Routa"]
  CanvasSkill --> Canvas["Canvas"]
  CanvasSkill --> Webview["Webview"]
  Jobs --> Overlay
  AcpSessions --> Overlay
  Canvas --> Overlay
  Webview --> Overlay

The design boundary is documented in:

• ADR 0008: Cliplet Office Orchestration
• ADR 0010: Cliplet Open Source Project Identity
• ADR 0011: Office Writing Skills And Automatic Preview
• ADR 0012: External Cliplet Runtime CLI
• ADR 0013: Desktop Pet ACP Assistant Sessions

Quick Start

Install and launch the default Clippy pet from the public store:

node .agents/skills/pet/scripts/codex_pets_store.js install \
  https://codex-pets.net/#/pets/clippit \
  --switch \
  --launch

Launch or update the overlay directly:

node .agents/skills/pet/scripts/cliplet_overlay.js clippit \
  --state waiting \
  --message "Needs input"

Show Qoder status in Cliplet:

node .agents/skills/pet/scripts/agent_status_probe.js --provider qoder --launch

Create a local Office slide job:

npx @autodev/cliplet office request \
  --action slide \
  --output-mode both \
  --prompt "Generate a roadmap deck"

Render an existing PPTX through the Office rendering stack:

npx @autodev/cliplet office webview <file.pptx> \
  --job-id cliplet-demo \
  --kind pptx \
  --open

Runtime Model

Cliplet stores runtime data under $PET_HOME, defaulting to $HOME/.pets.

$PET_HOME/config.json
$PET_HOME/pets/<pet-id>/
$PET_HOME/desktop/<pet-id>/state.json
$PET_HOME/integrations/qoder/status.json
$PET_HOME/office/jobs/<jobId>/
$PET_HOME/acp/requests/<requestId>.json
$PET_HOME/acp/sessions/<localSessionId>/

$CODEX_HOME/pets is only an interoperability fallback for existing Codex TUI pet packages. Desktop state, host installs, downloads, logs, and Office jobs belong under $PET_HOME.

Office Job Contract

Office jobs are file-based so Cliplet, Qoder, and the renderer can cooperate without sharing private process state.

$PET_HOME/office/jobs/<jobId>/request.json
$PET_HOME/office/jobs/<jobId>/progress.json
$PET_HOME/office/jobs/<jobId>/result.json

request.json describes the user request and render mode:

{
  "schemaVersion": 1,
  "source": "cliplet",
  "action": "slide",
  "kind": "pptx",
  "prompt": "Generate a roadmap deck",
  "outputMode": "both",
  "providerId": "qoder",
  "workspace": "/absolute/workspace",
  "resultPath": "/absolute/$PET_HOME/office/jobs/<jobId>/result.json"
}

progress.json uses queued, running, ready, or failed, with stages such as request, writing, canvas, webview, done, and error.

result.json records the generated file and render outputs:

{
  "status": "ready",
  "sourceFile": "/absolute/file.pptx",
  "canvasPath": "/absolute/file.canvas.tsx",
  "webviewUrl": "http://127.0.0.1:5173/",
  "serveCommand": "npm ...",
  "error": null
}

Qoder Boundary

Qoder integration is read-only toward Qoder storage. Cliplet may read sanitized status surfaces and open visible Qoder UI, but it must not:

• read Qoder auth contents;
• inspect raw request logs;
• write under .qoder;
• mutate Qoder SQLite databases;
• send Qoder IPC messages;
• change Qoder model settings;
• paste a new requirement into the current conversation as a fallback.

New requirements and Office prompts must open Qoder with:

qoder://aicoding.aicoding-deeplink/chat?...&isNewChat=true

For real end-to-end validation, confirm Qoder is using the user's intended visible model first. Model/account errors should not be treated as Cliplet bridge failures until that precondition is checked.

Repository Layout

• .codex-plugin/plugin.json: Codex plugin metadata for cliplet; plugin skill discovery points at .agents/skills/.
• package.json and bin/cliplet.js: npm package entry for @autodev/cliplet. The Electron host calls this external runtime instead of requiring copied Office runner code from the installed app bundle. Launcher state records the real Node binary so the host does not accidentally spawn Cliplet.app as the script runner.
• .agents/skills/slide, .agents/skills/spreadsheets, .agents/skills/docx, and .agents/skills/pdf: complete Office writing skills copied from the shared Office skill bundle, excluding local junk and dependency folders.
• .agents/skills/office-canvas: Office render wrapper for Canvas and Webview.
• .agents/skills/pet/SKILL.md: canonical Agent Skill instructions.
• .claude/skills/pet/SKILL.md: Claude Code /pet wrapper.
• .agents/skills/pet/scripts/cliplet_overlay.js: public overlay launcher.
• .agents/skills/pet/scripts/cliplet_office_runner.js: public Office runner alias.
• .agents/skills/pet/scripts/desktop_pet_overlay.js: legacy-compatible overlay launcher and host installer.
• .agents/skills/pet/scripts/agent_status_probe.js: provider status entry.
• .agents/skills/pet/scripts/qoder_status_probe.js: Qoder compatibility entry.
• .agents/skills/pet/scripts/acp_session_runner.js: standard ACP assistant runner and rolling stream state writer.
• .agents/skills/pet/scripts/office_action_runner.js: Office job runner.
• .agents/skills/pet/desktop-node/: Electron overlay host.
• .agents/skills/pet/references/: pet package and runtime references.
• docs/adr/: architecture decisions and constraints.

Development

Install Electron host dependencies only for local development:

npm --prefix .agents/skills/pet/desktop-node install

Normal users should install a prebuilt host from a GitHub Release. Runtime use must not require Xcode, swiftc, or npm.

Useful validation commands:

python3 -m py_compile .agents/skills/pet/scripts/*.py
node --check .agents/skills/pet/scripts/desktop_pet_overlay.js
node --check .agents/skills/pet/scripts/cliplet_overlay.js
node --check .agents/skills/pet/scripts/agent_status_probe.js
node --check .agents/skills/pet/scripts/qoder_status_probe.js
node --check .agents/skills/pet/scripts/acp_session_runner.js
node --check .agents/skills/pet/scripts/office_action_runner.js
node --check .agents/skills/pet/scripts/cliplet_office_runner.js
node --check .agents/skills/pet/desktop-node/acp_orchestration.js
node --check .agents/skills/pet/desktop-node/office_orchestration.js
node --check .agents/skills/pet/desktop-node/main.js
node --check .agents/skills/pet/desktop-node/renderer.js
node --test .agents/skills/pet/tests/*.test.js
python3 .agents/skills/pet/tests/test_qoder_pet_interaction.py
git diff --check

Open Source

• CONTRIBUTING.md: setup, validation, and contribution boundaries.
• SECURITY.md: security reporting and local-state handling.
• CHANGELOG.md: user-facing release notes.
• LICENSE: MIT license.

The public project name is Cliplet. The Agent Skill remains $pet, and legacy script names remain supported as compatibility entrypoints while documentation and releases move to the Cliplet identity.