Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

docs/CC_PARITY_MATRIX.md

View on GitHub
# Codex Tellonce — Claude Code Parity Matrix

Date: 2026-05-01 (Round-7 update)
Status: native hook integration shipped; codex now wires PreToolUse /
PostToolUse / SessionStart / UserPromptSubmit (no Stop hook — that's the
one CC capability codex's runtime can't provide; PostToolUse +
wrapper-driven enforcement together cover the gap).

## Principle

Codex must preserve the corrected Claude Code version's user-visible behavior. It does not need to copy Claude Code mechanisms when Codex lacks the same runtime surface.

No CC capability may be removed from the Codex package without an explicit user decision. Staging is allowed; dropping is not. The install UX must still look simple from the outside: install one `tellonce` skill/package, run doctor, then use it.

## Legend

- `codex_core`: required in first stable release.
- `codex_wrapper`: enforced through `tellonce_codex exec`.
- `hooks_experimental`: only available when Codex hooks are explicitly enabled and verified.
- `deferred_with_reason`: postponed with an explicit replacement or rationale.

## Matrix

| Claude Code capability | Current CC mechanism | Codex parity target | Status |
|---|---|---|---|
| Skill entry and per-message scan | `SKILL.md` iron law + observation JSONL | Codex skill + `tellonce_codex scan` event ledger | `codex_core` |
| Install | `install.sh` with backup + merge settings | idempotent copy install (global runtime + hook registration + project state) with a versioned `hooks.json` backup (`.v3_pre_pt_*`); no manifest / smoke / commit phases | `codex_core` |
| Doctor | unit + path + hook registration + smoke | doctor checks: state, private_paths, wrapper, hooks, shadow (`doctor.run_doctor`) | `codex_core` |
| Rollback | latest settings backup + hook removal | manual: restore `~/.codex/hooks.json` from the versioned `.v3_pre_pt_*` backup written at install/uninstall; no rollback command yet | `deferred_with_reason` |
| Uninstall | keep data by default, optional purge | ownership manifest; keep data default; purge-state explicit | `codex_core` |
| Path config | `B5_*` env > config > cwd defaults | Codex project registration + explicit fallback | `codex_core` |
| Observation logging | `observations.jsonl` + compliance logs | authoritative `events.jsonl`; observations export only | `codex_core` |
| Retrieval injection | UserPromptSubmit hook | UserPromptSubmit hook (codex native) — `userpromptsubmit-dispatch.py` (retrieve step) | `codex_core` (Round-7) |
| Legacy pending observations | UserPromptSubmit/Stop workflow | metrics only; shared SQLite upsert is the sole writer | `codex_core` |
| B4 pending metric | Stop hook | log-only on all platforms | `codex_core` |
| Deterministic rules | Stop hook hard block | PostToolUse hook (`posttooluse-deterministic-block.sh`) scans agent-authored tool input; mode-aware (audit_only / wrapper / blocking). Wrapper-driven enforcement covers final stdout. | `codex_core` (Round-7) |
| Per-user whitelist | package base + user whitelist file | Codex base + user whitelist under config/state | `codex_core` |
| Streak bypass | repeated rule auto-bypass | implemented in the PostToolUse adapter (`codex_posttooluse_block.py`): per-session counter in the state dir, threshold `PT_STREAK_BYPASS`/`B5_STREAK_BYPASS` (default 3), kill-switch `PT_DETERMINISTIC_DISABLED`/`B5_DETERMINISTIC_DISABLED` honored | `codex_core` |
| Rule params | frontmatter `params` parser | preserve schema and defaults | `codex_core` |
| Threshold advisor | suggests threshold updates | dashboard advisory after telemetry exists | `deferred_with_reason` |
| Shadow judge | Claude CLI / SDK | provider-pluggable; disabled by default; no Claude dependency | `deferred_with_reason` |
| Shadow alert injection | next-turn additional context | UserPromptSubmit hook (codex native) — `userpromptsubmit-dispatch.py` (shadow-alert step) | `codex_core` (Round-7) |
| Auto-light-entry fallback | hook fallback for missing obs | doctor-visible degraded status + wrapper audit fallback | `codex_core` |
| Dashboard | 7-day compliance summary | prints mode, hooks, blocking, scan_count, wrapped_turns (`dashboard.py`) | `codex_core` |
| Chaos tests | 12 chaos tests | unit/integration suites are kept out of the public tree (see repo history: ec24a78); fault-injection chaos suite (fake HOME, interrupt, corrupt log, multi-project) not yet ported | `deferred_with_reason` |
| Cost cap | shadow judge budget | provider module later; disabled default | `deferred_with_reason` |
| Hook short-circuit | skip expensive hooks on no signal | not needed in core; hooks experimental must include short-circuit | `hooks_experimental` |

## Codex implementation notes (Round-7, 2026-05-01)

Codex actually exposes a hook system parallel to CC's (`~/.codex/hooks.json`,
hook events `PreToolUse / PostToolUse / SessionStart / UserPromptSubmit /
PermissionRequest`, JSON stdin/stdout, exit 2 + stderr reason for blocks).
The wire schema mirrors CC's almost exactly. Same scripts can be reused
modulo two adapters:

1. PostToolUse takes the place of Stop hook. CC fires Stop after every text
   reply; codex doesn't have that. Instead PT scans the AGENT'S tool input
   (Write content / Edit new_string / Bash command) on PostToolUse — that's
   where most CC-detectable violations actually originate. Pure-text
   violations (agent reply with no tool call) are caught only by the
   wrapper path (`tellonce_codex exec --`) since codex lacks a per-text
   hook.
2. Retrieve / pending / shadow-alert UPS hooks reuse CC's `lib/*.py`
   directly via the `shared_lib/` copy that codex install bundles into
   `~/.codex/skills/tellonce/`.

## Known CC Bugs / Portability Holes (historical)

- ~~Installs into `~/.claude/skills/tellonce`, not Codex paths.~~ Codex
  install now lays out `~/.codex/skills/tellonce/` with `tellonce_codex/`
  + `shared_lib/` + `hooks/` + `seed_memory/` + `SKILL.md` (Round-7).
- ~~Registers `.claude/hooks` and `.claude/settings.local.json`, which Codex does not consume.~~ Codex install
  registers into `~/.codex/hooks.json` via `install_codex_hooks --add` (Round-7).
- Memory still defaults to `~/.claude/projects/<cwd_escaped>/memory` — the codex variant honors
  `B5_MEMORY_DIR` env override the same way CC's path_config does.
- `shared_lib/` reuses CC's `pt_platform` defaults, so the UserPromptSubmit hooks
  create `.claude/tellonce-state/` directories inside Codex projects.
  Known cosmetic wart — harmless, and overridable via the `B5_*` path env vars.
- The legacy Codex skill (pre-PR-1) had developer-machine hardcoded paths in its install scripts; the current Codex variant runs through tellonce_codex.paths so it's portable, and tellonce_codex.doctor explicitly scans state files for those leaked tokens.
- Doctor scans state for private-path leaks + reports hook registration status (`hooks=PASS / NOT_INSTALLED / PARTIAL / FAIL`) post-Round-7.
- Rollback is based on latest-looking settings backup, not an install transaction id.
- Shadow judge can depend on `claude` CLI, which a Codex-only user may not have. Codex skips shadow_judge entirely (deferred — see `B5_JUDGE_BACKEND` todo).
- Stop hook behavior has no reliable Codex equivalent — PostToolUse + wrapper enforcement cover the gap for the cases that actually matter.

## Acceptance Rule

Every implementation task must update this matrix if it implements, defers, or changes a parity row. A task cannot be marked complete if it weakens a CC parity row without adding a replacement path and test.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall