README
¶
ctx (Context)
Context is a system, not a prompt.
A lightweight, file-based system that enables AI coding assistants to persist, structure, and rehydrate project context across sessions.
ctx works with any AI tool that can read files; no model or
vendor lock-in.
Full documentation: ctx.ist
The Problem
Most LLM-driven development fails not because models are weak: They fail because context is ephemeral. Every new session starts near zero:
- You re-explain architecture
- The AI repeats past mistakes
- Decisions get rediscovered instead of remembered
The Solution
ctx treats context as infrastructure:
- Persist: Tasks, decisions, learnings survive session boundaries
- Reuse: Decisions don't get rediscovered; lessons stay learned
- Align: Context structure mirrors how engineers actually think
- Integrate: Works with any AI tool that can read files
Here's what that looks like in practice:
❯ "Do you remember?"
● Yes. The PreToolUse hook runs ctx agent, and CLAUDE.md tells me to
check .context/sessions/. I'll have context.
❯ "Summarize all sessions we have had so far?"
● Yes. I can ls .context/sessions/ and read each file:
- 2025-01-20: The meta-experiment that started it all
- 2025-01-21: The ctx rename + Claude hooks session
That's the whole point: Temporal continuity across sessions.
Installation
Download pre-built binaries from the releases page, or build from source:
git clone https://github.com/ActiveMemory/ctx.git
cd ctx
CGO_ENABLED=0 go build -o ctx ./cmd/ctx
sudo mv ctx /usr/local/bin/
See installation docs for platform-specific instructions.
Quick Start
# Initialize context directory in your project
ctx init
# Check context status
ctx status
# Get an AI-ready context packet
ctx agent --budget 4000
# Add tasks, decisions, learnings
ctx add task "Implement user authentication"
ctx add decision "Use PostgreSQL for primary database"
ctx add learning "Mock functions must be hoisted in Jest"
Documentation
| Guide | Description |
|---|---|
| Getting Started | Installation, quick start, first steps |
| CLI Reference | All commands and options |
| Context Files | File formats and structure |
| Integrations | Claude Code, Cursor, Aider setup |
| Ralph Loop | Autonomous AI development workflows |
Design Philosophy
- File-based: No database, no daemon. Just markdown and convention.
- Git-native: Context versions with code, branches with code, merges with code.
- Human-readable: Engineers can read, edit, and understand context directly.
- Token-efficient: Markdown is cheaper than JSON/XML.
- Tool-agnostic: Works with Claude Code, Cursor, Aider, Copilot, or raw CLI.
Contributing
Contributions welcome. See CONTRIBUTING.md for guidelines.
All commits must be signed off (git commit -s) to certify the
DCO.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ctx
command
package main is the main entry point of the app.
|
package main is the main entry point of the app. |
|
internal
|
|
|
bootstrap
Package bootstrap initializes the ctx CLI application.
|
Package bootstrap initializes the ctx CLI application. |
|
claude
Package claude provides Claude Code integration templates and utilities.
|
Package claude provides Claude Code integration templates and utilities. |
|
cli/add
Package add provides the "ctx add" command for appending entries to context files.
|
Package add provides the "ctx add" command for appending entries to context files. |
|
cli/agent
Package agent implements the "ctx agent" command for generating AI-ready context packets.
|
Package agent implements the "ctx agent" command for generating AI-ready context packets. |
|
cli/compact
Package compact implements the "ctx compact" command for cleaning up and consolidating context files.
|
Package compact implements the "ctx compact" command for cleaning up and consolidating context files. |
|
cli/complete
Package complete implements the "ctx complete" command for marking tasks as done in TASKS.md.
|
Package complete implements the "ctx complete" command for marking tasks as done in TASKS.md. |
|
cli/drift
Package drift implements the "ctx drift" command for detecting stale or invalid context.
|
Package drift implements the "ctx drift" command for detecting stale or invalid context. |
|
cli/hook
Package hook implements the "ctx hook" command for generating AI tool integration configurations.
|
Package hook implements the "ctx hook" command for generating AI tool integration configurations. |
|
cli/initialize
Package initcmd implements the "ctx init" command for initializing a .context/ directory with template files.
|
Package initcmd implements the "ctx init" command for initializing a .context/ directory with template files. |
|
cli/load
Package load provides the command for outputting assembled context.
|
Package load provides the command for outputting assembled context. |
|
cli/loop
Package loop provides the command for generating Ralph loop scripts.
|
Package loop provides the command for generating Ralph loop scripts. |
|
cli/session
Package session provides commands for managing session snapshots.
|
Package session provides commands for managing session snapshots. |
|
cli/task
Package task implements the "ctx tasks" command for managing task archival and snapshots.
|
Package task implements the "ctx tasks" command for managing task archival and snapshots. |
|
context
Packages context provides functionality for loading and managing .context/ files.
|
Packages context provides functionality for loading and managing .context/ files. |
|
drift
Packages drift provides functionality for detecting stale or invalid context.
|
Packages drift provides functionality for detecting stale or invalid context. |
|
templates
Package templates provides embedded template files for initializing .context/ directories.
|
Package templates provides embedded template files for initializing .context/ directories. |
Click to show internal directories.
Click to hide internal directories.