codex-compressor

KO | EN

gitlite — search

#large-language-models #chatbot #redis #javascript #cloud-native #github #bash #ai-agent #deep-learning #privacy

codex-compressor

(★ 9)

Keep long-running Codex tasks moving across fresh context windows with validated cumulative handoffs.

File Explorer

ZIP Download

- - marketplace.json
- marketplace.json
- - ci.yml
  - release.yml
- codex-compressor-hero-en.png
- codex-compressor-hero-ko.png
- - __init__.py
  - __main__.py
  - cli.py
  - compatibility.py
  - configuration.py
  - continuity.py
  - github_star.py
  - manager.py
- test_compatibility.py
- test_configuration.py
- test_continuity.py
- test_github_star.py
- test_manager.py
- test_plugin_contract.py
- test_release_notes.py
- release_notes.py
- sync_plugin_runtime.py
.gitignore
CHANGELOG.md
install.ps1
install.sh
LICENSE
NOTICE
pyproject.toml
README.md
README_ko.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[한국어](README_ko.md)

![Codex Compressor breaks the infinite compaction loop with a handoff.](https://raw.githubusercontent.com/hehee9/codex-compressor/main/assets/codex-compressor-hero-en.png)

**Break Codex's infinite `read → compact → reread` loop on long-running tasks.**

## Why

**Codex's built-in compaction**

> Shortened history → Omitted details → Reread files and reconstruct decisions → Compact again

→ Tasks that outlast the interval between compactions enter an **infinite loop**

**Codex Compressor**

> Handoff → Fresh context window → Resume from the exact next action

- Creates a visible cumulative handoff while the active agent still has the full context.
- Validates, saves, and reinjects the handoff through hooks.
- Starts the new window with context headroom and resumes from the exact next action.

⭐ [Star Codex Compressor on GitHub](https://github.com/hehee9/codex-compressor)

**Requirements:** Python 3.11 or later · Windows, macOS, or Linux · standalone installation or local Codex plugin

## Standalone installation

macOS and Linux:

```sh
git clone https://github.com/hehee9/codex-compressor.git
cd codex-compressor
./install.sh install --mode standalone
```

Windows PowerShell:

```powershell
git clone https://github.com/hehee9/codex-compressor.git
Set-Location codex-compressor
.\install.ps1 install --mode standalone
```

## Plugin installation

```text
codex plugin marketplace add .
codex plugin add codex-compressor@codex-compressor-local
```

Complete the plugin setup:

```sh
# macOS and Linux
./install.sh install --mode plugin
```

```powershell
# Windows PowerShell
.\install.ps1 install --mode plugin
```

Open `/hooks` in Codex, approve the `codex-compressor` hooks, and start a new session.

## Commands

macOS and Linux:

```sh
./install.sh status
./install.sh doctor
./install.sh uninstall
```

Windows PowerShell:

```powershell
.\install.ps1 status
.\install.ps1 doctor
.\install.ps1 uninstall
```

## Known limitation

- Sub-agents may lose their previous context during compaction because the `SessionStart(compact)` hook is not called. ([#35935](https://github.com/openai/codex/issues/35935), [#17148](https://github.com/openai/codex/issues/17148))

## License

codex-compressor

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

codex-compressor

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README