跳转至

Chinese · English

For Codex Desktop: actual gate consistency, GPT-6 controllers, and native receipt recovery. Existing roots retain their routing and accounting semantics. Internal scripts support management and validation, not a standalone CLI product.

Stable release V7.17.3 was published on 2026-10-29 (UTC).

Codex Cross-Project Engineering Assistant

Codex bilingual project preview

A cross-project engineering framework for Codex: Skill routing, independent multi-agent review, recoverable task memory, lifecycle events, and controlled evolution.

CI Bilingual documentation Latest release Apache-2.0 Python 3.11+ Codex Desktop

The current implementation retains non-blocking message/Stop behavior, Operation v2, and separation of base Skills from optional enhancement. The optional file gate remains off by default; when enabled, missing indexes or optional material permit scoped continuation without disabling it. Capability level establishes neither semantic correctness nor authority. See the model policy and Desktop gates and recovery.

Quick links: Bilingual documentation · Downloads · Four daily paths · Start · Compatibility · Upgrade · Documentation

Use the assistant directly after installation; ordinary work does not require learning Profiles, indexes, or ledgers first. The first full scan is optional. Declining it, leaving it unanswered, or losing auxiliary storage keeps the current-source BASIC path available. For recovery, use doctor, read-only inventory, and canonical recover in that order; each reports the affected feature, what still works, and the next action.

Four daily paths and the unified entry

The extracted source tree and release ZIPs provide the same cp-assistant entry. Use scripts\\cp-assistant.ps1 on Windows and scripts/cp-assistant.sh on POSIX. help and install-base do not require this package's Python runtime. Other management commands report the Python 3.11+ requirement instead of fabricating Plugin state.

Daily path Example request Entry behavior
Fix a bug “Fix the failing validation and run the smallest relevant test.” Describe the problem; use status / doctor when state is relevant.
Build a feature “Implement this feature and validate it according to risk.” Describe the objective; add enhancements only when needed.
Review “Review this branch for compatibility and security risks.” Describe the review scope; independent review is risk-driven.
Continue a task “Continue the previous task and tell me where it stopped and what is next.” Run read-only resume; it does not recover an install transaction.
.\scripts\cp-assistant.ps1 help
.\scripts\cp-assistant.ps1 install-base
.\scripts\cp-assistant.ps1 status
.\scripts\cp-assistant.ps1 doctor
.\scripts\cp-assistant.ps1 inventory --scope user --mode plugin --json
.\scripts\cp-assistant.ps1 resume --repo-path E:\\work\\repo --profile C:\\safe-state\\project-profile.json --checkpoint-dir C:\\safe-state\\task
.\scripts\cp-assistant.ps1 recover --scope user

status, doctor, inventory, and resume are read-only. install-base, install-enhancement, and recover are write operations. resume accepts a bound Profile/State/Evidence set or an explicitly supplied legacy Markdown checkpoint directory. It reports the stage, checkpoint, repository changes, evidence needing revalidation, and one next action; it does not create a Profile, repair checkpoints, or continue a task. Default status retains the complete check; use the lower-cost diagnostic view only when explicitly requesting status --quick. Add --json for the machine-readable view.

On POSIX, replace the path with ./scripts/cp-assistant.sh. See the user guide for the four paths.

Start in two steps

  1. Extract the package and install the base Plugin with its native launcher. This does not need this package's Python runtime or an API key.
.\scripts\install-base.ps1
./scripts/install-base.sh
  1. Describe the work in ordinary language. For example:
Fix the failing validation in this repository and run the smallest relevant test.
Review the changes I made in this branch for compatibility and security risks.
Continue the previous task; first confirm what is already changed and what still needs verification.

The base Plugin loads the ten Skills once and does not start Hooks, workers, Profile creation, indexing, or a budget ledger. Those remain optional enhancements rather than prerequisites for ordinary work.

Optional enhancements

Use the existing enhanced installer only when the task needs recoverable long-running state, Hooks, indexing, an independent Reviewer, an enforced budget, or controlled writes. It performs the existing backup, transaction, verification, and recovery steps; a managed enhancement installation is never downgraded by the base launcher.

Downloads

Download the public V7.17.3 packages, published on 2026-10-29 (UTC).

Package Interface Download
Codex-Skills-V7.17.3-zh-CN.zip Chinese Download zh-CN package
Codex-Skills-V7.17.3-en.zip English Download English package

Release · SHA256SUMS.txt

Core capabilities

  • Ten engineering Skills with minimal, progressive routing for the active task.
  • The C01-C25 registry defaults to AUTO/BASIC. A missing prerequisite degrades only that capability, while explicit OFF and task risk are evaluated separately.
  • A first full scan queues only after an explicit persisted choice. Decline, no reply, cancellation, persistence failure, and late workers have separate states.
  • Seven logically read-only Reviewers with no hard-coded model or reasoning effort.
  • The enhanced installation registers 8 registered Hook entry points: UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop, Interrupt, SessionEnd. The base Plugin registers none; enhanced UserPromptSubmit is asynchronous observation, Stop is neutral, and Interrupt remains host-controlled.
  • TaskOutcomeEvent 3.0 with project_id + repo_fingerprint isolation and a separate continuous hash chain.
  • Recoverable checkpoints, delayed SessionEnd sealing, event archives, and cross-project health summaries.
  • Separate package routing regression from real-host routing acceptance, binding host evidence to raw final-report SHA-256 digests.
  • Evaluate evidence sufficiency per evolution signal instead of globally blocking on unrelated missing telemetry.
  • Controlled proposals fixed at execution_authorization=NONE, without implementation authority.
flowchart LR
    A[Task input] --> B[Minimal Skill routing]
    B --> C[Main Agent execution]
    C -. Optional enhancement .-> D[Independent Reviewers]
    C -. Optional enhancement .-> E[Lifecycle Hooks]
    D --> E
    E --> F[TaskOutcomeEvent 3.0]
    F --> G[Project isolation and hash chain]
    G --> H[Snapshot / Assessment / Proposal]
    H --> I[Human decision]

Reproducible usage example

The following input, flow, and inspectable outcome show a typical read-only task. This is an illustrative usage example, not runtime evidence for the current session.

Task input

Inspect the installer upgrade path in the current repository without modifying files.
Select a Reviewer according to actual risk, and separate confirmed facts, inferences,
and unverified items.

Expected flow

Task input
  -> route engineering-quality-delivery
  -> read the installer, manifests, tests, and upgrade documentation
  -> start a logically read-only Reviewer when justified by risk
  -> deduplicate and reconcile Reviewer findings
  -> report evidence, risks, and unverified boundaries

The lifecycle can produce TURN_OPENED -> SUBAGENT_STARTED -> SUBAGENT_STOPPED -> TASK_COMPLETED; SessionEnd then enters the delayed sealing path. Model evidence stays separated into two fields:

dispatch_policy_status = PASS
host_model_identity = NOT_COLLECTED

Dispatch records establish conformance with the task's authorized policy, not the backend model that actually ran.

Compatibility matrix

Environment or mode Current role Existing validation level Boundary
Codex Desktop + Plugin Sole product target Local installation, enabled-gate writes, continuation and receipt reconciliation verified Evidence is bound to the V7.16.0 release commit and observed host; other environments need their own checks
Windows / Ubuntu Python matrix Package release gate Python 3.11/3.13 tests and builds This does not prove native Desktop acceptance; read remote results from Actions
Old layouts and frozen policies Compatibility recovery Existing states, ledgers and readers remain No standalone CLI product adaptation or acceptance track
macOS Unverified No current CI or host-acceptance evidence Status remains UNVERIFIED

The base installation does not require the package Python runtime; the enhancement runtime requires Python 3.11 or later; public CI is configured to validate both 3.11 and 3.13 on Windows and Ubuntu. For any other environment combination, run doctor, dry-run, and verify before deciding its usable status.

The bundled Desktop management component may have an internal prerelease version. Installation checks executable identity, command contracts and registration structure. That version is not the Desktop task-runtime version. The old stable registry retains historical reading and recovery semantics only.

First install and upgrade

For a new installation, use the base launcher above. To add enhancements, or to upgrade an existing managed V7 installation, run the following commands from the extracted package root:

python scripts\package_manager.py doctor
python scripts\package_manager.py install --scope user --mode plugin --dry-run
python scripts\package_manager.py install --scope user --mode plugin
python scripts\package_manager.py verify --scope user --mode plugin
codex plugin list --json

The enhanced installation is established only when Plugin readback reports installed=true, enabled=true, the expected release version, a compatible host snapshot, and no declared legacy Skill directory. doctor and status normally show what remains usable, what is affected, why, and the one next action; use --json for the full machine-readable record.

The installer detects an existing version, creates a bounded backup, rejects link and reparse-point risks, preserves unknown files, and removes only Manifest-declared legacy Skill directories: the three V7 domain replacements plus the previously deprecated Vue Skill. See Installation and recovery and the User guide.

Model evidence boundary

New tasks use desktop-g6-deterministic-v1. Scripts choose from all nine GPT-6 Luna/Sol/Astra low/medium/high profiles for Reviewers, Workers and Explorers. Ordinary or unknown work uses Sol/medium. Models retain semantic judgment and bounded adjustment proposals; actual calls use exact script-approved parameters.

Missing rationale, qualification cards, gain evidence, historical samples or optional material keeps gates enabled and returns a default/degraded path. Authorization, integrity and real budget constraints still restrict their affected action. Permission to continue does not establish verified success, and planning units are not actual fees or capability rankings. See model selection and budget.

Requested parameters do not attest to the underlying host model, which this package does not read or infer. Keep the main agent's selection; automatic xhigh/max/ultra remain forbidden. Retain 5.6 and V3/V4 for explicit compatibility and unchanged historical replay, without repricing old charges or outcomes.

Documentation and collaboration

Local validation

python scripts\localization-audit.py --strict
python scripts\validate-package.py

Release builds use fixed timestamps, stable ordering, and SHA-256 witnesses. The source repository and release archive are separate evidence layers: repository CI validates a commit, while Release assets and witnesses validate downloadable artifacts.

Release provenance

The Release Candidate and Provenance workflow validates version tags, checks the source on Windows and Ubuntu, builds both reproducible ZIP files, and uses GitHub Artifact Attestations to generate signed provenance for the actual ZIP digests. An authorized public Release is created and read back separately.

$repository = ([uri]"https://github.com/JimmyVGDY/codex-long-term-assistant-skills").AbsolutePath.Trim("/")
gh attestation verify Codex-Skills-V7.17.3-en.zip --repo $repository

See Release automation and artifact provenance for the complete gates and new-version procedure.

Safety boundaries

  • No automatic Skill, Reviewer, model-route, global-configuration, or business-repository modification.
  • No automatic proposal acceptance or execution.
  • No automatic commit, push, deployment, restart, production operation, or business-data write.
  • Evidence records facts and never grants authority.
  • Raw prompts, complete responses, source bodies, diffs, tokens, cookies, API keys, and credentials are not stored by default.

Licensed under Apache-2.0. See LICENSE.

Reuse guidance: Capability index · Acceptance protocol.

Published-release validation and known limits