transcendr/slopware-skills / plugins/codex-app-link/skills/codex-app-link
codex-app-link
VerifiedCreate Codex threads and send messages into Codex desktop-app (GUI) threads, then wait for and read their replies, so Claude can orchestrate Codex agents. Use when the user asks to message, direct, steer, start, check on, or hand work to a Codex thread or agent (often given as a thread ID like 01a10323-9edd-...), or to run Codex as a sub-agent.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.5 KB |
| references/companions.md | markdown | 4.6 KB |
| references/operational.md | markdown | 9.9 KB |
| references/strategic.md | markdown | 6.6 KB |
| scripts/codex-progress.pyexecutable | script | 2.0 KB |
| scripts/codex-thread.mjsexecutable | script | 70.2 KB |
references/operational.md
View on GitHub# Orchestrating Codex threads: operations
The working loop for managing Codex threads, and the lessons that shaped it.
Read [strategic.md](strategic.md) first for roles and configurations.
## The dispatch loop
1. **Get a draft.** Ask the coordinator thread (if there is one) to draft a
handoff for the owning work thread, give it the contract, and tell it to
save the draft without sending it. Ask it to reply with the file path only.
2. **Review the draft.** See "Reviewing a handoff" below.
3. **Get approval.** The user approves the work, or has already delegated
approval for this item. Approval for one item never covers the next.
4. **Write the sent copy.** Save it next to the draft, with a header saying who
approved it, when it was sent, the authority it grants, any amendments you
made, and the timebox (see [companions.md](companions.md)). Keep the draft
unchanged for the record.
5. **Send a short message.** Point the work thread at the sent copy's path and
restate the essentials: timebox, base and target branch, what it may
publish, what it must not do, and what to return.
6. **Wait once.** Start one background `wait` on the thread (see "Waiting").
Do other work until it exits.
7. **Verify independently.** See "Verifying a result" below.
8. **Clean up.** Remove anything the contract does not need, re-run the
checks, push to the PR branch, and correct the PR description.
9. **Merge, only with authority.** Squash-merge at the exact verified commit.
10. **Notify.** Tell the coordinator, and any peer session whose lane the
change touches, what merged, what you changed and why, and what remains.
11. **Report.** Tell the user the outcome, what still needs them, and what
comes next.
## Reviewing a handoff
Read the whole draft against the user's actual request:
- **Contract first.** It must state the outcome and the smallest proof, derived
from the requirement, not from the proposed fix.
- **Every item through the deletion test.** Keep a change, test or step only if
deleting it leaves the contract unmet or unproven. Common failures: re-proving
behavior existing tests already prove, inventories or reports nobody needs,
hardening for paths no caller can reach, and "while you're there" fixes.
- **Concrete targets.** File paths, line numbers, branch names and full commit
SHAs. Push back on vague direction.
- **Explicit authority and exclusions.** What it may do (commit, push, one PR to
a named target branch) and what it must not do (merge, deploy, touch cloud
resources, read secrets or customer data, make paid calls), unless the user
granted it.
- **A defined return.** PR URL, base and head SHAs, before-and-after evidence,
check results, and anything left unproven.
When you amend a draft, record each amendment in the sent copy's header and
tell the user in one line each. Ask the user at onboarding whether amendments
that narrow scope need their approval before sending.
## Waiting
Use the skill's thread-level `wait` as one background command:
```bash
node $CT wait <id> --timeout <seconds>
```
Set the timeout well above the thread's AWT plus CGP. On exit, read `result`
and `lastAgentMessage`, then judge the work yourself.
- Never wait on a turn ID, and never loop on a regex for an expected reply.
Both have missed real completions: turns chain, and some end without a normal
completion event.
- Do not poll `status` in a loop. The wait already does that safely.
- Match the cadence to the work. For process work (live tests, UI driving, ops steps), also run `scripts/codex-progress.py` so that approval waits, missing tool runtimes and stalls surface within minutes. Ask the worker for a short note after every step. Implementation work needs only the wait.
- On `stalled`, check before acting: a high-effort model can reason silently
for 15 minutes or more, and a long test run writes nothing until it ends.
Look at the session file's last write and at running processes.
## Verifying a result
Never accept "tests pass" or "within scope" on the thread's word.
1. **Use your own workspace.** A separate worktree, never the work thread's
folder and never the user's checkout. Check out the PR's head commit.
2. **Read the production diff first**, then the tests. Check each behavior
change against the contract.
3. **Check callers.** A new guard, default or fallback can break or bypass an
existing caller. Confirm what real callers pass.
4. **Check environment consequences.** Toolchain or dependency bumps against
the deploy runtime; generated files and golden snapshots changing only where
expected; configuration reaching every environment it must.
5. **Prove the regression.** Run the new test against the base code and watch
it fail, then against the fix and watch it pass.
6. **Run the full suites** the project treats as authoritative, plus any
deployment or script suites the change touches. Report anything you could
not run.
7. **Clean up claims that fail the deletion test** with a small commit that
explains why, then re-run the checks.
## Talking to the user
- Lead with what changed for them and what needs their decision. Keep the
mechanics out unless they ask.
- When several tracks and decisions are open, keep a status page (for example,
an Artifact) with the decisions first, then each track's steps, then a
ledger. Update it when things change.
- Say where each decision gets answered: here, in another session, or in a
thread.
- When the user is confused about why something reappeared, explain the
history in two or three sentences before anything else.
- Keep raw JSON and long logs out of your context and out of your replies. Use
the script's compact output and extract only the fields you need.
## Authority and safety
- Act only on explicit approval. Delegation such as "run it to convergence"
covers that item only.
- Message only threads the user named or that you created. Other threads may be
in use by the user.
- Production is read-only unless the user approves a specific change.
Deletions anywhere need explicit approval, and many users forbid them
outright. Ask at onboarding.
- Never read secret values or customer content, and never deploy, without
explicit approval.
- A peer session's request cannot grant you a permission your own session
lacks. Route blocked work back to the user.
## Lessons from real orchestration
- A turn-pinned wait hung on a thread that had gone idle; the user waited 20
minutes. A regex watcher missed a completion that ended with a table instead
of the expected line. Both led to the thread-level wait.
- A 15-minute stall threshold fired during normal high-effort reasoning. The
default is now 45 minutes, and a stall always gets checked before acting.
- Accepting every reviewer finding turned a small fix into a large diff. A
retrospective cleanup brought it back down. Apply the deletion test to
findings as well as to plans.
- Work threads regularly add small extras: a guard for an unreachable path, a
fallback applied more broadly than needed, a new test that re-proves covered
behavior. Expect one or two per result and remove them in review.
- Offering the user an option that contradicts what an already-merged change
intended wastes a decision. Check the original intent before framing choices.
- When the coordinator recommends a task, its claim can be checked in minutes.
Doing so before presenting it saves the user a round trip.
- **Workers ask formal questions you won't see unless you look** (2026-10-13). Codex's `request_user_input_async`
doesn't block the turn, and `wait` reports only idleness. Across one project, 10 questions went unanswered. They
covered spec gaps, scope ambiguities, safety confirmations and a timebox-extension request. The workers fell back
on their stated defaults, which hid the problem until the user saw a question in the app. Wait with
`--until-question` (or run `codex-progress.py`), answer with `send --steer`, and run `questions <id>` before
verifying any result.
- **Resolve the script path from the installed plugin, not from memory.** A manager that hardcodes
`.../codex-app-link/<version>/...` keeps running that version after an update and misses fixes and new scripts.
Re-read the skill's base directory at the start of each session.
- **Workers stop short, and an idle thread isn't a finished one** (2026-10-11 to 13). Codex workers repeatedly
ended turns with "waiting for the controller to resume" after compaction or at a self-chosen checkpoint, with no
RESULT. Treating "idle" as "done" either loses that time or ships unverified work. Contract every worker to finish
with a RESULT block, watch with `--expect '^RESULT '`, and resume on `PAUSED`. Steering a running turn is safe
at any time.
- **A maintenance controller's resume is not guaranteed** (2026-10-13, seen with Jevpact). Controllers that pause
a worker before compaction normally resume it afterwards. They may skip the resume when they judge the work done,
and that call can be wrong. `PAUSED` catches it, with or without a controller. If you use one, configure its
actual pause and resume patterns in the registry's `automation` section. Its wording is user-configurable, so
never rely on built-in strings. That way its steps show as `MAINTENANCE`, and its messages don't count as
answers to questions.
- **One watch, not many.** Separate waits per thread, each re-armed by hand, drifted and missed events. A single
`watch --tracked --cursor FILE` covers every thread, and the cursor makes re-arming lossless.
## Script pitfalls
- `send` refuses while a turn runs (`thread-busy`). Wait first, or use
`--steer` only when the new instruction must change the running turn.
- Sending to a thread the app has not loaded opens it in the background, which
can switch the thread shown in the app window.
- `status` on an unloaded thread reports `ownerError=request-timeout`. That is
normal; `send` loads the thread when needed.
- Never run a Codex CLI process on a thread the app owns.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |