claude-codex-queue 0.2.2

Local queue and auto-continue runner for Claude Code sessions and Codex App tasks.

Claude + Codex Queue

Queue prompts for existing Claude Code sessions and Codex App tasks.
Wait out usage limits, send continua, then resume the queue without wasting the next prompt.

Quick start | Limit recovery | Roadmap | Discussions

Why use it?

AI coding sessions often stop at the usage-limit boundary. Sending the next real prompt immediately can waste it on another limit response. Claude + Codex Queue keeps that prompt pending, waits for the reset, resumes the interrupted work with continua, and only then processes the rest of the queue in order.

The app works with sessions you already use. It does not create a separate chat system and does not require external Anthropic or OpenAI API keys.

What it supports

Source	Discover	Queue prompts	Auto-continue	Preserve settings
Claude Code in VS Code	Yes	Yes	Yes	Model, effort, permissions
Claude Desktop Code sessions	Yes	Yes, when locally resumable	Yes	Model, effort, permissions
Claude Code over Remote SSH	Yes	When enough metadata exists	Yes	Remote effective settings
Codex App tasks	Yes	Yes	Yes	Model, reasoning, sandbox, approvals

Additional capabilities:

• newest-real-message sorting across Claude and Codex;
• persistent FIFO queue with per-prompt priorities;
• one-minute safety delay after a parsed reset time;
• multi-account Claude metadata synchronization and chat transfer;
• account mismatch and view-only checks before actions are enabled;
• transcript confirmation after every Codex send;
• local web UI plus a scriptable CLI;
• no runtime Python dependencies outside the standard library.

Quick start

Windows app and Desktop shortcut

Requirements: Windows, WSL, Python 3.10+ in WSL, and at least one authenticated Claude Code or Codex CLI installation.

git clone https://github.com/ravhello/claude-codex-queue.git
cd claude-codex-queue
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-desktop-shortcut.ps1

Open Claude + Codex Queue from the Desktop. The launcher starts the local server and opens http://127.0.0.1:8765/.

To run it without installing a shortcut:

.\start-claude-codex-queue.ps1

Install the CLI from the latest wheel

Run this inside WSL:

python3 -m pip install claude-codex-queue
claude-codex-queue doctor
claude-codex-queue-web --host 127.0.0.1 --port 8765

The source checkout is recommended if you want the Windows launcher and Desktop shortcut. The wheel is useful for CLI-only installations.

How limit recovery works

flowchart LR
    A["Queued prompt"] --> B["Resume selected session"]
    B --> C{"Usage limit?"}
    C -- "No" --> D["Confirm prompt in transcript"]
    C -- "Yes" --> E["Keep prompt pending"]
    E --> F["Wait until reset + 60 seconds"]
    F --> G["Send 'continua'"]
    G --> H{"Previous work finished?"}
    H -- "Not yet" --> G
    H -- "Yes" --> A

Auto-continue can also monitor a selected session with an empty queue. It sends nothing while no active limit is detected.

Safety guarantees

• The project does not bypass or evade provider limits.
• The next queued prompt remains pending when a limit is detected.
• Chat settings are fingerprinted and checked before sending.
• External Anthropic and OpenAI API-key/base-URL overrides are removed from child processes, so local CLI authentication remains authoritative.
• Codex dangerous bypass mode is never enabled implicitly.
• Controls are disabled for sessions that are genuinely view-only.
• Queue state and logs stay local under the detected Windows profile.

Read SECURITY.md before sharing diagnostics. Never publish private transcripts, authentication files, tokens, or unredacted logs.

CLI

claude-codex-queue doctor
claude-codex-queue list --limit 30
claude-codex-queue add --chat <selector> [--priority 100] "message"
claude-codex-queue status -v
claude-codex-queue check-settings
claude-codex-queue run
claude-codex-queue remove <item-id>
claude-codex-queue reset <item-id>
claude-codex-queue clear

<selector> accepts a visible row number, session-ID prefix, title fragment, or working-directory fragment. Multiple messages can be supplied in order or loaded from @prompt.md.

State and compatibility

New installations use:

<Windows user profile>\.claude-codex-queue

Existing installations automatically keep using .claude-vscode-queue, so an upgrade does not reset queues or logs. The old Python modules, commands, and launcher names remain as compatibility aliases.

Development

python3 -m unittest discover -s tests -v
python3 -m build
python3 -m twine check dist/*

See CONTRIBUTING.md, ARCHITECTURE.md, and the roadmap. Questions and setup help belong in Discussions; reproducible defects belong in Issues.

Project status

Current release: v0.2.2. The project is alpha software tested on Windows/WSL with local Claude Code and Codex App workflows. Upstream desktop metadata is not a public compatibility contract and may change between provider releases.

Claude + Codex Queue is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI.

Released under the MIT License.