Metadata-Version: 2.4
Name: claude-codex-queue
Version: 0.3.0
Summary: Local queue and auto-continue runner for Claude Code sessions and Codex App tasks.
Author: Claude + Codex Queue contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ravhello/claude-codex-queue
Project-URL: Issues, https://github.com/ravhello/claude-codex-queue/issues
Project-URL: Changelog, https://github.com/ravhello/claude-codex-queue/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ravhello/claude-codex-queue/blob/main/docs/ARCHITECTURE.md
Project-URL: Discussions, https://github.com/ravhello/claude-codex-queue/discussions
Project-URL: Releases, https://github.com/ravhello/claude-codex-queue/releases
Project-URL: Source, https://github.com/ravhello/claude-codex-queue
Keywords: ai-agents,anthropic,automation,claude,claude-code,codex,developer-tools,openai,queue,rate-limit,wsl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/ravhello/claude-codex-queue/main/assets/claude-codex-queue-128.png" width="112" alt="Claude + Codex Queue icon">
</p>

<h1 align="center">Claude + Codex Queue</h1>

<p align="center">
  Queue prompts for existing Claude Code sessions and Codex App tasks.<br>
  Wait out usage limits, retry the interrupted turn correctly, then resume the queue without wasting the next prompt.
</p>

<p align="center">
  <a href="https://github.com/ravhello/claude-codex-queue/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ravhello/claude-codex-queue/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/ravhello/claude-codex-queue/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/ravhello/claude-codex-queue"></a>
  <a href="https://pypi.org/project/claude-codex-queue/"><img alt="PyPI" src="https://img.shields.io/pypi/v/claude-codex-queue"></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white">
  <a href="https://github.com/ravhello/claude-codex-queue/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/ravhello/claude-codex-queue"></a>
  <a href="https://github.com/ravhello/claude-codex-queue/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ravhello/claude-codex-queue?style=social"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> |
  <a href="#how-limit-recovery-works">Limit recovery</a> |
  <a href="https://github.com/ravhello/claude-codex-queue/blob/main/ROADMAP.md">Roadmap</a> |
  <a href="https://github.com/ravhello/claude-codex-queue/discussions">Discussions</a>
</p>

![Claude + Codex Queue dashboard with anonymized sample data](https://raw.githubusercontent.com/ravhello/claude-codex-queue/main/docs/assets/dashboard.png)

## 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, and recovers the interrupted turn
without duplicating a failed message. It 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 Code, Cowork artifact and private Claude Code artifact synchronization with archive and delete propagation;
- Codex task forks for the active ChatGPT-authenticated account, with linked lifecycle sync;
- per-account Claude and ChatGPT usage windows with the next reset and first available account;
- 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.

### Multi-account chat copies

Claude Desktop Code sessions are replicated once per known account. Archive and
unarchive changes propagate in either direction. A missing known replica is
observed twice before it is treated as a deletion; the app then writes a durable
tombstone, backs up the remaining metadata and removes the other replicas. A
surviving Claude transcript cannot recreate or relist a tombstoned chat. Remote bridge
identifiers remain owned by their original Claude account and are never copied
to another account, preventing failed remote deletes from restoring a local
replica. Account switches and session-directory changes wake the sync monitor
immediately instead of waiting for the normal polling deadline.

Every synchronization pass selects one canonical session record and writes the
same shared fields to every account replica. It then compares both the chat count
and a SHA-256 fingerprint of the shared content for every logical session. A
duplicate, missing replica or content mismatch fails the inventory check and is
shown on the dashboard instead of being reported as a successful sync. Only
provider-required account-local transport fields (`sessionId`, private artifact
`cliSessionId` aliases and `bridgeSessionIds`) are excluded from that comparison;
they do not change the conversation or its settings.

Account changes are read from Claude's session-bridge log as soon as login
finishes, before the app writes its first activity to `config.json`. Cowork
artifact manifests are replicated to every known account/organization and their
session links are remapped to the destination copy. Connector grants, published
share IDs and other account-local fields are not copied. Artifact deletion uses
the same two-scan confirmation rule; the physical `Artifacts/<id>/index.html`
file remains provider-owned and is never deleted by this project.

Claude Code web artifacts use a different, account-private service. The sync
monitor verifies locally cached OAuth credentials against `/api/oauth/profile`,
caches the rendered artifact locally, creates one private server copy per
account and points an account-specific derived transcript at that copy. The
original provider transcript is never edited. If an account is logged out or
its token is not currently cached, the UI reports that copy as waiting and
finishes it automatically after the next login; a token belonging to another
account is never substituted.

When the monitor runs in WSL, private artifact replication uses hidden
PowerShell 7 (`pwsh.exe`) to decrypt Claude Desktop's Chromium AES-GCM cache
under the current Windows user. Without PowerShell 7, chat and lifecycle sync
continue normally while private artifact copies remain pending.

The chat list keeps one row per logical Claude session and shows every account
that currently owns a replica. Account identifiers are searchable, so switching
accounts never makes the previous account's sessions appear to vanish. Each row
also shows the beginning of the latest real user message from the transcript,
excluding assistant output and tool results.

For Codex, **Copy to active ChatGPT account** uses Codex app-server
`thread/fork` and creates a new thread ID instead of relabelling the old task.
Only copies linked by this app share archive, unarchive and delete state. Those
operations use the official `codex archive`, `codex unarchive` and
`codex delete --force` commands; the project never edits Codex SQLite or rollout
files directly.

The local web process runs a complete transcript and artifact scan on startup,
then a fast linked-account check on a ten-second cadence and another full scan
every minute. Account and session-directory changes wake it immediately, so
clicking **Aggiorna** is not required. Verified OAuth sessions are retained only
in process memory between fast checks; any credential-file change invalidates
that cache immediately.
Discovery, chat lifecycle replication and local artifact caching continue while
Claude Desktop, Codex and VS Code are closed. A due Claude Desktop native
`Try again` action opens the selected Claude session through its registered
`claude://` link because that final UI action necessarily needs Claude Desktop.
The browser API uses the fast metadata path first; Claude chats appear while the
full Claude/Codex list is refreshed in the background. Slow transcript discovery
does not add another fixed delay before the next metadata check, so lifecycle
synchronization does not depend on an open or foreground browser tab. The Windows
Startup entry keeps the program running after login.

Filesystem discovery, account synchronization and queue persistence do not
require Claude, Codex or VS Code to be open. Sending still requires the matching
authenticated CLI; Claude Desktop native retry opens the exact app session when
needed.

Codex changes for a copy owned by another ChatGPT account remain pending until
that account becomes active, then the monitor applies them automatically. State
updates are locked across local processes; a corrupt or unreadable state file
stops synchronization instead of being replaced with an empty one.

Here, “ChatGPT account” means the account authenticating Codex. This feature
does not copy ordinary conversations from chatgpt.com, and the Claude feature
does not copy ordinary claude.ai chats.

### Two Claude Desktop accounts at the same time

The optional multi-account companion uses the MIT-licensed
[Zoltak-Dev/ai-multi-instance](https://github.com/Zoltak-Dev/ai-multi-instance).
It gives every Claude Desktop account a separate Chromium `--user-data-dir`, so
the official Windows app can keep multiple authenticated instances open side by
side. This project installs the audited source commit rather than an unsigned
binary:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-claude-multi-account.ps1
```

The companion setup requires Windows 10 or later, Git for Windows and Python 3.
The installer clones source rather than an unsigned binary, checks out a pinned
commit, verifies the audited SHA-256 hashes and creates a Desktop shortcut.
Create two Claude profiles in the visible manager and complete Claude's login
once for each profile. OAuth callbacks must pass through Claude's default MSIX
instance, so this provider login is the only interactive step. From then on the
queue discovers every `ClaudeProfiles/<name>` directory, starts authenticated
profiles again after Windows/app restarts, refreshes their usage every minute
and shows whether two distinct accounts are simultaneously available.

The dashboard also derives a 2 h 30 stagger plan from the two live five-hour
reset windows. It never sends a synthetic prompt merely to start or manipulate
a quota window. At the planned time it identifies the account on which the next
real queued job should run; normal queue and auto-continue rules still prevent a
prompt from being spent before the provider reset.

Custom installations can set `CLAUDE_MULTI_INSTANCE_ROOTS` to one or more
semicolon-separated manager or `ClaudeProfiles` paths. Automatic launch is
enabled only after the installer records the exact audited commit and source
hashes. The helper used at runtime is included in both the source package and
wheel.

## 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.

```powershell
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/](http://127.0.0.1:8765/). Both the
Desktop and Startup shortcuts use the windowless Windows Script Host; WSL,
PowerShell, Claude and Codex child processes are launched with hidden/no-window
settings, so the app does not create terminal windows in normal operation.
Under WSL, PowerShell scripts are stored atomically in the current user's
private queue cache and invoked by file; large encoded scripts and raw child
commands are never returned by the web diagnostics.

The installer also registers the app in the current Windows user's Startup
folder. At login it starts the server in the background and opens the browser
after the health check succeeds. The page refreshes every five seconds and
again whenever its tab regains focus. A server-side supervisor starts the queue
runner whenever pending messages, recovery work or auto-continue need it, so
the **Refresh** and **Start runner** buttons are not required for normal use.

To install or repair only the automatic startup entry:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-autostart.ps1
```

To run it without installing a shortcut:

```powershell
.\start-claude-codex-queue.ps1
```

### Install the CLI from the latest wheel

Run this inside WSL:

```bash
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

```mermaid
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{"Provider and turn state"}
    G -- "Claude Desktop Code" --> H["Invoke native Try again"]
    G -- "Codex prompt never started" --> I["Rollback failed turn and resend the same prompt"]
    G -- "Codex work stopped before recap" --> J["Send 'continua'"]
    I --> K["Queue any additional failed prompts in order"]
    J --> K
    H --> A
    K --> A
```

Auto-continue can monitor any number of selected sessions with an empty queue.
Each session keeps independent status, timing, settings and cancellation state;
one failed or waiting session does not replace or stop the others.

For Claude Desktop Code sessions, auto-continue opens the exact local session
through Claude's supported deep link and invokes the visible `Try again` control
through Windows UI Automation. It checks the native control directly because
Claude Desktop can show it without recording a limit in the transcript, and it
keeps monitoring after a successful invocation. It never substitutes a new
`continua` message.
For Codex App tasks, the runner reads structured turn state through app-server:
a failed turn with no agent progress is removed with `thread/rollback` and sent
again unchanged, while an interrupted turn that already contains agent activity
receives `continua`. Additional failed text prompts are placed in the persistent
queue in their original order.

## Safety guarantees

- The project does not bypass or evade provider limits.
- The next queued prompt remains pending when a limit is detected.
- Failed Codex prompts are rolled back before replay, so the task does not show a duplicate user message.
- Claude Desktop `Try again` failures never fall back to sending a new prompt.
- 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.
- Codex account copies receive a new thread ID and require an explicit confirmation.
- Destructive lifecycle changes are debounced and verified before linked copies are changed.
- Controls are disabled for sessions that are genuinely view-only.
- Queue state and logs stay local under the detected Windows profile.

Read [SECURITY.md](https://github.com/ravhello/claude-codex-queue/blob/main/SECURITY.md) before sharing diagnostics. Never publish private
transcripts, authentication files, tokens, or unredacted logs.

## CLI

```bash
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:

```text
<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

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

See [CONTRIBUTING.md](https://github.com/ravhello/claude-codex-queue/blob/main/CONTRIBUTING.md),
[ARCHITECTURE.md](https://github.com/ravhello/claude-codex-queue/blob/main/docs/ARCHITECTURE.md),
and the [roadmap](https://github.com/ravhello/claude-codex-queue/blob/main/ROADMAP.md). Questions and setup help belong in
[Discussions](https://github.com/ravhello/claude-codex-queue/discussions);
reproducible defects belong in
[Issues](https://github.com/ravhello/claude-codex-queue/issues).

## Project status

Current release: **v0.3.0**. 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](https://github.com/ravhello/claude-codex-queue/blob/main/LICENSE).
