Codex Auto Archive

English · 简体中文 · 日本語 · Español

Manage Codex's own Archive in natural language. Independent idle, completion and GitHub workflow rules; exact-thread protection; previews and reversible operations; a local scheduler that never calls an LLM.

v0.1.0 is safety-gated. Native archive/restore and MCP work, but a detached App Server cannot prove whether Desktop or another process is busy. Automatic execution is blocked for those threads. On the tested Codex CLI 0.160.0, pin state is also absent from the protocol, so default pin protection skips these threads. Installing this plugin does not mean unattended Desktop archiving is verified or supported on that version. See compatibility.

Install once

Requirements: Python 3.11+, uv, a local Codex CLI with App Server and plugin support. gh is optional and reuses your existing login.

git clone https://github.com/Jineggegg/codex-auto-archive.git
cd codex-auto-archive
bash scripts/install.sh

Windows PowerShell:

git clone https://github.com/Jineggegg/codex-auto-archive.git
cd codex-auto-archive
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

The execution policy switch applies only to that installer invocation. Dependencies are pinned in uv.lock. The installer uses official codex plugin marketplace add and codex plugin add, then creates a systemd user timer or Windows scheduled task. It opens no ports and never modifies Codex session files.

Open a new Codex conversation. In Codex, review and trust the plugin's command hooks with /hooks (or the native hook review UI). Official Codex requires trust for the exact hook definitions; the installer does not bypass it. Time-rule evaluation and Dry Run work without hooks. Local plugin commands require uv on the Codex client's PATH.

For a different profile, set CODEX_HOME before installation (PowerShell installer also accepts -CodexHome). Windows and WSL profiles are separate; installing in WSL does not install into Windows Desktop. Keep the checkout/runtime while the scheduler is installed.

Related MCP server: workflow-studio

Say it in Codex

• “Use 7 idle days, and archive after the linked PR merges.”

• “Disable completion archiving but keep time archiving.”

• “Never automatically archive this project.”

• “Show the next 7 days of archive candidates.”

• “Show the latest 10 automatically archived conversations.”

• “Restore yesterday's automatically archived conversations.”

• “Set language to Simplified Chinese.”

The bundled skill translates requests into strictly typed MCP tools using the existing conversation model. The MCP server, hooks and scheduler make no additional model calls. locale supports auto, en, zh-CN, ja, es; chat responses follow the user's language. Machine-readable tool keys stay stable.

“Enable auto archive” explicitly authorizes leaving Dry Run; changing days, selecting a preset or installing does not. Runtime/pin/goal/agent protections still apply after enabling. Batch archive and restore always require a displayed preview followed by explicit confirmation. A confirmation token is single-use, lasts 10 minutes and binds the selected IDs and configuration. A forecast token cannot archive anything.

Current-thread operations use CODEX_THREAD_ID only when the host provides it and App Server can read the exact thread. Otherwise, Codex asks you to select an ID from the thread list. Current-thread archive is deferred at least 60 seconds and until idle; new user input cancels it. Never treat “scheduled” as “archived.”

Defaults and rules

Priority: exclusions → safety → thread overrides → project overrides → global policy → defaults. Enabled triggers are OR-combined, except workflow_all_of explicitly requires all its enabled events. Presets reset global trigger policy: conservative=90d/24h grace, standard=30d/30min, aggressive=7d/5min. Presets keep pin protection and disable completion/workflow triggers; overrides remain.

Effective activity comes from official turn start/completion timestamps and lightweight activity hooks, not creation time or metadata updatedAt. A normal reply, Stop or SessionEnd never marks a task complete. Active/paused/blocked goals, approval waits, active agents, unknown descendants and unsupported sources are protected. Recent child activity prevents an older parent from cascading an automatic archive.

PR/Issue links require exact user-confirmed owner/repository and number. GitHub is used only to confirm workflow conditions through authenticated gh api. CI must have real successful checks/statuses on the exact PR head SHA; an empty suite isn't success. Network/auth failures cannot produce a positive workflow signal. Time triggers remain independent.

Tools and maintenance

Tool reference · Architecture and safety · Compatibility and validation

uv run codex-auto-archive doctor
uv run codex-auto-archive check --dry-run
uv run codex-auto-archive disable
uv run codex-auto-archive enable             # preserves Dry Run
uv run codex-auto-archive export policy.json
uv run codex-auto-archive import policy.json # always returns to Dry Run
uv run codex-auto-archive scheduler-remove
uv run codex-auto-archive scheduler-install
uv run codex-auto-archive uninstall         # keeps settings/audit
uv run codex-auto-archive uninstall --purge # removes only plugin state

Use the same UV_PROJECT_ENVIRONMENT as the installer when invoking from the checkout if you want to reuse its environment; the plugin's cached environment is separate. You can also invoke the installed runtime's python -m codex_auto_archive directly.

Update: git pull --ff-only, rerun the installer. Published versions bump the plugin version so the official plugin cache refreshes. Reinstalling keeps settings/audit and does not silently activate archiving. Uninstall removes this plugin and its marketplace/timer; it never deletes or unarchives Codex conversations. Remove the checkout and dedicated runtime directory afterward if no longer wanted. Config export excludes executable connection configuration; importing resets the connection and requires new execution consent.

Advanced Linux/WSL hosts with a single official controlling App Server can configure its existing control socket using connect --proxy-socket /absolute/socket --confirm-shared-runtime. This is an operator assertion that every relevant client uses that server, not automatic discovery. Do not point at an unrelated daemon to bypass a Desktop protection. No daemon is started or Desktop restarted by this plugin. Real automation still requires known pin state and explicit activation.

Development

uv sync --extra dev --frozen
uv run pytest -q
ARCHIVE_REAL_INTEGRATION=1 uv run pytest -q tests/test_integration.py
uv run ruff check src tests

The opt-in integration test creates a disposable, isolated CODEX_HOME, materializes a test thread using a local synthetic Responses fixture, archives and restores that thread through official RPC, and checks native membership. It never targets existing user threads or calls a real model. Validation details.

Official interfaces: App Server, hooks, plugin packaging. This is an independent community project, not an OpenAI product.