Codexception

Codexception is a Codex-native skill for continuous learning: it helps Codex decide when a completed task produced reusable, verified knowledge, then codify that knowledge into future Codex skills.

Every time an AI coding agent starts a fresh session, it risks rediscovering the same local workflow, debugging trap, or tool integration detail. Codexception is a Codex-native fork of Claudeception that preserves verified, reusable knowledge as Codex skills.

It keeps the original package's explanation, examples, templates, and research notes, but uses Codex paths, Codex hooks, and Codex skill conventions.

Installation

User-level

Clone this repository into your Codex skills directory:

mkdir -p ~/.codex/skills
git clone https://github.com/whyy9527/codexception.git ~/.codex/skills/codexception

Project-level

For project-specific extraction rules, clone or copy the skill under:

.codex/skills/<skill-name>

Codexception itself is normally user-level because it governs skill extraction across sessions.

Activation Hook

The skill can activate via semantic matching, but a startup hook keeps the extraction check visible after meaningful work.

1. Copy or symlink the hook:

mkdir -p ~/.codex/hooks
cp ~/.codex/skills/codexception/scripts/codexception-activator.sh ~/.codex/hooks/
chmod +x ~/.codex/hooks/codexception-activator.sh

2. Register it in ~/.codex/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -lc 'exec \"$HOME/.codex/hooks/codexception-activator.sh\"'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

The hook emits structured JSON for Codex and injects a short reminder to evaluate whether the completed user request produced reusable knowledge.

Search Keywords

Codex, OpenAI Codex, Codex CLI, agent skills, SKILL.md, skill extraction, continuous learning, self-reflection, reusable debugging knowledge, session memory, SessionStart, hooks.json, additionalContext, default-deny .gitignore.

Aliases and trigger phrases include codexception, claudeception, claudexception, "write a skill", "save this as a skill", and "extract what we learned". See SEARCH.md for a compact search index.

Usage

Automatic Mode

Codexception should be considered after Codex:

• Debugs a non-obvious failure.
• Discovers a project-specific workflow, file path, or convention.
• Fixes an error where the message was misleading.
• Finds a tool integration gotcha through trial and error.
• Verifies a repeatable fix that future sessions should reuse.

Explicit Mode

Ask directly:

codexception

or:

Save what we just learned as a skill.

What Gets Extracted

Codexception is selective. It extracts only knowledge that is reusable, non-obvious, specific, and verified. Simple command output, generic documentation lookup, one-off facts, and unverified guesses do not become skills.

How It Works

Codex loads available skill names and descriptions, then retrieves relevant skills when the current task matches those descriptions. Codexception writes future retrieval targets by creating or updating focused SKILL.md files with precise trigger language.

The description matters. "Helps with hooks" is weak. "Fix Codex SessionStart hooks that emit plain text instead of structured JSON" is likely to surface when the same failure appears again.

Codex Skill Format

Extracted skills are markdown files with YAML frontmatter:

---
name: codex-hook-json-sessionstart
description: |
  Fix Codex SessionStart hooks that print plain text, invalid JSON, or reminders
  that do not enter model-visible context. Use when editing ~/.codex/hooks.json,
  ~/.codex/hooks/*.sh, or a skill-bundled hook script for Codex.
---

# Codex Hook JSON SessionStart

## Use When

[Exact hook symptom, file path, and trigger condition]

## Failure Mechanism

[Why the obvious or copied approach fails]

## Procedure

[Step-by-step hook fix]

## Verification

[JSON parse command and expected output]

## High-Risk Actions

[Actions that corrupt state, hide failure, or leave stale paths]

See resources/skill-template.md for the full template.

Quality Gates

Before creating or updating a skill, check:

• The future trigger is clear and specific.
• The lesson required real investigation or local context.
• The procedure is actionable without hidden context.
• Verification has happened, or residual risk is explicit.
• Dangerous actions are prohibited where relevant.
• No credentials, private absolute paths, machine names, or one-off incident details are baked into reusable instructions.

Examples

See examples/ for sample extracted skills:

• codex-hook-json-sessionstart/: fixing Codex hooks that emit plain text or invalid JSON
• codex-skill-rename-alias-preservation/: renaming a skill while preserving old trigger names
• codex-default-deny-skill-staging/: adding a skill under the default-deny .gitignore

Research

The original Claudeception package cites work on agent skill libraries and self-reflection, including Voyager, CASCADE, SEAgent, and Reflexion. The same principle applies here: agents that persist verified learning avoid repeating the same investigation.

See resources/research-references.md for the original research notes.

License

MIT