ctx

Active · v1.6.3

🧩 About this project

ctx is a CLI tool that preserves Claude Code session context across compactions.

When Claude Code hits its context window limit and compacts the conversation, critical information gets diluted or lost: the current goal, technical decisions already made, which files you were editing, what still needed to be done. After two or three compactions, Claude can forget what you were building, repeat work, or contradict decisions you already agreed on.

ctx hooks into Claude Code’s PreCompact, PostCompact, and SessionStart events to capture and restore a structured snapshot of your working context, every time. Snapshots are scoped per branch, so parallel sessions on different branches never collide.

⚙️ How to use it

Install:

curl -fsSL https://raw.githubusercontent.com/AgusRdz/ctx/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/AgusRdz/ctx/main/install.ps1 | iex

Homebrew:

brew install AgusRdz/tap/ctx

Register the hooks:

ctx init

After that, everything is automatic.

📋 What it captures

🛠️ Main commands

ctx init              # install hooks in Claude Code
ctx init --status     # verify installation
ctx show              # view current snapshot
ctx clear             # delete snapshot
ctx list              # list projects with snapshots
ctx config            # show effective config
ctx doctor            # installation health check
ctx logs              # view hook logs
ctx agents            # subagent capture mode
ctx update            # update to latest version

🔧 Technical details

• Written in Go — fast, single binary, no runtime dependencies
• Cross-platform: Linux, macOS, Windows (amd64 / arm64)
• Two-layer config: global (~/.config/ctx/config.yml) and per-project (.ctx/config.yml)
• Snapshots stored at ~/.local/share/ctx/{project-hash}/
• Smart transcript compression to fit within token budgets
• Deterministic fallback if claude -p is unavailable

💬 Read more about the motivation behind ctx in the blog post.