简体中文 · GitHub

Codex Clean Up

Create a traceable handoff under the right Codex Project—without changing the source session.

Codex makes it easy to start a new task, but a new task can land in an unexpected or projectless location. This Skill turns that cleanup into a deliberate handoff: inspect the current topic, recommend a Project, and create a new summarized session there while leaving the original conversation intact.

What it does

• Reads the current session context and available Codex Projects.
• Compares the topic with Project names, roots, and recent session evidence.
• Shows only meaningful recommendations (60/100 minimum, up to three choices).
• Uses A/B/C/N selection for a fast decision.
• Treats the selected recommendation as the final confirmation—no second OK.
• Creates a new session under the selected Project using official Codex App tools.
• Carries forward a concise summary of goals, decisions, evidence, risks, and next steps.
• Names the handoff 迁移｜ for easy tracing.
• Keeps the source session, title, Project, and content unchanged.

A real run

These annotated screenshots document a real macOS V2 run, in execution order: diagnose the current placement, create and verify the handoff, then open the new Project-scoped session. Local filesystem paths are redacted in the public copies.

Historical note: this captured V2 run still displayed one extra OK step. The current Skill removes that step: a valid A/B/C choice directly executes the handoff.

01 — Diagnose and choose

02 — Create and verify

03 — Continue from the new session

Why a new session?

The Skill intentionally does not rewrite the source session's Project assignment. A new handoff session is easier to audit and recover:

source session ──diagnose──> A/B/C choice ──summary──> new session in target Project
       │                                                   │
       └────────────── original remains unchanged ─────────┘

This also avoids closing the App or editing private local state files.

Workflow

1. Diagnose — identify the current topic, title, Project, and available targets.
2. Recommend — show only candidates with evidence and uncertainty.
3. Choose — reply A, B, C, or N.
4. Handoff — the selection immediately creates the new Project-scoped session; there is no extra confirmation step.
5. Receipt — the original session reports the new title, Project, thread ID, and unchanged-source status.

Official tool boundary

The Skill uses Codex App capabilities:

• codex_app__list_projects
• codex_app__list_threads
• codex_app__create_thread
• codex_app__set_thread_title
• codex_app__read_thread

It does not edit .codex-global-state.json, SQLite databases, or other private App state. If the official creation capability is unavailable, it stops instead of falling back to an unsupported state mutation.

Install

The installed Skill directory should contain SKILL.md and references/handoff-template.md:

mkdir -p ~/.codex/skills
git clone https://github.com/manwithshit/CodexCleanUp.git ~/.codex/skills/CodexCleanUp

If the directory already exists, preserve it or back it up before replacing it.

Use

Trigger the Skill when a session may be in the wrong Project:

整理当前会话

or:

这个会话该放哪个 Project？

Choose the recommended letter. N cancels the handoff.

Repository layout

.
├── SKILL.md
├── references/
│   └── handoff-template.md
├── assets/readme/
│   ├── hero.svg
│   └── screenshots/
│       ├── 01-diagnose-and-choose.jpg
│       ├── 02-handoff-created.jpg
│       └── 03-new-session-receipt.jpg
└── dist/
    └── CodexCleanUp.skill

Scope and limits

• The Skill is for Codex local Projects; remote targets are used only when the current App tool explicitly supports them.
• ChatGPT cloud Projects are not selected by this Skill.
• It creates one handoff at a time.
• It does not delete, archive, fork, rename, or move the source session.
• Project recommendations are evidence-based, not a guarantee of semantic correctness.

中文文档

完整中文说明见 README.zh-CN.md。