Skip to content

Getting Started with ctx

Context (ctx) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. Instead of re-explaining your codebase every time, context files let AI tools remember decisions, conventions, and learnings.

Why ctx?

Most AI-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

Context solves this by treating context as infrastructure: files that version with your code and persist across sessions.

Installation

Download pre-built binaries from the releases page.

curl -LO https://github.com/ActiveMemory/ctx/releases/latest/download/ctx-linux-amd64
chmod +x ctx-linux-amd64
sudo mv ctx-linux-amd64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/latest/download/ctx-linux-arm64
chmod +x ctx-linux-arm64
sudo mv ctx-linux-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/latest/download/ctx-darwin-arm64
chmod +x ctx-darwin-arm64
sudo mv ctx-darwin-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/latest/download/ctx-darwin-amd64
chmod +x ctx-darwin-amd64
sudo mv ctx-darwin-amd64 /usr/local/bin/ctx

Download ctx-windows-amd64.exe from the releases page and add it to your PATH.

Build from Source

Requires Go 1.22+:

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/

Verify installation:

ctx --version

Quick Start

1. Initialize Context

cd your-project
ctx init

This creates a .context/ directory with template files and configures AI tool hooks (for Claude Code).

2. Check Status

ctx status

Shows context summary: files present, token estimate, and recent activity.

3. Start Using with AI

With Claude Code, context loads automatically via hooks. For other tools, paste the output of:

ctx agent --budget 8000

4. Verify It Works

Ask your AI: "Do you remember?"

It should cite specific context: current tasks, recent decisions, or previous session topics.

What Gets Created

.context/
├── CONSTITUTION.md     # Hard rules — NEVER violate these
├── TASKS.md            # Current and planned work
├── DECISIONS.md        # Architectural decisions with rationale
├── LEARNINGS.md        # Lessons learned, gotchas, tips
├── CONVENTIONS.md      # Project patterns and standards
├── ARCHITECTURE.md     # System overview
├── DEPENDENCIES.md     # Key dependencies and why chosen
├── GLOSSARY.md         # Domain terms and abbreviations
├── DRIFT.md            # Staleness signals
├── AGENT_PLAYBOOK.md   # How AI agents should use this
└── sessions/           # Session snapshots

See Context Files for detailed documentation of each file.

Common Workflows

Add a Task

ctx add task "Implement user authentication"

Record a Decision

ctx add decision "Use PostgreSQL for primary database"

Note a Learning

ctx add learning "Mock functions must be hoisted in Jest"

Mark Task Complete

ctx complete "user auth"

Check for Stale Context

ctx drift

Next Steps