Skip to content

feat(claude-code): 1.7.1, separate codex-delegate and session-handoff triggers #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brtkwr merged 1 commit into from
Oct 28, 2026
Merged

feat(claude-code): 1.7.1, separate codex-delegate and session-handoff triggers #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
{
"name": "agentic-utils-claude-code",
"description": "Skills grounded in Claude Code internals",
"version": "1.7.0",
"version": "1.7.1",
"source": "./plugins/claude-code",
"category": "utilities"
},
Expand Down
2 changes: 1 addition & 1 deletion plugins/claude-code/.claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "agentic-utils-claude-code",
"version": "1.7.0",
"version": "1.7.1",
"description": "Skills grounded in Claude Code internals: memory consolidation, memory writing, compaction checkpointing, bash safety, the Anthropic-employee prompt differences, session handoff, and delegating to the Codex CLI.",
"author": {
"name": "agentic-utils"
Expand Down
18 changes: 9 additions & 9 deletions plugins/claude-code/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ Seven skills grounded in Claude Code's source code. Each one surfaces an interna

## Skills

| Skill | Trigger phrases | Description |
| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [`dream`] | "dream", "consolidate memory", "clean up CLAUDE.md" | Consolidate and prune memory files using the 4-phase Orient/Gather/Consolidate/Prune algorithm |
| [`memory-writer`] | "write a memory", "add to CLAUDE.md", "update memory files" | Write memory entries that get selected. Covers description field scoring, staleness, index limits |
| [`compaction-prep`] | "prep for compaction", "checkpoint", "context is filling up" | Checkpoint mid-task state so the compacted session resumes exactly where it left off |
| [`bash-safety`] | "check this bash", "is this safe to run", "review this script" | Exit code semantics table plus dangerous pattern checklist |
| [`ant-mode`] | "enable ant mode", "use the Anthropic prompt" | Add the 5 Anthropic-employee prompt differences to your CLAUDE.md |
| [`session-handoff`] | "hand this off to another session", "hand this off to codex" | Launch a new Claude or codex session in a tmux window or iTerm tab with the brief attached; the child reports back to its parent |
| [`codex-delegate`] | "ask codex", "delegate to codex", "have codex review/research this" | Hand one task to `codex exec` (needs the Codex CLI): credit preflight, background-safe run, answer plus token usage, relay-only subagent |
| Skill | Trigger phrases | Description |
| ------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [`dream`] | "dream", "consolidate memory", "clean up CLAUDE.md" | Consolidate and prune memory files using the 4-phase Orient/Gather/Consolidate/Prune algorithm |
| [`memory-writer`] | "write a memory", "add to CLAUDE.md", "update memory files" | Write memory entries that get selected. Covers description field scoring, staleness, index limits |
| [`compaction-prep`] | "prep for compaction", "checkpoint", "context is filling up" | Checkpoint mid-task state so the compacted session resumes exactly where it left off |
| [`bash-safety`] | "check this bash", "is this safe to run", "review this script" | Exit code semantics table plus dangerous pattern checklist |
| [`ant-mode`] | "enable ant mode", "use the Anthropic prompt" | Add the 5 Anthropic-employee prompt differences to your CLAUDE.md |
| [`session-handoff`] | "hand this off to another session", "hand this off to codex" | Hand a tangent nobody here waits on to a new Claude or codex session in its own tab and worktree; the child reports back to its parent |
| [`codex-delegate`] | "ask codex", "get codex's take", "have codex review/research this" | Get an answer this conversation needs from `codex exec` (needs the Codex CLI): credit preflight, background-safe run, answer plus token usage |

## Install

Expand Down
6 changes: 5 additions & 1 deletion plugins/claude-code/skills/codex-delegate/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
---
name: codex-delegate
description: Delegate a self-contained task to the Codex CLI (`codex exec`) non-interactively and get back its answer and token usage. Covers the credit preflight, a background-safe invocation, read-only vs workspace-write sandbox, raising reasoning effort for adversarial review, web research, and relaying through a cheap subagent so the output stays out of the main context. Use when asked to "ask codex", "delegate to codex", "get a second opinion from codex", "have codex review this", "have codex research this", "run codex exec", or before spawning an in-session agent for work codex could do.
description: Get an answer from the Codex CLI (`codex exec`) that THIS conversation needs, such as a second opinion, a review of a diff or design, web research or a non-interactive edit. One headless run; the answer and token usage come back here. Covers the credit preflight, a background-safe invocation, sandbox and reasoning-effort choices, and relaying through a cheap subagent. Use when asked to "ask codex", "get codex's take", "get a second opinion from codex", "have codex review this", "have codex research this", "run codex exec", or, when codex is installed, before spawning a Claude subagent for self-contained work codex could do. For separate work codex should carry on in its own tab, use session-handoff instead.
---

# Delegate to Codex

Hand one self-contained task to `codex exec` and get back a single answer plus its token usage. Good fits: a second model's view on a design or diff, an adversarial review, web research, and non-interactive edits you want off your own quota.

**Which skill.** Use this one when this conversation waits for the answer. Separate work that ends in its own result (a branch, a PR, a fix in another repo), which codex should carry on in its own tab, goes to `session-handoff` instead. "Have codex do X" means this skill for a question, review or research, and `session-handoff` for implementation that ends in its own PR.

**When not to.** If the task needs this conversation's context, use a fork. If it needs a Claude-only tool or MCP server, use a Claude subagent.

Needs the [Codex CLI](https://github.com/openai/codex) installed and logged in. If `codex` isn't on `PATH`, this skill doesn't apply: do the work in-session and don't install codex unasked. The preflight below checks for it.

## Step 1: Preflight
Expand Down
14 changes: 12 additions & 2 deletions plugins/claude-code/skills/session-handoff/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: session-handoff
description: Hand a task to a NEW local Claude Code session (or an interactive Codex CLI session) in its own tmux window or iTerm tab (detected automatically), with the brief attached as its first turn so the child hands its leftovers back (Claude via SendMessage, codex via a watched handback file) and the parent then closes it and cleans up what it left behind. Only for a clear tangent; work that feeds the current task goes to a subagent. Use when asked to "hand this off to another session", "hand this off to codex", "launch a new claude session", "spin up a tab for this", "open a tmux window for this", "new session for X", "start a session to do Y", or "handoff".
description: Hand a clear tangent to a NEW local session, Claude Code or an interactive Codex CLI, in its own tmux window or iTerm tab (detected automatically) and worktree. The brief is its first turn; the child hands back its leftovers (Claude via SendMessage, codex via a watched handback file) and the parent closes it and cleans up what it left behind. Only for work nobody here waits on; an answer this conversation needs goes to a subagent, or to codex-delegate for codex. Use when asked to "hand this off to another session", "hand this off to codex", "open a codex tab for this", "launch a new claude session", "spin up a tab for this", "open a tmux window for this", "new session for X", "start a session to do Y", or "handoff".
---

# Session Handoff
Expand All @@ -9,7 +9,9 @@ Start a new Claude Code session in its own tmux window or iTerm tab with the bri

## When to use it

Only for a clear tangent: work that is independent of the current task, would derail this session, and ends in its own result (a separate PR, a fix in another repo) that nobody here waits on. Otherwise use a regular subagent (the Agent tool, or a fork): research, reviews, and anything whose answer this session needs to continue. A subagent reports straight back into this conversation and needs no tab, trust dialog or cleanup.
Only for a clear tangent: work that is independent of the current task, would derail this session, and ends in its own result (a separate PR, a fix in another repo) that nobody here waits on. Otherwise use a regular subagent (the Agent tool, or a fork): research, reviews, and anything whose answer this session needs to continue. A subagent reports straight back into this conversation and needs no tab, trust dialog or cleanup. The same split applies to codex: an answer you need now goes to the `codex-delegate` skill, and separate work codex carries on in its own tab comes here.

The test: will this conversation wait for the result? Yes means a subagent or `codex-delegate`. No means a handoff.

## Step 1: Find your own name

Expand Down Expand Up @@ -160,6 +162,14 @@ When done or blocked, hand back and stop:

Spell `<S>` out as an absolute path in the brief: codex doesn't expand `~` in prose.

**Preflight.** Check codex is installed and has usage left before opening the tab. Otherwise the child fails in a tab nobody is watching and never writes a handback:

```bash
${CLAUDE_SKILL_DIR}/../codex-delegate/codex-credit # exit 0 go; 1 no usage left; 2 not installed or check failed
```

On 1 or 2, don't launch. Tell the user, or hand off to a Claude session instead. Never spend a free rate-limit reset without asking.

**Launcher.**

```bash
Expand Down
Loading