@thetrueguardai/core

Capture and manage AI assistant session handoffs with zero dependencies.

Seamlessly transfer your development context between Claude Code, GitHub Copilot, and other AI tools. Preserve git state, open files, task context, and history — all locally stored.

Features

• Session Capture: Record git branch, staged files, uncommitted changes, and task context
• File Tracking: Detect changed files relative to main branch
• Editor Context: Capture open files and current working state
• Schema Validation: Validate handoff data against strict JSON schema
• Local History: Track all past handoffs in .claude/handoff-history.json
• Zero Dependencies: Pure Node.js, no external services
• CLI Tool: Command-line interface for all operations

Quick Start

Install

npm install -g @thetrueguardai/core

See Installation Guide for detailed platform-specific instructions (Windows, macOS, Linux).

Prepare a Handoff

# In your project directory
handoff-core prepare

Creates .handoff.json with:

• Current git branch and state
• List of changed files
• Uncommitted changes
• Task description
• Timestamp

View History

handoff-core history

Shows all past handoffs:

2026-05-17 14:32  feature/auth      "Implement JWT validation"
2026-05-17 12:15  feature/auth      "Add token refresh logic"
2026-05-17 09:45  bugfix/payment    "Fix transaction limits"

Resume from a Handoff

handoff-core resume ./.handoff.json

Outputs full resumption prompt with all context. Copy and paste into your next AI tool.

What Gets Captured

When you run handoff-core prepare, it captures:

Git State

• Current branch
• Staged files
• Uncommitted changes (diff)
• Files changed vs main

Editor Context

• List of open files
• Current file in focus
• Cursor position (if available)

Task Context

• Task description (manual input or auto-detected)
• Related files
• Recent commands

Metadata

• Timestamp
• Tool used (Claude Code, Copilot, etc.)
• Handoff reason

Workflow Example

Scenario: Working on auth feature in Claude Code, approaching token limit.

Step 1: Prepare Handoff (Claude Code)

handoff-core prepare

Output:

✓ Handoff prepared successfully
  File: .handoff.json
  Branch: feature/auth
  Files: 3 changed, 2 uncommitted

Step 2: Commit and Switch Tools

git add .handoff.json
git commit -m "Prepare handoff to Copilot"
# Switch to GitHub Copilot

Step 3: Resume (Copilot)

handoff-core resume ./.handoff.json

Output:

📋 Resumption Prompt:
---
Branch: feature/auth
Task: Implement JWT validation
Changed Files: auth.ts, middleware.ts, tests.ts
Uncommitted: +15 lines, -3 lines in auth.ts
---
[Full context ready to paste]

Commands

prepare

Capture current session state.

handoff-core prepare [--task "description"] [--output .handoff.json]

Options:

• --task "description" — Optional task description
• --output file.json — Custom output file (default: .handoff.json)
• --interactive — Prompt for task details interactively

history

List past handoffs in project.

handoff-core history [--limit 20] [--branch feature/auth]

Options:

• --limit N — Show last N handoffs (default: 20)
• --branch name — Filter by branch
• --format json — Output as JSON

resume

Generate resumption prompt from handoff file.

handoff-core resume <file.json> [--copy]

Options:

• --copy — Copy to clipboard automatically
• --format markdown — Format as markdown (default)

Resume Enhancement

The resumption prompt now includes your complete handoff state as JSON plus an explicit instruction to use superpowers. This enables the AI to intelligently parse your context and invoke relevant skills (like gsd-resume-work, gsd-verify-work) to generate a comprehensive resumption summary.

The JSON payload includes:

• Complete metadata (timestamp, branch, tool)
• Task description and context
• Git state (staged files, uncommitted changes, files changed vs main)
• Changed files list
• Metadata for skill invocation
• Next steps and status

Example prompt structure:

Resume work using this handoff:

<HANDOFF_JSON>
{
  "version": "1.0",
  "timestamp": "2026-05-17T14:32:00Z",
  "branch": "feature/auth",
  "task": "Implement JWT validation",
  "changedFiles": ["auth.ts", "middleware.ts", "tests.ts"],
  ...
}
</HANDOFF_JSON>

Use superpowers to generate comprehensive resumption context.

This allows Claude, Copilot, or other AI tools to automatically parse the context and invoke appropriate resumption workflows without manual re-briefing.

validate

Validate handoff JSON against schema.

handoff-core validate <file.json>

clean

Remove old handoffs (older than N days).

handoff-core clean [--days 30]

Configuration

Create .handoff.json.config in project root:

{
  "maxHistory": 100,
  "excludePatterns": [".env", "secrets/", "node_modules/"],
  "taskPrompt": "What are you working on?",
  "autoIncludeStagedFiles": true
}

Schema

Handoff files follow strict JSON schema for validation. See src/schema.json.

Example .handoff.json:

{
  "timestamp": "2026-05-17T14:32:00Z",
  "branch": "feature/auth",
  "task": "Implement JWT validation",
  "changedFiles": ["auth.ts", "middleware.ts", "tests.ts"],
  "uncommittedChanges": {
    "auth.ts": {
      "additions": 15,
      "deletions": 3
    }
  },
  "stagedFiles": ["auth.ts"],
  "openFiles": [
    {
      "path": "auth.ts",
      "line": 42,
      "column": 10
    }
  ],
  "tool": "claude-code",
  "reason": "token-limit"
}

Use Cases

Multi-Tool Development

• Start in Claude Code, hit token limit
• Prepare handoff → Switch to Copilot
• Copilot resumes context automatically
• Later switch back to Claude Code with full history

Context Persistence

• Work on complex feature over multiple sessions
• Each handoff captures full state
• Jump between tools without losing progress

Team Handoffs

• Developer A prepares handoff
• Developer B reviews and resumes
• Full context transfer without meetings

Debugging Sessions

• Record state before deep debugging
• Easy rollback if needed
• Handoff to teammate with exact reproduction

Troubleshooting

.handoff.json not created

• Check git repository exists: git status
• Ensure write permissions in directory
• Try with explicit output: handoff-core prepare --output .handoff.json

History not showing

• History stored in .claude/handoff-history.json
• Check file exists: ls -la .claude/
• Ensure project is git repository

Resume prompt shows nothing

• Validate handoff: handoff-core validate .handoff.json
• Check file is valid JSON: cat .handoff.json | jq .

API Usage

You can also use @thetrueguardai/core as a library in your own tools:

import { captureState, parseHandoff } from '@thetrueguardai/core';

// Capture current state
const handoff = await captureState({
  task: 'Implement feature X',
  tool: 'my-tool'
});

// Write to file
fs.writeFileSync('.handoff.json', JSON.stringify(handoff, null, 2));

// Later, resume
const saved = JSON.parse(fs.readFileSync('.handoff.json', 'utf-8'));
const resumption = await parseHandoff(saved);
console.log(resumption.prompt);

See TypeScript interfaces in src/types.ts.

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm run test

# Watch mode
npm run dev

# Lint
npm run lint

License

MIT

Support

Found a bug or have a feature request? Open an issue.