@humancontext/intent-engine

Know what you decided — not what the AI said.

An MCP server + CLI that reads your AI coding sessions and extracts human intent: what you were doing, what approaches you tried, what you accepted and rejected, and why.

Works with Claude Code, Cursor, Windsurf, Copilot, and 20+ other AI coding tools.

Quick Start — MCP Server

Add to your Claude Code config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "hc-intent": {
      "command": "npx",
      "args": ["-y", "@humancontext/intent-engine", "mcp"]
    }
  }
}

Then in any Claude Code session, ask:

"Where did I leave off yesterday?"

The MCP server auto-discovers your recent sessions and runs 4-layer intent analysis.

MCP Tools

Tool	What It Does
get_context	"Where did I leave off?" — finds and analyzes your most recent session
analyze_session	Full 4-layer analysis on any session file
list_sessions	Discover all AI coding sessions on your machine

Quick Start — CLI

npx @humancontext/intent-engine ./session.jsonl

Output:

═══════════════════════════════════════════════════════════
  HumanContext Intent Analysis
═══════════════════════════════════════════════════════════

  Session:    abc123
  Events:     1568 (from 2400 raw lines)
  Duration:   45m 12s
  Analyzed:   154ms

── Layer 1: Activity Classification ──
  Navigation:     312 (20%)
  Editing:        890 (57%)
  Comprehension:  280 (18%)
  Other:           86 (5%)

── Layer 3: Intent Narrative ──
  Summary: Developer debugged a race condition in the payment service.
  Tried 3 approaches. Rejected mutex (latency), rejected retry (complexity),
  chose event sourcing after consulting Stripe docs.

── Layer 4: Decision Capture ──
  Total decisions: 23
  Rejected: 8  |  Accepted: 15
  Top rejection: "AI suggestion ignored system constraints"
═══════════════════════════════════════════════════════════

CLI Options

hc-intent <file>              # Full analysis
hc-intent <file> --json       # JSON output
hc-intent <file> --summary    # One-line summary
hc-intent <file> --layer 3    # Single layer (1-4)
hc-intent <file> --stats      # Quick stats

What It Extracts

Layer 1 — Activity Classification Every event tagged as navigation, editing, comprehension, or other. 95%+ accuracy using tool-call heuristics.

Layer 2 — Cognitive Phases Groups activities into cognitive workflow stages (understanding, hypothesizing, experimenting, verifying). Detects iteration cycles.

Layer 3 — Intent Narrative Human-readable summary: what the developer was doing, what files were involved, what approaches were tried and why they were accepted or rejected.

Layer 4 — Decision Capture Every point where the developer accepted, rejected, or redirected an AI suggestion, with rationale categorization and confidence scores.

Supported Formats

Format	Source Tools	Auto-Detection
Claude Code JSONL	Claude Code	.jsonl with message.role + uuid
CASS JSON/JSONL	13+ agents (Claude Code, Cursor, Windsurf, Aider, etc.)	agent_slug + messages[]
Agentlytics JSON	16+ editors (Cursor, Windsurf, Copilot, etc.)	source + messages[]
Agentlytics SQLite	Same as above (local cache)	.db / .sqlite extension

Format is auto-detected. No configuration needed.

Library API

import { analyzeSession } from '@humancontext/intent-engine';

const result = analyzeSession('./session.jsonl');

console.log(result.layer3.summary);    // "Developer debugged race condition..."
console.log(result.layer3.approaches); // [{name, rejected, rejectionReason}]
console.log(result.layer4.decisions);  // [{type, rationale, confidence}]

Async (for SQLite/Agentlytics)

import { analyzeSessionAsync } from '@humancontext/intent-engine';

const result = await analyzeSessionAsync('./agentlytics-cache.db');

Adapter API (direct ingestion)

import { ingestSync, detectFormat, SourceFormat } from '@humancontext/intent-engine';

// Auto-detect and parse any format → NormalizedEvent[]
const { events, metadata } = ingestSync('./session-file');

Architecture

┌─────────────────┐   ┌──────────────────┐   ┌───────────────────┐
│ Claude Code     │   │ CASS (13+ tools) │   │ Agentlytics (16+) │
│ .jsonl          │   │ .json / .jsonl   │   │ .json / .db       │
└────────┬────────┘   └────────┬─────────┘   └────────┬──────────┘
         │                     │                       │
         └─────────┬───────────┴───────────┬───────────┘
                   │                       │
            detectFormat()          ingest() / ingestSync()
                   │                       │
                   └───────────┬───────────┘
                               │
                    ┌──────────▼──────────┐
                    │   NormalizedEvent    │
                    │ (unified schema)    │
                    └──────────┬──────────┘
                               │
              ┌────────┬───────┴───────┬────────┐
              │        │               │        │
           Layer 1  Layer 2        Layer 3  Layer 4
          classify  phases        narrative decisions

Every adapter produces NormalizedEvent objects with a unified schema. The 4-layer analysis runs identically regardless of source tool.

Security

The MCP server validates all file paths:

• Only absolute paths accepted
• Must be under user home directory
• Path traversal (../) blocked via normalization
• Non-existent files rejected before any I/O

Contributing

PRs welcome for: classification improvements, new adapter formats, CLI enhancements, and bug fixes.

We build on top of these open-source projects — contributions there benefit everyone:

• CASS — Unified AI session schema (13+ agents)
• Agentlytics — Editor session analytics (16+ editors)

License

Apache 2.0 — see LICENSE.

---

Built by HumanContext.ai — Mission control for developers using AI coding tools.