Version 3.2.2 • What's New
Externalize AI context. Enable human-AI collaboration. Perfect session continuity.
Built for all AI coding assistants. Optimized for Claude Code.
The AI Context System externalizes AI reasoning into visible, structured documentation that serves four critical purposes:
Never lose context between AI sessions. Pick up exactly where you left off—days, weeks, or months later—without re-explaining anything.
Make AI thoughts, decisions, and mental models visible to humans. Turn invisible AI reasoning into tangible documentation that programmers can read, review, and reference.
Enable programmers to work alongside AI agents with full visibility into the AI's thinking process, constraints, and decision rationale.
Facilitate peer review, project handoffs, and collaborative development between different AI agents—with complete context preservation.
Emergency patch fixing installer bugs blocking all upgrades
Critical Fixes:
- ✅ Deprecated command bug - Removed save-context.md causing 404 errors (100% upgrade failure)
- ✅ Version detection - Now shows actual version instead of blank
- ✅ Misleading error message - Fixed "success then failure" confusion in non-interactive mode
Impact:
- Upgrades now work reliably
- Clear success messaging
- Perfect non-interactive (--yes) support
Full details: CHANGELOG.md • Upgrade: /update-context-system
AI reasoning is invisible. Context is lost between sessions. Decisions lack rationale. Humans can't review AI's thinking. New AI agents must reverse-engineer everything. Collaboration breaks down.
Externalize AI context into structured, visible documentation:
/init-contextor/migrate-context- One-time setup/save(2-3 min) - Quick updates during work/save-full(10-15 min) - Comprehensive saves before breaks/handoffs/review-context- Verify continuity at session start
Everything AI thinks gets documented. No hidden context. Perfect session continuity. Full visibility for humans and AI agents.
Universal concepts work everywhere:
- File structure (
context/,SESSIONS.md,STATUS.md, etc.) - Documentation philosophy (externalize reasoning)
- Mental model capture
- Decision rationale
- Session continuity
Supported AI tools:
- Claude Code
- Cursor
- Aider
- GitHub Codex
- Any AI assistant with file system access
Claude-specific features:
- Slash commands -
/save,/save-full,/init-context, etc. (14 commands) - TodoWrite integration - Automatic capture of task state
- Interactive workflows - Approval checkpoints, validation prompts
- Command system - Structured
.claude/commands/architecture
Other AI tools:
- Can use the file structure and templates manually
- Can reference
cursor.md,aider.md, etc. (tool-specific headers) - Full access to externalized context
- Manual workflow (no slash commands)
Why Claude-optimized? This system was built using Claude Code through extensive dogfooding. The slash command system provides the best UX, but the core value—externalized context—works with any AI tool.
# Install from GitHub (downloads to current directory)
curl -sL https://raw.githubusercontent.com/rexkirshner/ai-context-system/main/install.sh | bash
# Initialize context
/init-context
# Daily workflow
/save # Quick update (2-3 min) - most sessions
/save-full # Comprehensive (10-15 min) - before breaks/handoffs# 1. Clone the repo
git clone https://github.com/rexkirshner/ai-context-system.git
# 2. Copy toolkit to your project
cp -r ai-context-system/.claude /path/to/your/project/
cp -r ai-context-system/scripts /path/to/your/project/
cp -r ai-context-system/templates /path/to/your/project/
# 3. In Claude Code, initialize
/init-context
# 4. Clean up (optional)
rm -rf ai-context-systemTry it now! See SETUP_GUIDE.md for complete instructions.
Core documentation (/init-context):
your-project/
├── .claude/ # Claude Code commands (optional for other AIs)
│ ├── commands/ # 14 slash commands
│ ├── docs/ # Comprehensive guides
│ └── checklists/ # Review criteria
├── scripts/
│ ├── save-full-helper.sh # Session template generator
│ ├── update-quick-reference.sh # Auto-generates Quick Reference
│ └── validate-context.sh # Documentation health check
├── context/ # ← EXTERNALIZED AI CONTEXT (visible to humans)
│ ├── .context-config.json # Project configuration
│ ├── claude.md # Claude Code entry point (7-line header)
│ ├── cursor.md # Cursor entry point (optional)
│ ├── aider.md # Aider entry point (optional)
│ ├── CONTEXT.md # Orientation (who/what/how/why)
│ ├── STATUS.md # Current state + auto-generated Quick Reference
│ ├── DECISIONS.md # Decision log (WHY choices were made)
│ └── SESSIONS.md # History (AI mental models + reasoning)
└── artifacts/ # Generated outputs
├── code-reviews/ # AI peer reviews
├── exports/ # Context exports for handoffs
└── [other analysis outputs]
Everything in context/ is externalized AI reasoning—visible to programmers, reviewable by humans, shareable across AI agents.
Additional files created on-demand:
CODE_MAP.md→ Project complexity increases (>20 files)PRD.md→ Product vision becomes complexARCHITECTURE.md→ System design needs comprehensive documentation
- Zero context loss - Resume exactly where you left off
- Work-in-progress preservation - Precise state capture with mental models
- Structured history - SESSIONS.md tracks every session's evolution
- Quick Reference - Auto-generated dashboard in STATUS.md
- Visible reasoning - AI decisions externalized to DECISIONS.md
- Mental models captured - AI's current understanding documented
- Constraints visible - Project limitations and tradeoffs documented
- Thought process preserved - How AI approached problems, not just solutions
- Full visibility - Programmers can read AI's reasoning
- Reviewable decisions - Humans can verify AI understood constraints
- Course-correction enabled - See when AI misunderstood, adjust quickly
- Shared mental models - Human and AI aligned on project understanding
- Peer review -
/code-reviewwith full context understanding - Seamless handoffs -
/export-contextpackages everything for new AI - Cross-tool compatibility - Works across Claude, Cursor, Aider, etc.
- Preserved rationale - New AI understands WHY, not just WHAT
- Single source of truth - No duplication, everything in one place
- Smart save commands -
/save(quick) vs/save-full(comprehensive) - Auto-generated Quick Reference - Extracted from config + current state
- Git operation audit trail - Auto-logged commits/pushes in SESSIONS.md
- Validation tools - Check documentation health and staleness
Note: These commands are universal and work with any AI coding assistant. They're organized in .claude/commands/ following Claude Code's slash command paradigm, but the workflows themselves are generalizable. Future versions will provide native support for other AI tools (Cursor, Aider, etc.). For now, other AI assistants can reference these command files directly to follow the same workflows.
Creates 5 core files: claude.md, CONTEXT.md, STATUS.md (with auto-generated Quick Reference), DECISIONS.md, SESSIONS.md. Optional files suggested when complexity demands. Start simple, grow naturally.
Migrates existing documentation to AI Context System structure. Preserves ALL existing content while organizing into context/ folder. Consolidates to single source of truth.
Quick save - run often (2-3 min)
Updates STATUS.md with auto-generated Quick Reference. Captures current tasks, blockers, next steps. Your safety net for session continuity.
Comprehensive save - run before breaks (10-15 min)
Everything /save does + SESSIONS.md entry with mental models and decision rationale. Auto-logs git operations. Essential for AI-to-AI handoffs.
Run at session start
Verifies documentation is current and accurate. Shows Quick Reference. Checks for version updates. Confirms you can resume exactly where you left off.
AI peer review with full context
Comprehensive code audit leveraging DECISIONS.md, SESSIONS.md, and STATUS.md for context-aware review. Identifies issues with understanding of constraints and rationale.
Package for AI-to-AI handoffs
Combines all context documentation into single markdown file. Perfect for project handoffs to new AI agents, team members, or cross-tool transitions.
Check documentation health
Validates all context files follow expected structure. Reports staleness (🟢🟡🔴), missing sections, and health score. Ensures context is ready for collaboration.
Updates slash commands and scripts from GitHub. Ensures you have latest features and fixes.
Compare your context files with latest templates. Interactive updates with visual diffs and automatic backups.
Who, what, how, why. Includes tech stack, architecture, communication preferences, anti-patterns. References other files instead of duplicating.
Purpose: Project overview for any AI agent or human taking over.
Single source of truth for "what's happening now." Includes auto-generated Quick Reference (project overview, URLs, tech stack), current phase, active tasks, blockers, next session start point.
Purpose: Fast orientation for session continuity and handoffs.
WHY choices were made. Includes technical decisions with rationale, alternatives considered, constraints and tradeoffs, when to reconsider.
Purpose: Enable AI agents to understand reasoning, not just code. Critical for peer review and takeovers.
What happened when. Includes mandatory TL;DR, structured entries, what changed, decisions, files, AI mental models, problem-solving approaches, auto-logged git operations.
Purpose: AI agents learn from problem-solving patterns, understand evolution, review decision history. Externalized AI reasoning visible to humans.
1. Install AI Context System
2. /init-context
3. Start coding
4. /save (frequently)
5. /save-full (at session end)
1. /save-full (capture current mental model)
2. /validate-context (ensure completeness)
3. /export-context (package everything)
4. Share export with new AI agent
5. New AI reads context/ folder for full understanding
1. Open context/DECISIONS.md (see WHY AI made choices)
2. Check SESSIONS.md (see AI's reasoning process)
3. Review STATUS.md (understand current state)
4. Verify AI understood project constraints
1. Open project
2. /review-context (see Quick Reference + verify continuity)
3. Start coding
4. /save (frequently - 2-3 min quick updates)
5. /save-full (at end of session - 10-15 min comprehensive)
1. /save-full (ensure context is current)
2. /code-review (AI reviews with full context)
3. Review artifacts/code-reviews/ output
4. Address issues in new session
This system is successful when:
Session Continuity:
"I can end any session abruptly, start days later, run /review-context, and continue exactly where I left off."
Externalized Context:
"I can read DECISIONS.md and SESSIONS.md and understand exactly what the AI was thinking and why."
Human-AI Collaboration:
"I can verify the AI understood my constraints by reading its documented reasoning."
AI-to-AI Collaboration:
"A new AI agent can read context/ and understand the entire project history, decisions, and current mental model."
Each project gets a .context-config.json with:
- Workflow preferences
- Documentation settings
- Command configuration
- Communication style
- Project type (single-repo, meta-project, etc.)
Customize per project or use defaults. Full schema: config/context-config-schema.json
For Claude Code users (full features):
- Claude Code CLI
- File system access
For other AI tools (manual workflow):
- Any AI coding assistant with file system access
- Manual use of templates and file structure
- Reference appropriate tool header (cursor.md, aider.md, etc.)
Universal:
- Any project (language/framework agnostic)
- Git recommended (but not required - works with timestamp-based detection)
- Externalize everything - AI thoughts, decisions, mental models → visible documentation
- Save often - Run
/savefrequently (2-3 min quick updates) - Full saves at boundaries - Run
/save-fullbefore breaks, handoffs (10-15 min) - Review at start - Always
/review-contextwhen opening project - Validate before handoffs - Run
/validate-contextbefore AI-to-AI transitions - Read the externalized context - DECISIONS.md and SESSIONS.md show AI reasoning
- Trust the system - It captures more AI context than you think
Commands not working?
⚠️ CRITICAL: Check for multiple.claudedirectories- Claude Code may be loading commands from a parent folder
- Solution: Only keep
.claudein the actual project root - Exception: Meta-projects intentionally have multiple
.claudedirs
Context feels stale?
- Run
/saveimmediately - Check STATUS.md Quick Reference for overview
- Check SESSIONS.md for last update
Can't resume work?
- Run
/review-contextto see Quick Reference - Check STATUS.md → Work In Progress section
- Check SESSIONS.md last entry for mental model
See SETUP_GUIDE.md for detailed troubleshooting.
Current Version: 3.2.2 Status: Production Ready Last Updated: 2025-10-23
What's New in v3.2.2:
- Fixed critical installer bug blocking all upgrades (save-context.md 404)
- Fixed version detection showing blank
- Fixed misleading error messages in non-interactive mode
- Installer now works reliably with --yes flag
See: CHANGELOG.md for complete version history
This system externalizes AI reasoning—making it visible, reviewable, and shareable. You're welcome to:
- Fork and adapt for your workflow
- Suggest improvements via issues
- Share your adaptations
- Contribute templates for other AI tools
Use freely for personal or commercial projects.
One-command install:
curl -sL https://raw.githubusercontent.com/rexkirshner/ai-context-system/main/install.sh | bashThen:
/init-context # Create your context structure
/save # Experience session continuitySee also:
- SETUP_GUIDE.md - Complete installation and usage
- CHANGELOG.md - Version history
- MIGRATION_GUIDE_v2_to_v3.md - Migration from v2.x
Remember: When in doubt, /save!
Your AI's thoughts are valuable. Externalize them.