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
read the context files. I have context.
❯ "What have we been working on recently?"
● Yes. I can run ctx recall list and review recent activity:
- 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" \
--context "Need a reliable database for production workloads" \
--rationale "PostgreSQL offers ACID compliance, JSON support, and team familiarity" \
--consequences "Team needs PostgreSQL training; must set up replication"
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 |
Manifesto
Creation, not code. Context, not prompts. Verification, not vibes.
ctx is infrastructure for preserving intent under scale. Without durable
context, intelligence resets. With ctx, creation compounds.
Read the full Manifesto | ctx.ist/manifesto
Contributing
Contributions welcome. See CONTRIBUTING.md for guidelines.
All commits must be signed off (git commit -s) to certify the
DCO.
Community
Open source is better together.
Join the community to ask questions, share feedback, and connect with other users:
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 types and utilities.
|
Package claude provides Claude Code integration types 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/decision
Package decision provides commands for managing DECISIONS.md.
|
Package decision provides commands for managing DECISIONS.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 initialize implements the "ctx init" command for initializing a .context/ directory with template files.
|
Package initialize implements the "ctx init" command for initializing a .context/ directory with template files. |
|
cli/journal
Package journal implements the "ctx journal" command for analyzing and publishing exported AI session files.
|
Package journal implements the "ctx journal" command for analyzing and publishing exported AI session files. |
|
cli/learnings
Package learnings implements the "ctx learnings" command for managing LEARNINGS.md and its quick-reference index.
|
Package learnings implements the "ctx learnings" command for managing LEARNINGS.md and its quick-reference index. |
|
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/pad
Package pad implements the "ctx pad" command for managing an encrypted scratchpad.
|
Package pad implements the "ctx pad" command for managing an encrypted scratchpad. |
|
cli/permissions
Package permissions implements the "ctx permissions" command for managing Claude Code permission snapshots.
|
Package permissions implements the "ctx permissions" command for managing Claude Code permission snapshots. |
|
cli/recall
Package recall provides CLI commands for browsing and searching AI session history.
|
Package recall provides CLI commands for browsing and searching AI session history. |
|
cli/serve
Package serve implements the "ctx serve" command for serving static sites locally.
|
Package serve implements the "ctx serve" command for serving static sites locally. |
|
cli/status
Package status implements the "ctx status" command for displaying context health and summary information.
|
Package status implements the "ctx status" command for displaying context health and summary information. |
|
cli/sync
Package sync implements the "ctx sync" command for reconciling context files with codebase changes.
|
Package sync implements the "ctx sync" command for reconciling context files with codebase changes. |
|
cli/system
Package system provides hidden subcommands that implement Claude Code hook logic as native Go binaries, replacing the shell scripts previously deployed to .claude/hooks/.
|
Package system provides hidden subcommands that implement Claude Code hook logic as native Go binaries, replacing the shell scripts previously deployed to .claude/hooks/. |
|
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. |
|
cli/watch
Package watch implements the "ctx watch" command for processing structured context-update commands from AI output.
|
Package watch implements the "ctx watch" command for processing structured context-update commands from AI output. |
|
config
Package config provides configuration constants, regex patterns, and entry type definitions used across the ctx codebase.
|
Package config provides configuration constants, regex patterns, and entry type definitions used across the ctx codebase. |
|
context
Package context provides functionality for loading and managing .context/ files.
|
Package context provides functionality for loading and managing .context/ files. |
|
crypto
Package crypto provides AES-256-GCM encryption for the scratchpad.
|
Package crypto provides AES-256-GCM encryption for the scratchpad. |
|
drift
Package drift provides functionality for detecting stale or invalid context.
|
Package drift provides functionality for detecting stale or invalid context. |
|
index
Package index provides index generation and parsing for context files.
|
Package index provides index generation and parsing for context files. |
|
rc
Package rc provides runtime configuration loading from .contextrc files.
|
Package rc provides runtime configuration loading from .contextrc files. |
|
recall/parser
Package parser provides JSONL session file parsing for the recall system.
|
Package parser provides JSONL session file parsing for the recall system. |
|
task
Package task provides task item parsing and matching.
|
Package task provides task item parsing and matching. |
|
tpl
Package tpl provides embedded assets for ctx: .context/ templates stamped by "ctx init" and the Claude Code plugin (skills, hooks, manifest) served directly from claude/.
|
Package tpl provides embedded assets for ctx: .context/ templates stamped by "ctx init" and the Claude Code plugin (skills, hooks, manifest) served directly from claude/. |
|
validation
Package validation provides input sanitization and validation utilities.
|
Package validation provides input sanitization and validation utilities. |
Click to show internal directories.
Click to hide internal directories.