# ctx

ctx (by dchu917) is a local context manager for Claude Code and Codex that lets you save conversation context into named "workstreams," resume them cleanly across sessions, and branch from a saved state without leaking future changes back to the source. All state lives in a local SQLite database — no API keys, no hosted service.

Python-based, MIT, 68 stars, created April 13 2026.

## What it solves

Default Claude Code and Codex conversation handling has two chronic failures:

1. **Transcript drift.** Resuming "the last session" may pick up a newer conversation that happens to share the same repo, losing the original thread.
2. **No clean branching.** Starting a parallel line of work from the current state requires either duplicating the entire transcript or losing history.

ctx addresses both by binding each workstream to the *exact* Claude and/or Codex conversation IDs it came from. Later pulls stay on that conversation instead of jumping to the newest chat on disk. Branching creates a new workstream seeded from the saved state of another one, without sharing future transcript pulls.

## Workstream model

```
Claude Code chat          Codex chat
      |                      |
      v                      v
   /ctx ...               ctx ...
          \              /
           v            v
      +----------------------+
      | workstream: feature-audit |
      |   claude:  abc123    |
      |   codex:   def456    |
      +----------------------+
                 |
                 +--> feature-audit-v2 branch
```

Each workstream is tied to a repo and references 0 or more bound conversation IDs per provider. Entries (captured from `--pull`) are indexed for search. Curation is first-class: pin saved entries so they always load into future resumes, exclude entries so they stay searchable but stop getting passed to the model, or delete them entirely.

## Usage

**From Claude Code** (slash commands):
- `/ctx start feature-audit --pull` — create workstream, pull the current conversation into it.
- `/ctx resume feature-audit` — continue an existing workstream, append new context.
- `/ctx branch feature-audit feature-audit-v2` — create a new workstream seeded from the current saved state of another.
- `/ctx search dataset download` — search saved workstreams and entries.
- `/ctx curate my-stream` — open the curation UI.

**From Codex** (CLI — Codex doesn't support repo-defined slash commands):
- `ctx start my-stream --pull`
- `ctx resume my-stream --compress` (for smaller load pack)
- `ctx list --this-repo`, `ctx search ... --this-repo`
- `ctx web --open` — local browser UI for browsing, searching, and copying continuation commands.

## Install options

- `git clone && ./setup.sh` — project-local SQLite DB at `./.contextfun/context.db`, skill links into `~/.claude/skills` and `~/.codex/skills`.
- `./setup.sh --global` — pinned global release into `~/.contextfun`.
- `curl | bash` install script for global without cloning.
- `npx skills add` for the bootstrap skill only.
- Shell bootstrap via `source <(curl ... agent_bootstrap.sh)`.

## How it fits

This is the "workflow tool" side of LLM-agent infrastructure, distinct from:
- [[hazmat]] — sandboxing the agent's OS access
- [[bubblewrap-dev-env]] — Linux equivalent sandbox
- [[crabtrap]] — HTTP-layer policy enforcement
- [[charlie-daemons]] — autonomous background agents

ctx is about *user-directed agent sessions* — helping a human keep multiple threads of agent-assisted work distinct and recoverable. It solves a productivity problem, not a security problem.

The conversation-binding idea is the load-bearing part of the design: both Claude Code and Codex write transcripts to disk with no stable "this is the conversation I meant" handle, so a context manager that infers identity from "the newest transcript" is inherently fragile. Binding to explicit conversation IDs makes resume semantics robust.

## Repo

https://github.com/dchu917/ctx — 68 stars, MIT, Python. Docs in-repo.

## Related

- [[botctl]] — process manager for long-running autonomous Claude agents (adjacent but different problem: ctx is for interactive sessions, botctl is for unattended ones)
- [[bubblewrap-dev-env]], [[hazmat]], [[crabtrap]], [[charlie-daemons]] — the rest of the LLM-agent infrastructure cluster
- [[context-engineering]] — the broader concept of assembling the right prior state into an LLM's context