ctx

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2026 License: Apache-2.0

README

ctx

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

  1. File-based: No database, no daemon. Just markdown and convention.
  2. Git-native: Context versions with code, branches with code, merges with code.
  3. Human-readable: Engineers can read, edit, and understand context directly.
  4. Token-efficient: Markdown is cheaper than JSON/XML.
  5. 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

Apache 2.0

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/decision
Package decisions provides commands for managing DECISIONS.md.
 Package decisions 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
cli/learnings
Package learnings provides commands for managing LEARNINGS.md.
 Package learnings provides commands for managing LEARNINGS.md.
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/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
cli/session
Package session provides commands for managing session snapshots.
 Package session provides commands for managing session snapshots.
cli/status
cli/sync
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
config
context
Package context provides functionality for loading and managing .context/ files.
 Package context provides functionality for loading and managing .context/ files.
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 template files for initializing .context/ directories.
 Package tpl provides embedded template files for initializing .context/ directories.
validation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.