codex-relay
Skill657 starsChanged 27 days agoMITView on GitHub
Open one new native Codex task with a compact handoff, end this turn, and receive a single completion or blocker message back. Use when the user invokes $codex-relay and asks to open a new task, optionally naming a model or reasoning effort.
In this repository4 other files it gives its agents.
- be-ambitiousSkill
- codex-dynamic-workflowsSkill
- explain-thisSkill
- modsmithSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
If any is missing, explain and stop.
- Very specific: line 34
Call create_thread. It returns a ready threadId plus hostId, or a pending clientThreadId.
- Very specific: line 35
If pending, make at most one list_threads setup check.
- Distinctive: line 40
If the callback arrives before this turn ends, handle it immediately.
- Distinctive: line 43
Verify results in the actual workspace, especially the right worktree.
- Very specific: line 44
No blind merge and no acknowledgment ping-pong.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Relay
Open one native Codex task, hand off a bounded job, end this turn, and verify the worker's callback. The invocation plus a request to open a task is the authorization; never create tasks otherwise.
Preconditions
If any is missing, explain and stop. Do not create an orphan, promise a wake-up you cannot deliver, or substitute a CLI, subagent, or automation.
create_threadandsend_message_to_threadare exposed.CODEX_THREAD_IDis non-empty (plus host if remote). Never derive it from the cwd or reuse a child ID.- The user named the task.
Model and effort
Use exactly what the user selected, handling the two independently: omit only the model field if no model was named, and only the thinking field if no effort was named, so each falls back to the configured default. If a model is unavailable, say so and ask; never substitute. Resolve ambiguity from tool metadata; ask only when material.
Workspace
Use list_projects to find the target when files are involved. Honor a user-specified branch, working-tree state, or saved checkout via the option create_thread supports; only when unspecified, default to a worktree for Git projects and local otherwise. A default worktree starts from the default branch without uncommitted changes; if a requested state is unsupported, say so rather than implying it was included. For projectless work, reference supplied accessible files.
Handoff brief
The worker inherits nothing from this conversation. Carry the full intent, minimum context, owned files and scope, exact paths and artifacts, workspace choice, required checks, authorization bounds, and the origin thread ID and host.
Embed worker instructions: do the bounded task only and create no further tasks. On completion send ONE message to the origin with your thread ID and host, outcome, actual workspace and artifact paths, checks with results, and limitations; if unable to proceed, send a blocker instead. End your turn after that message. The callback is an internal handoff, not publication.
Dispatch
- Call
create_thread. It returns a readythreadIdplushostId, or a pendingclientThreadId. Never pass aclientThreadIdto read, send, or wait tools. - If pending, make at most one
list_threadssetup check. Use an immediatewait_threadssnapshot only after a readythreadIdis known. If still pending, report setup pending, emit the returnedclientThreadIddirective, and end. Never guess or poll. - Say the task is dispatched, emit the native created-thread directive if required, and end.
Callback
If the callback arrives before this turn ends, handle it immediately; never add delay to manufacture an idle wake-up.
- Authenticate the sender by ready ID when known. Otherwise compare the worker's creation prompt (via
read_thread) against the actual handoff; a similar title is not enough. If unverifiable, say so and do not act. - Verify results in the actual workspace, especially the right worktree. Report claim versus verified success within the original scope.
- No blind merge and no acknowledgment ping-pong. A scoped correction within existing authorization may go through
send_message_to_thread, omitting model and thinking fields. - A duplicate callback repeats nothing and spawns no new worker.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

