@jenishk29/ai-context-manager

The fastest way to hand off AI context — generate rich project snapshots for ChatGPT, Claude, Gemini, Copilot, and any other AI tool. Never lose context when switching models or starting a new session.

npm install -g @jenishk29/ai-context-manager
acm snapshot   # → HANDOFF.md in seconds

Table of Contents

• Why
• Install
• Quick Start
• CLI Commands
  • acm init
  • acm snapshot
  • acm stats
  • acm validate
  • acm doctor
• Configuration
• Library API
• Environment Variables
• Contributing
• License

Why

Every time you switch AI tools or hit a context limit, you lose momentum. Copy-pasting files and re-explaining your project wastes time.

acm snapshot generates a single comprehensive handoff file containing:

• 📁 Directory tree — full project structure
• 🔀 Git context — branch, recent commits, status
• 🧩 Stack detection — auto-detected technologies
• ✅ Progress tracking — what's done, in progress, and next
• 🎯 Active task — exactly what you're working on
• 📄 Relevant files — embedded code your AI needs
• 🔒 Secret scanning — never accidentally leak credentials
• 🔢 Token estimate — know the size before you paste

Paste it into any AI. Zero re-explaining.

Install

Global (recommended — enables acm CLI)

npm install -g @jenishk29/ai-context-manager

Both acm and ai-context-manager are available as commands. Use acm — it's faster to type.

acm --version
acm --help

Local (library / programmatic use)

npm install @jenishk29/ai-context-manager

Requirements: Node.js ≥ 18.0.0

Quick Start

# 1. Install globally
npm install -g @jenishk29/ai-context-manager

# 2. Go to your project
cd my-project

# 3. Initialize (once per project)
acm init

# 4. Fill in .ai-context-manager.json — add your current task & progress

# 5. Generate handoff file
acm snapshot

# 6. Paste HANDOFF.md into your AI and keep working instantly

CLI Commands

acm init

Initialize AI Context Manager in your project. Auto-detects stack and project name.

acm init                 # interactive
acm init -y              # accept all defaults (CI-friendly)
acm init --force         # overwrite existing config

Creates .ai-context-manager.json at your project root. Commit this file — it's how your team shares context state. The generated .ai-context-manager/ directory (handoff files) is git-ignored automatically.

Output:

Initializing AI Context Manager...

Detecting project stack...
✔ Detected: node, typescript, react
  Project name: my-app

✔ Created .ai-context-manager.json
✔ Created .ai-context-manager/ directory
✔ Added .ai-context-manager/ to .gitignore

Setup complete!

Next steps:
   1. Edit .ai-context-manager.json to add your progress & context
   2. Run acm snapshot to generate a handoff file
   3. Paste the handoff into your new AI session

acm snapshot

Generate the AI handoff file. The core command.

acm snapshot                          # generates HANDOFF.md + HANDOFF.json
acm snapshot --copy                   # also copies to clipboard instantly
acm snapshot --dry-run                # preview without writing files
acm snapshot -o docs/handoff.md      # custom output path
acm snapshot --format md             # markdown only
acm snapshot --format json           # json only
acm snapshot --format both           # both (default)
acm snapshot --force                 # skip secret-scan warnings

Options:

| Flag | Alias | Default | Description | |------|-------|---------|-------------| | --output | -o | HANDOFF.md | Output file path | | --format | | both | md, json, or both | | --copy | | false | Copy output to clipboard | | --dry-run | | false | Preview without writing files | | --force | -f | false | Skip secret-scan block |

Generated snapshot includes:

# AI Handoff — my-app
Generated: 2026-03-03T06:00:00Z  |  Tokens: ~3,200

## Project
Stack: node · typescript · react

## Progress
✅ Completed: User auth, DB schema
🔄 In Progress: Payment integration
📋 Next: Email notifications

## Active Task
Implement Stripe payment flow
Files: src/payments/stripe.ts, src/api/checkout.ts

## Directory Tree
my-app/
├── src/
│   ├── payments/

## Git Context
Branch: feature/stripe  |  Last commit: "Add checkout endpoint"

Secret scanning is automatic. The command blocks on critical secrets (API keys, tokens, private keys) and warns on suspicious patterns. Use --force to override at your own risk.

acm stats

Show snapshot history and token usage.

acm stats                # summary + recent snapshots
acm stats --last 5       # show last 5 only
acm stats --json         # raw JSON output (pipe-friendly)

Output:

AI Context Manager Statistics

   Total snapshots:         24
   Total tokens generated:  78,400
   Last snapshot:           3/3/2026, 11:52:00 AM
   Avg tokens per snapshot: 3,267

Recent snapshots:
  Date                     Tokens    Lines
  ────────────────────────────────────────
  3/3/2026, 11:52:00 AM    3,267      412

acm validate

Validate your .ai-context-manager.json config file.

acm validate

Checks:

• ✅ Valid JSON syntax
• ✅ Schema compliance
• ✅ All relevantFiles paths exist on disk
• ⚠️ Warns if progress fields are empty
• ⚠️ Warns if active task description is missing
• ⚠️ Warns if project name is unset

acm doctor

Full health check on your setup.

acm doctor

Output:

AI Context Manager Doctor

  ✔ Node.js version: 20.11.0
  ℹ Platform: darwin arm64
  ✔ Config file found: .ai-context-manager.json
  ✔ Config file is valid JSON and passes schema validation
  ✔ All 3 relevant files exist and are valid
  ✔ .ai-context-manager/ directory exists
  ✔ .ai-context-manager/ is writable
  ✔ Disk space: 142,311 MB available
  ✔ Git is available
  ✔ Project is a git repository
  ✔ .ai-context-manager/ is in .gitignore

11 passed, 0 failed, 0 warnings

Configuration

.ai-context-manager.json lives at your project root and drives every snapshot.

{
  "schemaVersion": "1.0",
  "project": {
    "name": "my-app",
    "stack": ["node", "typescript", "react"],
    "description": "AI-powered productivity app",
    "environment": {
      "languageVersion": "Node.js 20.x",
      "frameworkVersions": ["React 18", "Next.js 14"],
      "runtimeNotes": "Requires PostgreSQL 15+"
    }
  },
  "progress": {
    "completed": ["User authentication", "Database schema"],
    "inProgress": ["Stripe payment integration"],
    "nextSteps": ["Email notifications", "Admin dashboard"],
    "blockers": [],
    "lastUpdated": "2026-03-03T06:00:00.000Z"
  },
  "activeTask": {
    "description": "Implement Stripe checkout flow",
    "relevantFiles": [
      "src/payments/stripe.ts",
      "src/api/checkout.ts"
    ],
    "steps": [
      "1. Set up Stripe webhooks",
      "2. Create checkout session endpoint",
      "3. Handle payment success/failure"
    ],
    "codeHints": [
      "Use stripe SDK v12+",
      "Store webhook secret in env as STRIPE_WEBHOOK_SECRET"
    ]
  },
  "architecture": {
    "overview": "Next.js app with API routes and PostgreSQL via Prisma",
    "patterns": ["Repository pattern", "Service layer"],
    "constraints": [
      "No direct DB queries in components",
      "All API routes must validate input with Zod"
    ],
    "protectedAreas": ["src/core/auth.ts", "src/db/migrations/"]
  },
  "exclude": ["coverage/", "*.generated.ts"],
  "options": {
    "maxTokens": 8000,
    "format": "both",
    "treeDepth": 4,
    "maxTreeEntries": 200,
    "includeGit": true,
    "gitLogCount": 5,
    "readBudget": {
      "maxRelevantFiles": 10,
      "allowExtraReads": true
    }
  }
}

Key Fields

| Field | Purpose | |-------|---------| | project.stack | Auto-detected on acm init, update as needed | | progress | The heart of the handoff — keep this updated | | activeTask.relevantFiles | These files are fully embedded in the snapshot | | activeTask.codeHints | Constraints to prime your AI's understanding | | options.maxTokens | Budget guard — warns if snapshot exceeds this | | exclude | Additional patterns on top of built-in security exclusions |

Built-in security exclusions (always applied, cannot be overridden):

.env* · *.pem · *.key · *.cert · node_modules/ · .git/ · dist/ · build/ · lock files · Terraform state · database files · credential files

Library API

Track AI context events programmatically across sessions and tools.

Basic Usage

import { ContextManager } from '@jenishk29/ai-context-manager';

const manager = new ContextManager({
  storagePath: '.context-events/context.json',
  tool_id: 'claude-3',
  prunePolicy: {
    max_events: 500,
    max_age_days: 90
  }
});

// Track an AI interaction
const event = manager.addEvent({
  operation: 'code_generation',
  status: 'completed',
  context_data: {
    prompt: 'Create user authentication',
    files_modified: ['auth.ts', 'user.ts']
  },
  tokens_used: 1200,
  notes: 'Generated JWT authentication'
});

// Export for use in another AI session or tool
const exported = manager.export();
console.log(`Token savings: ${exported.token_savings}`);

Constructor Options

interface ContextManagerOptions {
  storagePath?: string;       // Default: '.context-events/context.json'
  inMemory?: boolean;         // Default: false  — set true for testing
  user_id?: string;           // Optional default user ID
  tool_id?: string;           // Optional default AI tool identifier
  prunePolicy?: {
    max_events?: number;      // Default: 500
    max_age_days?: number;    // Default: 90
    drop_statuses?: string[]; // Default: ['aborted']
  };
  tokenEstimator?: (value: unknown) => number;  // Custom token counter
}

Full API

// ── Event management ──────────────────────────────────────────
manager.addEvent(input)                             // create event
manager.updateEvent(event_id, patch)                // update fields
manager.abortEvent(event_id, { notes? })            // mark aborted
manager.removeEvent(event_id)                       // hard delete

// ── History ───────────────────────────────────────────────────
manager.getHistory({ order, limit, tool_id, user_id, operation, status })

// ── Import / Export ───────────────────────────────────────────
manager.export({ prune? })                          // export snapshot
manager.import(data, { mode: 'replace' | 'merge' }) // import snapshot

// ── Optimization ──────────────────────────────────────────────
manager.prune({ max_events, max_age_days, drop_statuses })
manager.rollbackToEvent(event_id, { preserve_removed_as_aborted? })

// ── Diagnostics ───────────────────────────────────────────────
manager.validateAccuracy({ expected_operations?, expected_pending? })
manager.clearErrors()

Cross-Tool Context Sharing

// Session 1 — Claude does architecture
const claude = new ContextManager({ tool_id: 'claude-3' });
claude.addEvent({
  operation: 'architecture_design',
  status: 'completed',
  context_data: { pattern: 'microservices', services: ['user', 'order'] },
  tokens_used: 1500,
  notes: 'Designed system architecture'
});

// Session 2 — GPT-4 picks up where Claude left off
const gpt = new ContextManager({ tool_id: 'gpt-4' });
gpt.import(claude.export());
// GPT-4 now has full context of what Claude did

In-Memory Mode (Testing)

const manager = new ContextManager({ inMemory: true });
// Zero disk I/O — perfect for unit tests

Schemas

import { schemas } from '@jenishk29/ai-context-manager';

schemas.context_event  // ContextEvent JSON Schema
schemas.export         // ContextExport JSON Schema
schemas.functions      // Function call schemas

Environment Variables

ACM_DEBUG=1                          # enable debug logging
ACM_STORAGE_PATH=.custom-context/   # override default storage path
ACM_DEFAULT_TOOL=claude-3-opus       # set default tool_id for events

Contributing

Contributions are welcome! Please open an issue before submitting a PR for major changes.

# Clone and setup
git clone https://github.com/jenishk29/ai-context-manager.git
cd ai-context-manager
npm install

# Build
npm run build

# Lint & format
npm run lint
npm run format

# Type check
npm run typecheck

License

MIT © 2026 Jenish Kheni — see LICENSE for full text.