@feature-maps/hooks

Claude Code hooks for feature-maps. Records assistant sessions and summarizes them into requirement docs + paired feature maps, so the work an AI agent did becomes a committable, linkable artifact.

Install

npm install --save-dev @feature-maps/hooks

Pulls in @feature-maps/core automatically (exact-version match).

Binaries

• fmap-record — hook handler. Reads Claude Code's JSON hook payload from stdin and appends the turn to .featuremap/sessions/<session-id>.jsonl. Handles both Stop and SessionEnd events; for SessionEnd it also ingests Claude Code's full transcript so nothing is missed in long sessions.
• fmap-summarize — distills a recorded session into:
  • requirements/session-<id>.md — markdown requirements doc.
  • .featuremap/session-<id>.featuremap.yaml — bindings from the new requirement IDs to the files the agent touched.

Wire it up

From the root of your project (no install needed):

npx @feature-maps/hooks install

That writes idempotent entries to <project>/.claude/settings.json:

• A Stop hook → fmap-record (captures each finished assistant turn).
• A SessionEnd hook → fmap-record (ingests the full transcript) then fmap-summarize --markEnded then fmap scan (regenerates the global map).

Other forms:

npx @feature-maps/hooks install --precommit   # also install .git/hooks/pre-commit
npx @feature-maps/hooks install --root <dir>  # target a different project root
npx @feature-maps/hooks uninstall             # remove what install added
npx @feature-maps/hooks --help                # full usage

The net effect: every Claude Code session leaves behind a requirements/ doc and a paired feature map, both regenerated into the global map, all stageable in one shot.

What gets written

After a session ends you'll see, e.g.:

requirements/session-2026-05-15-1247.md
.featuremap/session-2026-05-15-1247.featuremap.yaml
.featuremap/feature-map.json            # regenerated by `fmap scan`
.featuremap/feature-map.json.map
.featuremap/sessions/<id>.jsonl         # raw transcript (kept for re-summarization)
.featuremap/sessions/<id>.ended         # marker so re-runs skip completed sessions

The generated requirements doc looks roughly like:

# Session 2026-05-15-1247

## SESSION-2026-05-15-1247-1 — Add rate limiting to /api/login
Block repeated login attempts from the same IP. ...

Files touched:
- src/middleware/rateLimit.ts
- src/login.ts

And the paired feature map:

version: 1
mappings:
  - requirement: SESSION-2026-05-15-1247-1
    files:
      - path: src/middleware/rateLimit.ts
        ranges: [[1, 64]]
      - path: src/login.ts
        ranges: [[40, 52]]

Both files are committable as-is — you can rename the auto-generated SESSION-* IDs to project-specific ones (e.g. AUTH-19) and fmap scan will pick them up.

Manual use

fmap-summarize                            # summarize all completed sessions
fmap-summarize <session-id>               # summarize one
fmap-summarize --provider=claude          # force Claude API (needs ANTHROPIC_API_KEY)
fmap-summarize --provider=heuristic       # force local extraction
fmap-summarize --markEnded                # mark session as ended on completion
fmap-summarize --root <dir>               # alternate project root

Configuration

• ANTHROPIC_API_KEY — enables Claude-based summarization (defaults on when set).
• FMAP_MODEL — override the model (defaults to claude-sonnet-4-6).
• Without an API key, a local heuristic summarizer extracts bullets and file references. Less polished, still committable.

Git pre-commit hook

Optional companion hook that regenerates the feature map on every commit and stages it, so the map never drifts from the code:

npx @feature-maps/hooks install --precommit

This writes .git/hooks/pre-commit (backing up any existing one to pre-commit.bak). The installed hook is a thin Node dispatcher that calls npx @feature-maps/hooks pre-commit, whose body is implemented in this package. Remove it with npx @feature-maps/hooks uninstall --precommit.

Programmatic API

A small transcript-handling surface is re-exported for tooling that wants to read or append to sessions without shelling out:

import {
  appendTurn,
  readTranscript,
  listTranscripts,
  transcriptPath,
  TranscriptTurn,
  SessionTranscript,
} from '@feature-maps/hooks';

License

Apache-2.0 — see LICENSE.