---
name: completion-pet
description: Open Motchi, a transparent dog popup at the primary Mac screen’s top right with automatic local task tracking, project progress, reliable project answers, direct Codex clarification replies, real approval replies through trusted PermissionRequest hooks and tasks started in Motchi, and desktop approval alerts. Use for Progress Dog desktop interaction or its secondary Codex question window.
---

Use `scripts/completion_pet.py` relative to this skill directory. Requires macOS, Python 3.9+, and Apple's Swift tools for the first build. Project discovery and read-only companion answers use the installed Codex CLI and its existing sign-in/provider. Only a dog is supported.

Resolve the user's actual project directory. Keep its agreed checklist accurate with the sibling `progress-pet` skill; never invent completed work. Prepare the native companion:

```sh
python3 /absolute/path/to/completion-pet/scripts/completion_pet.py --project /absolute/project --prepare-app --replace --report-on-start
```

Open the exact returned app with an available native launcher. One hub handles local projects. `--replace` replaces older Progress Dog watchers. Existing desktop Codex chats are unaffected. Finish or stop any task started through Motchi before restarting/updating the companion: its live approval connection closes with the app. Confirm startup in the app's sibling `events.log`: `Progress Dog hub watching:` and `Local project and chat bridge started.` Check this log before retrying a launch after a window-inspection error.

## Secondary Codex questions

When the user is using Motchi for a project, use this plugin's available `mochi.ask_user` MCP tool for ordinary project clarification. Supply the absolute `project_path`, descriptive `project_name`, question, and optional short choices. Supply `thread_id` only if the real current chat UUID is known; never guess it. The dog appears, displays the question, and sends the user's typed reply or selected choice back to the exact Codex run that called the tool.

A `waitingForReply` result is not an answer. Continue with `mochi.wait_for_reply` using the returned `question_id`; do not guess, continue dependent work, create duplicate questions, or say the user answered. Each wait is under the default Codex tool timeout, with a nine-minute total question expiry. Cancellation/expiry returns an explicit error. Closing the popup dismisses the view and leaves the question pending. The user can reopen it with the shortcut. If the MCP tool is unavailable, use Codex's normal question interface and explain that a new session may be needed to load the updated plugin.

For existing desktop Codex chats, trusted synchronous `PermissionRequest` hooks can deliver real Allow/Deny choices in Motchi. Only a live waiting hook supplies these buttons; log-only and unsupported native cards remain in Codex. For tasks explicitly started with **Start Codex task** in Motchi, the live app-server connection supports real Allow/Deny replies. Never route permission decisions through the ordinary clarification tool or interpret chat text as approval. Authentication and unsupported approval types remain in their native interface.

The popup's normal **Ask** mode remains a separate ephemeral, read-only companion conversation. **Reply** mode appears only for a pending question actually issued through the Motchi MCP tool. It returns a real tool result to the originating run. Do not describe Ask mode as a way to steer an arbitrary existing desktop chat. Codex does not expose a supported universal takeover of all existing desktop prompts to this plugin.

## Real Codex approvals

Click **Start Codex task**, describe the work, then **Start task ↑**. This starts a separate Codex chat in the selected project with workspace-write sandboxing and on-request, user-reviewed approvals. It uses the existing Codex provider/sign-in/model. It does not take over, resume or duplicate an arbitrary ongoing desktop chat. The new chat can be opened in Codex through its real thread link.

For a live connected request, Motchi displays the exact requested scope/command with **Allow once**, **Deny**, and **Ask about this request**. Only offered decisions are shown. Permission grants return only the captured requested subset with turn scope; command/file replies use the actual app-server approval protocol. Session grants and always-allow rules are not added. Requests are bound to the original connection, RPC ID, thread, turn and item; stale or disconnected IDs cannot be used. An explanation is a separate read-only context conversation. It never sends a decision or unpauses the task. Typing yes does not approve: use the explicit button. If the request resolves while an explanation is being answered, that answer is marked as no longer pending.

**Add work to Codex** adds a checklist item and sends additional instructions to an active or idle Motchi-controlled chat. Active delivery uses the exact `expectedTurnId`; it never falls back to another turn on rejection. Idle/disconnected owned chats explicitly start/resume their own follow-up. Resolve a pending approval/question first; confirmed unsent work offers Send saved task. Uncertain deliveries cannot be retried blindly. Similar additions ask Same task / Different task / Skip before sending. **Ask Motchi** is the read-only companion mode. **Stop task** interrupts the exact connected turn and invalidates pending decisions. Ordinary built-in question prompts on this same live connection accept replies in Motchi too. Unsupported/secret prompts are not represented as approval buttons. A connection loss invalidates all pending decisions; restart does not restore approval IDs or automatically resume work. Selecting a disconnected Motchi-owned task and explicitly sending a new instruction resumes its saved history. Do not start another client on the same chat while a Motchi task is active.

The owned app-server integration handles tasks started through Motchi. Existing chats can also return decisions through the separate trusted synchronous permission hook described below. Native `request_permissions` cards bypass that hook; they remain **Review in Codex** alerts unless Codex actually supplies a live hook request. Do not promise universal approval interception or add synthetic Allow/Deny buttons to log-only alerts. No hook trust changes or global approval-policy changes are required for the live connection. The installed CLI currently gates native permission requests behind its under-development `request_permissions_tool` flag; Motchi enables it only for its own app-server process. Command/file approvals use their normal protocol. Keep Motchi open while its tasks work; quitting disconnects them. The controller’s local registry retains chat IDs/project metadata, not pending permission arguments or commands.

## Existing-chat permission replies (0.11)

Motchi's registered user `PermissionRequest` command invokes `dog_bridge.py --permission-hook` with a 600-second Codex timeout. While Motchi is running, it waits up to nine minutes for **Allow once** or **Deny** and returns `hookSpecificOutput` / `PermissionRequest` / `decision.behavior` from the original hook invocation. This is a real decision route, not a notification or a new chat. User dismissal and asking questions never send a decision. Only explicitly clicked buttons decide; typed yes is not interpreted as permission.

Codex requires one-time user review of the exact changed hook definition via `/hooks`; install/update does not grant trust. Prepare and install the reviewable plugin first. Then ask the user to review/trust it and reload the relevant session. Never write trust records or use a trust bypass. The original request may need to be reissued after activation; a hook cannot take over an already displayed card retroactively.

Officially documented hook paths include shell escalation, apply_patch, MCP approvals, and managed-network approval. A live test confirmed the core built-in `request_permissions` request bypasses PermissionRequest hooks. This desktop app's separate `functions.request_permissions` filesystem/network card also has no reply bridge in this integration. Do not promise these native cards are answerable through the hook. Log-only cards never gain synthetic Allow/Deny buttons.

A live OS lock and unique request ID bind replies to the original session/turn/call. Full tool input is shown as plain text for review. **Ask about this request** uses a separate read-only context and leaves the original paused. Cancellation, expiry, dead hook, missing companion, and duplicate/stale replies cannot grant access. Native Codex approval remains the fallback when a hook declines to decide. Temporary request details are removed after expiry/delivery and a short acknowledgement period. No always-allow rules are created.

## Automatic checklist

Open **Project checklist** to see and edit the boxes. The progress ring uses completed / total project tasks. **＋ Checklist task** adds an item without sending work. **Add work to Codex** saves a task and sends its full instructions into the selected Motchi-owned chat: `turn/steer` targets the exact active turn, or `turn/start` starts a follow-up in the same idle chat. If that turn ends before steering is accepted, Motchi does not silently send it to another turn. Timeouts are marked uncertain and never retried automatically. Existing desktop-only chats support checklist edits and **Open in Codex**, but cannot receive injected prompts on this installation.

Similar additions pause with **Same task**, **Different task**, or **Skip**. Same reuses the existing ID and reopens a completed item when the user is adding work. Different adds a separate item. Only explicit additional-work submissions deliver prompts; automatic checklist inference never instructs Codex to execute something. Pending approvals/questions must be answered before more work is sent. A confirmed unsent prompt stays in the checklist panel with **Send saved task**; uncertain deliveries must be checked in Codex.

Motchi reconciles recorded Codex plans and the recent visible chat history in each local project. Structured plans update immediately; a background read-only Codex extraction handles conversational tasks and semantic similarity using the existing provider/sign-in. Normal model usage applies. It coalesces unchanged histories, uses one background worker, and limits each project to one attempt per minute. It reads up to 24 recent messages per chat and 32 messages per project batch; it does not claim to reconstruct arbitrarily old or unavailable history. Reasoning and general tool outputs are excluded. Model failure leaves recorded plans and manual edits available, with a visible sync notice.

Completion needs an explicit completed plan step or a matching assistant statement confirming that task finished. Intentions, silence and turn completion do not check boxes. Historical finished work can be reconstructed with its completion evidence. Manually checked/unchecked boxes are preserved against automatic changes. Task evidence can be viewed by hovering its title. Similar automatic proposals ask before merging. Checklist IDs, decisions, evidence snippets and delivery state persist under `.progress-pet.json`; full transcripts remain in memory. Plan steps retain their own source identities so polling cannot create duplicates. Store locking and revision checks coordinate the companion, CLI and browser checklist.

## Appearance and interaction

Double right-click beside any Mac app to open Motchi at the primary screen’s top-right corner. Popup positions never use the cursor location. The native window and page canvas are transparent, with no solid enclosing panel. A ground line appears first. For interactive chat, the dog leaps from its corner ground line, lands with a soft squash and settles into a sit over 1.42 seconds; chat cards begin appearing at 1.48 seconds. A newly observed working turn gets a compact dog-and-message notification at the top right of the primary display, “I’m tracking the progress of [project]”, then the dog fades into its ground line. All automatic announcements, permission/question prompts, returned answers and completion celebrations appear at the top right of the primary display. Manual shortcut chat also opens at the primary display’s top right. Tracking announcements use a 280 ms entrance, begin fading at 1.3 seconds, and close at 1.5 seconds total. The timer starts after the page is ready and the window is shown, rather than during loading. Opening chat or receiving an attention alert cancels the notification’s dismissal timer. Reduce Motion shows the controls directly. The preview server uses a checkerboard only to demonstrate transparent space; the desktop has no checkerboard.

Click outside, the non-interactive background/dog, the close button, or Escape while typing inside to dismiss. Chat fades first, then the dog crouches and hops into its ground line and the ground line retracts; the native window closes after 780 ms. Reopening during this animation cancels the old close timer. Reduce Motion dismisses immediately. Picker, messages, questions, options, and reply controls remain interactive. Opening does not steal keyboard focus; clicking the reply box enables typing. Original right-click events continue to the underlying app, so its context menu can also appear.

**Auto** follows the latest working local chat by default, with pending questions/approvals taking priority. This follows recorded activity; it does not inspect which Codex window is focused. Mention an exact project/chat title in a question (for example, “what has World Trigger done?”) to route the answer automatically. Replies and drafts remain attached to their project. A conversation stays on its topic until a newly observed task starts. A picker change pins a project; Auto resumes following. Drafts and in-flight answers prevent routine automatic selection changes. New permission/question alerts take priority, saving the previous project’s draft and preserving in-flight answers.

The supported app-server catalog supplies up to 100 recent non-archived local chats. Motchi reads explicit lifecycle events, visible assistant messages, update_plan steps, and recognized built-in user-input requests from each catalog-provided local session log. Paths must be inside Codex's sessions directory and metadata must match the chat. It ignores reasoning and general command arguments/results. Recognized native permission calls retain only the reason and requested scope; known permission execution results use their status header and routing identity only. For recognized question tools it reads only question text/options and call IDs; synchronous result IDs or structured async user replies clear the matching request. An async delivery acknowledgement is not an answer. This is a read-only compatibility adapter for Codex's version-dependent log format, with hook-connected projects as a fallback. Missing/unrecognized logs remain unknown. It never resumes, writes to, or steers an existing chat. Remote/cloud-only work is not covered. Catalog refreshes about every fifteen seconds; local activity every two seconds. Keep the companion running while Codex works.

Progress and “what has been done?” questions use the checklist, current task plan and recorded assistant updates locally, including when no percentage is available. Other companion questions use a separate ephemeral read-only model run; final results return without waiting for CLI shutdown. A provider error or delay returns an explicitly labeled recorded-update fallback. Dismissing while an Ask request is pending does not cancel it. When its answer or error arrives, Motchi reopens the correct project conversation at the top right, including if the dismissal animation is still running. Returned answer dialogs stay open for reading; permission/question prompts stay open for user input. Existing visible conversations keep their answers in place. A pending permission/question has priority over a returned answer. This side conversation does not submit changes to the original chat.

The ring uses actual completed tasks / total tasks from the shared project checklist. Recorded plans now seed and reconcile checklist items; a plan is used as a fallback only when the checklist is unavailable or empty. Plan progress is labeled **Current task plan** and is never treated as whole-project completion. Missing plans/checklists do not imply zero or 100 percent. Follow the agreed checklist for project scope; do not invent tasks or mark work complete merely because a turn stopped. Checklist completion celebrations are watched across local projects, not just the selected one.

## Attention alerts

Codex requires user review/trust of exact non-managed hook definitions; installation alone does not grant trust. Direct the user to `/hooks` in the Codex CLI, review/trust the Motchi user permission hook, and start/reload sessions. Never write trust hashes or bypass review.

Trusted observer hooks detect supported `request_user_input` / `request_user_input_async` tool calls via `PreToolUse`, and final assistant messages ending in a question via `Stop`. Recognized built-in user-input calls in validated local session logs also alert without hook trust. These sources open the named project's popup with **Open Codex to reply** or **Review in Codex**. They do not provide a generic reply bridge for built-in requests. Tool completion, user follow-up, interruption, and session endings clear relevant attention events. Not every natural-language question or remote workflow produces these signals. Only newly seen pending events trigger a popup; dismissing does not repeatedly reopen the same request.

Native filesystem/network access cards (`request_permissions`, including “Allow ChatGPT to edit the contents of …?”) are also observed from validated local logs without hook trust. Show the reason/scope and **Review in Codex**, keeping the actual Allow/Deny decision in Codex. For this read-only adapter, issue the permission tool directly when available; if it must be wrapped in `functions.exec`, use one standalone `text(await tools.request_permissions({...}));` call with literal arguments and double-quoted strings. Do not combine it with unrelated statements or hide arguments in variables. This narrow parser never evaluates code; arbitrary wrappers and remote/cloud-only requests are not supported. Matching permission results or the associated completed exec/wait clear the alert; a running-cell acknowledgement does not. Task completion/interruption clears outstanding permissions. Dismissing a pending alert hides its view without choosing a decision.

Observer hooks (`--hook`) always return `{}`. The dedicated synchronous `--permission-hook` returns the documented allow/deny decision only after an explicit Motchi button choice for its original waiting request. No trust hashes or policy changes are made. Local temporary records contain question text/options, project/session IDs, activity and short approval reasons; they do not copy full transcripts, commands or credentials. The direct MCP question channel works independently of hook trust once loaded and enabled by Codex.

When any observed local project's nonempty checklist finishes, the existing dog celebration pulls out from its ground line at the primary screen’s top right over 350 ms with its project name. The “[project name] is done!” announcement lasts 1.5 seconds total, including its entrance and final 200 ms fade. Reduce Motion hides at 1.5 seconds. `--duration` overrides the total announcement lifetime, not a separate hold. Interactive answers and permission/question dialogs stay open for reading and input. Celebrations wait while questions, permissions, another celebration, or a chat are open. `.progress-pet-completion.json` suppresses repeats; an incomplete checklist rearms the next completion. Only shortcut button events sample pointer location; popup placement is fixed to the primary screen. No global keystrokes or cursor movements are recorded.

The dog menu opens/hides the dialog, toggles the shortcut, previews completion, or quits. The normal app build creates no login item. The optional `install_autolaunch.py --install --login-app --app /absolute/Motchi.app` installs a stable Motchi Launcher app; register it in macOS Open at Login only when the user requests automatic startup. It watches Codex desktop opening, preserves an existing companion, and respects manual Motchi quit until Codex reopens. Disable it by removing Motchi Launcher from Open at Login. `--report` opens the running hub, `--stop` stops it and requests shutdown of the current project's legacy watcher. `--preview` shows one labeled completion demo and exits; `--preview-on-start` previews then watches. Previewing never changes tasks or consumes completion. If Swift/Codex is missing, report the prerequisite rather than installing it automatically.

### User hook registration

Run `python3 /absolute/installed/plugin/skills/completion-pet/scripts/install_approval_hook.py` once after updating the plugin. It merges the dedicated synchronous PermissionRequest command into `~/.codex/hooks.json`, preserving other hooks and backing up an existing file. It never trusts hooks or alters approval policy. This registration is necessary on installations where the CLI does not discover bundled plugin hooks. The plugin bundle intentionally omits PermissionRequest to avoid duplicate handlers. Review the exact user hook in `/hooks`; non-permission bundled hooks are observation only.

### Verified activation

On 2026-10-22, Codex reported the installed user PermissionRequest hook trusted and enabled. A real shell escalation request reached Motchi; its Deny decision was returned by the original synchronous hook and the originating task resumed with DENIED_AND_RESUMED. A separate live built-in filesystem permission test did not invoke the hook and was denied through its owned app-server RPC. The two paths must not be conflated. No trust records were written by Motchi or the agent.