v0.6.0

Context CLI v0.6.0

This release replaces shell hook scripts with native Go subcommands and ships hooks and skills as a Claude Code plugin. ctx init is now tool-agnostic: it no longer scaffolds .claude/hooks/ or .claude/skills/. The plugin model eliminates the jq dependency, enables go test coverage for all hook logic, and makes distribution a single install command.

Canonical Release Narrative

ctx v0.6.0: The Integration Release

Highlights

• Plugin-based Distribution: Hooks and skills ship as a Claude Code plugin. Install with /plugin marketplace add ActiveMemory/ctx then /plugin install ctx@activememory-ctx. No build step required; the plugin is served directly from source.
• Shell Hooks to Go Subcommands: All 6 shell scripts replaced by ctx system * commands compiled into the binary. Zero external dependencies.
• Obsidian Vault Export: ctx journal obsidian generates a full Obsidian vault from enriched journal entries with wikilinks, MOC pages, and graph-optimized cross-linking.
• Encrypted Scratchpad: ctx pad provides a git-friendly encrypted scratchpad (AES-256-GCM) for sensitive one-liners that travel with the project.
• Security Hardening: Path boundary validation, symlink detection, and user-specific temp directories close the medium-severity findings from the security audit.

Breaking Changes

• ctx init no longer creates .claude/hooks/ or .claude/skills/. Install the ctx plugin instead.
• ctx hook claude-code now prints plugin install instructions instead of generating shell scripts.
• Version jumps from 0.3.0 to 0.6.0 to signal the magnitude of the plugin conversion.

Features

• Add ctx system subcommands: check-context-size, check-persistence, check-journal, post-commit, block-non-path-ctx, cleanup-tmp
• Add Claude Code plugin with marketplace.json, hooks.json, and 25 skills
• Serve plugin directly from internal/tpl/claude/; eliminate make plugin build step
• Add ctx journal obsidian command with wikilink conversion, frontmatter transformation, MOC generation, and related-sessions footer
• Add ctx pad command suite: show, edit, clear, edit --append, edit --prepend
• Add ctx permissions snapshot and ctx permissions restore for settings.local.json management
• Add allow_outside_cwd option to .contextrc for path boundary override
• Add ctx init auto-append of recommended .gitignore entries
• Add Context.File() lookup method for programmatic context file access
• Add journal reminder hook detecting unexported sessions and unenriched entries
• Add SessionEnd cleanup hook removing stale temp files
• Add persistence nudge hook with adaptive frequency based on prompt count
• Add /check-links skill for dead link auditing
• Add /ctx-pad skill for scratchpad interaction
• Add /ctx-worktree skill for parallel agent development with git worktrees
• Add /ctx-borrow skill for extracting and applying deltas between project copies
• Add /sanitize-permissions skill for settings.local.json security auditing

Bug Fixes

• Hooks no longer create partial .context/ (logs only) before ctx init runs
• ctx init treats .context/ with only logs as uninitialized; skips overwrite prompt
• Fix CodeQL int64-to-int truncation warning in persistence state parser
• Fix UTF-8 safe string truncation preventing mid-rune splits
• Fix 18 golangci-lint issues across pad, compact, crypto, and validation packages
• Fix hook output channels: stderr is invisible for UserPromptSubmit hooks
• Fix outdated context-update XML syntax in docs
• Remove all stale session/save references from docs, skills, and source

Security

• Add path boundary validation on --context-dir / CTX_DIR preventing operations outside project root (M-1)
• Add symlink detection with Lstat() before file read/write in .context/ (M-2)
• Use $XDG_RUNTIME_DIR/ctx or user-specific temp subdirectory for state files (M-3)
• Add /sanitize-permissions skill for auditing dangerous Bash permissions

Refactoring

• Split config/tpl.go (349 lines) into 4 feature-area files
• Convert formatToolUse switch to dispatch map
• Move 6 utility functions from recall/run.go to recall/fmt.go
• Extract findSessions() and deployHookScript() helpers to reduce duplication
• Unify task archiving into compact.WriteArchive helper
• Fix stale godocs and add doc.go for 6 packages
• Update internal/tpl package doc to reflect dual purpose (templates + plugin assets)

Documentation

• Add migration guide for upgrading from shell hooks to plugin model
• Add first-session walkthrough with end-to-end interaction examples
• Add agent security docs and defense-in-depth blog post
• Add scratchpad docs, recipes, and autonomous loop hardening guide
• Add agent team decision framework recipe
• Reorder docs nav: promote recipes, demote adopting/upgrading
• Add recipe TL;DR admonitions for long recipes
• Add cross-references between blog posts and documentation pages
• 8 new blog posts covering skills anatomy, IRC bouncers, worktrees, and more

---

Full changelog: v0.3.0...v0.6.0

---

Below is the auto-generated release notes:

What's Changed

• fix: UTF-8 safe string truncation by @usirin in #12
• fix: add required flags to decision example in quickstart by @doguhanniltextra in #13
• ctx v0.6.0: Convert shell hooks to Go plugin by @josealekhine in #14

New Contributors

• @usirin made their first contribution in #12
• @doguhanniltextra made their first contribution in #13

Full Changelog: v0.3.0...v0.6.0

v0.3.0

Context CLI v0.3.0

This release is a major evolution in how ctx works with AI agents. Slash commands are replaced by a full Agent Skills system, a new autonomous mode (--ralph) enables unattended operation, and a comprehensive suite of hooks keeps context healthy during long sessions. Under the hood, two consolidation sweeps eliminated magic strings, deshadowed variables, and split large files into focused modules.

Canonical Release Narrative

ctx v0.3.0: The Discipline Release

Highlights

• Agent Skills System: All 21 slash commands migrated to directory-based skills following the agentskills.io spec, each with frontmatter, quality gates, usage examples, and "When NOT to Use" triggers
• Autonomous Loop Mode: ctx init --ralph creates PROMPT.md and IMPLEMENTATION_PLAN.md configured for independent agent operation without clarifying questions
• Context Health Hooks: New UserPromptSubmit hooks for context size checkpoints, backup staleness warnings, and a deployed context-watch.sh monitor tool
• Code Consolidation: Two systematic sweeps replaced magic strings/numbers with constants, deshadowed variables across all packages, and split large files (journal/site.go into 12 files, recall/export.go into 4 files)

Features

• Convert all .claude/commands/*.md to .claude/skills/*/SKILL.md directory structure with structured frontmatter
• Add ctx init --ralph flag for autonomous agent mode with dedicated PROMPT.md template
• Add context size checkpoint hook (check-context-size.sh) with adaptive reminder cadence (silent for 15 prompts, then every 5th, then every 3rd)
• Add ctx-context-monitor skill teaching agents how to respond to checkpoint signals
• Deploy context-watch.sh to .context/tools/ via ctx init for all users
• Add backup staleness hook (check-backup-age.sh) warning when backups are >2 days old
• Add global backup support (hack/backup-global.sh) for ~/.claude/ with make backup-global
• Add /consolidate skill with 9 project-specific drift checks
• Add /brainstorm skill for design-before-implementation workflow
• Add ctx agent --cooldown and --session flags with tombstone debounce
• Add "Update When" triggers to all context file templates (CONSTITUTION, TASKS, CONVENTIONS, etc.)
• Add Anti-Patterns section to AGENT_PLAYBOOK.md (Stale Context, Context Sprawl, Implicit Context, etc.)
• Deploy Makefile.ctx template via ctx init (amend, never overwrite)
• Add journal site /files/ index with popular/long-tail split
• Add journal site /types/ pages grouping sessions by type
• Change ctx recall export default to update mode preserving YAML frontmatter (--skip-existing for old behavior, --force for full overwrite)
• Add 7 deterministic normalize scripts for journal fence/metadata repair
• Add ctx-journal-normalize skill for clean journal site rendering

Bug Fixes

• Fix all 137 journal files: complete fence reconstruction (8 broken files with stray markers)
• Fix consolidateToolRuns root cause: (xN) on its own line creating broken fences
• Fix session export reliability and browser performance
• Resolve all golangci-lint v2 errcheck and staticcheck warnings
• Remove unnecessary nl parameter in recall/fmt.go
• Fix task insertion placement in TASKS.md
• Restore release-notes and release skills dropped during commands-to-skills migration

Refactoring

• Replace magic strings/numbers with config constants (ExtJSONL, IssueType*, DefaultSessionFilename, ClaudeField*, session headings, template strings)
• Deshadow err/ok variables with descriptive names across drift, recall, session, task, context, and validation packages
• Split journal/site.go into 12 focused files; split recall/export.go into 4 files
• Extract error constructors to err.go files
• Move Claude raw types to types.go with project-standard godoc
• Extract hook matcher into internal/claude/matcher.go
• Simplify defer file.Close() patterns
• Replace cmd.Printf("\n") with cmd.Println(fmt.Sprintf(...))

CI

• Upgrade to golangci-lint v2 for CI compatibility
• Fix goinstall mode removal and v2 security warnings

Documentation

• Add architecture docs and remove DRIFT.md (superseded by /consolidate skill)
• Add quick-reference table to CLI reference
• Add copyright headers to normalize scripts
• Add 3 blog posts: "The Attention Budget", "You Can't Import Expertise", "The Anatomy of a Skill That Works"
• Add blog post topic frontmatter to all 6 existing posts
• Add journal pipeline docs (session-journal.md)

---

Full changelog: v0.2.0...v0.3.0

v0.2.0

Context CLI v0.2.0

This release brings significant improvements to session recall, code quality, and documentation. The new journal system enables AI-powered analysis of exported sessions, while extensive refactoring consolidates configuration constants and adds thread safety throughout the codebase.

Canonical Release Narrative

ctx v0.2.0: The Archaeology Release

Highlights

• Session Recall & Journal System: Browse, search, and export AI session history with ctx recall, then analyze sessions with ctx journal
• Quick Reference Indexes: DECISIONS.md and LEARNINGS.md now include auto-generated indexes for faster scanning
• Improved CLI Flags: Global --context-dir and --no-color flags, plus required structured flags for decisions and learnings
• Code Quality: Consolidated configuration constants, thread-safe runtime config, and comprehensive test coverage

Features

• Add ctx recall command for browsing AI session history across projects
• Add ctx journal command with site generation for session analysis
• Add quick reference index to DECISIONS.md and LEARNINGS.md with ctx decisions reindex and ctx learnings reindex
• Add global flags: --context-dir to override context directory, --no-color to disable colored output
• Add .contextrc configuration file support for project-level settings
• Add structured attributes to <context-update> XML format for richer metadata
• Require --context, --rationale, --consequences flags for ctx add decision
• Require --context, --lesson, --application flags for ctx add learning
• Add shell completion support via ctx completion (bash, zsh, fish, powershell)

Bug Fixes

• Fix ctx tasks archive to handle nested content correctly
• Fix shell script linter warnings in release and tag scripts

Refactoring

• Consolidate hardcoded strings into config constants (file names, env vars, Claude API types)
• Add thread safety with RWMutex for runtime configuration
• Extract shared helpers to eliminate code duplication (ReindexFile, ScanDirectory)
• Rename internal/templates to internal/tpl
• Use iota for enum-like constants
• Add CRLF-aware newline handling

Documentation

• Add security page with vulnerability reporting guidelines
• Add version history page with release documentation links
• Update demo project with AGENT_PLAYBOOK.md, LEARNINGS.md, and specs examples
• Standardize Go docstrings with Parameters/Returns/Fields sections
• Add CLI output convention (use cmd.Print* instead of fmt.Print*)
• Document ctx completion command and --all-projects flag for recall commands

Dependencies

• Bump golangci/golangci-lint-action from 6 to 9
• Bump actions/setup-go from 5 to 6
• Bump actions/checkout from 4 to 6

---

Full changelog: v0.1.2...v0.2.0

---

Below is autogenerated release notes:

What's Changed

• deps: Bump actions/setup-go from 5 to 6 by @dependabot[bot] in #2
• deps: Bump golangci/golangci-lint-action from 6 to 9 by @dependabot[bot] in #3
• deps: Bump actions/checkout from 4 to 6 by @dependabot[bot] in #1
• Cleanup (part one) before release cut. by @josealekhine in #4
• cleanup before v0.2.0 release cut. by @josealekhine in #5

New Contributors

• @dependabot[bot] made their first contribution in #2
• @josealekhine made their first contribution in #4

Full Changelog: v0.1.2...v0.2.0

v0.1.2

Context CLI v0.1.2

This release improves the out-of-box experience for new users by automatically
configuring Claude Code permissions during ctx init. It also adds a new
Prompting Guide to help users get the most out of AI-assisted workflows.

Highlights

• ctx init now pre-seeds all required permissions for /ctx-* slash commands
• New Prompting Guide documentation with effective prompts for AI sessions
• Added make site-setup, make site, and make site-serve targets

Features

• Automatic permission configuration: ctx init now adds Bash(ctx status:*),
  Bash(ctx agent:*), Bash(ctx add:*), Bash(ctx session:*), Bash(ctx tasks:*),
  and Bash(ctx loop:*) to .claude/settings.local.json. Permissions are merged
  additively to preserve any existing user customizations.

Documentation

• Prompting Guide: New documentation page with effective prompts for working
  with AI assistants in ctx-enabled projects. Covers session start, debugging,
  reflection, and exploration patterns.
• Added Makefile targets for documentation site management (site-setup, site,
  site-serve)

---

Full changelog: v0.1.1...v0.1.2

v0.1.1

Context CLI v0.1.1

This release focuses on stability improvements and better Claude Code integration. Key fixes address JSON settings handling and hook configuration, while new features include a session reflection command and improved documentation.

Highlights

• Fixed JSON unicode escaping issues in settings.local.json
• Corrected Claude Code hook schema keys for proper integration
• Added /ctx-reflect slash command for session reflection
• New comparison documentation page for evaluating Context against alternatives

Features

• Session Reflection Command: New /ctx-reflect slash command helps AI agents reflect on sessions and suggest what context to persist
• Proactive Context Persistence: Added task lifecycle timestamps and improved context persistence workflows
• Template Consolidation: Reorganized Claude templates under internal/templates/ for better maintainability

Bug Fixes

• JSON Unicode Escaping: Fixed issue where settings.local.json incorrectly escaped unicode characters
• Hook Schema Keys: Corrected Claude Code hook configuration to use proper schema keys
• Init Command: Fixed ctx init to insert content after H1 heading instead of appending to end
• Deferred Error Handling: Properly check error return of os.Chdir in defer statements

Documentation

• Added comparison page documenting how Context compares to alternative solutions
• Improved mental model section and formatting in AGENT_PLAYBOOK
• Added learnings about JSON unicode escaping and Claude Code hook schema keys

CI/CD

• Added Dependabot configuration for automated dependency updates
• Set CTX_SKIP_PATH_CHECK=1 for tests to improve CI reliability
• Build golangci-lint from source to support Go 1.25

---

Full changelog: v0.1.0...v0.1.1

v0.1.0

Context CLI v0.1.0

Initial release of the Context CLI (ctx) - a tool for persistent AI context management.

What's New

This is the first stable release of ctx, providing:

• Context Management: Create and maintain .context/ directories with structured markdown files
• AI Integration: Built-in support for Claude Code with hooks and slash commands
• Session Persistence: Automatic session saving and transcript management
• Drift Detection: Track staleness of context files
• Multi-tool Support: Integration guides for Claude Code, Cursor, Aider, Copilot, and Windsurf

Installation

Linux (x86_64)

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

Linux (ARM64)

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

macOS (Apple Silicon)

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

macOS (Intel)

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

Windows

Download ctx-0.1.0-windows-amd64.exe or ctx-0.1.0-windows-arm64.exe and add to your PATH.

Verifying Checksums

Each binary has a .sha256 file. Verify with:

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.1.0/ctx-0.1.0-linux-amd64.sha256
sha256sum -c ctx-0.1.0-linux-amd64.sha256

Quick Start

# Initialize context in your project
ctx init

# Check context status
ctx status

# Get AI-ready context packet
ctx agent --budget 4000

Documentation

Full documentation available at ctx.ist

Checksums

Each binary has a corresponding .sha256 file for verification.