Interaction Awareness — Developer Reference

Claude Code plugin for AI interaction pattern awareness.

Architecture

Four layers, each building on the previous:

Layer 1 (skills/) — SKILL.md behavioral overrides. Always active.
Layer 2 (hooks/scripts/) — Programmatic detection via 4 hook events. Node.js (.mjs), cross-platform. Writes JSONL metadata to ${CLAUDE_PLUGIN_DATA}.
Layer 3 (commands/) — User-triggered reports from Layer 2 data. Opt-in.
Layer 4 (commands/interaction-report.md Step 9) — Contemplative references. Opt-in.

Key files

File	Purpose
`hooks/scripts/lib.mjs`	Shared library: stdin, paths, thresholds, state, cooldowns, layer guards, DOMAIN_STAKES, readRecentEndRecords
`hooks/scripts/session-start.mjs`	SessionStart: register session, count daily, night check
`hooks/scripts/prompt-analyzer.mjs`	UserPromptSubmit: pattern flags (NEVER logs prompt text)
`hooks/scripts/tool-tracker.mjs`	PostToolUse: events, edit ratio, burst, alerts
`hooks/scripts/session-end.mjs`	SessionEnd: finalize JSONL, cleanup state
`hooks/hooks.json`	Hook event registration (4 events)
`skills/ai-psychosis/SKILL.md`	Layer 1 behavioral instructions
`commands/interaction-report.md`	Layer 3 slash command: `/interaction-report [weekly\|monthly\|all]`
`hooks/scripts/report-reader.mjs`	Layer 3 helper: reads sessions.jsonl with v1.0.0 backward compat

Legacy bash scripts were removed in v1.0 (available in git history).

Data storage

${CLAUDE_PLUGIN_DATA}/
├── sessions.jsonl       Compact JSONL, one record per session
├── events.jsonl         {ts, session_id, tool_name} per tool call
└── state/
    └── {session_id}.json    Live state during active session

State files are created at SessionStart and deleted at SessionEnd.

Hard constraints

Cross-platform — Node.js only, no bash/jq dependency
Privacy — prompt text NEVER written to disk. Boolean flags only.
Performance — hooks must complete in <100ms
Non-blocking — never exit 2, never require confirmation
No network — everything local
Zero npm dependencies — Node.js stdlib only (fs, path, os)

Layer configuration

Global config at ~/.claude/ai-psychosis.local.md, or per-project override at <project>/.claude/ai-psychosis.local.md:

---
layer2: true   # default on
layer3: false  # default off
layer4: false  # default off
---

requireLayer(N) in lib.mjs exits with {"continue": true} if layer N is disabled.

Testing

Automated test suite using node:test (258 cases, zero npm dependencies):

node --test tests/*.test.mjs

File	Cases	Coverage
`tests/session-start.test.mjs`	11	State init, JSONL, tier-2 cross-session alert
`tests/prompt-analyzer.test.mjs`	100	All v1.x patterns × 2 + thresholds + valence + v1.2 pushback contract
`tests/tool-tracker.test.mjs`	8	Counting, burst, reminders
`tests/session-end.test.mjs`	7	Finalize, duration, flags, v1.1.0 string + v1.2 array shapes
`tests/privacy.test.mjs`	7	Canary + matched-phrase × original + 5 v1.2 detector variants
`tests/skill-md.test.mjs`	3	Constitution citation + Score 5 + 11 guidance criteria
`tests/perf.test.mjs`	9	4 hooks × 2 modes + 1000-record sessions.jsonl wall-clock
`tests/interaction-report.test.mjs`	6	report-reader.mjs v1.0/v1.1/v1.2 + SC-12 stdout assertions
`tests/lib.test.mjs`	17	Threshold constants + DOMAIN_STAKES + readRecentEndRecords
`tests/domain-detection.test.mjs`	39	8 new domains × positive + adjacent-domain negatives + multi-domain
`tests/user-info.test.mjs`	24	yes_people/yes_digital/no priority + sticky + tier-1 alert
`tests/validation-seeking.test.mjs`	20	valseek detection + accumulation + domain-gated alert
`tests/stakes-matrix.test.mjs`	7	Stakes weighting on v1.2 alerts; v1.1.0 sensitivity preserved

Conventions

Conventional Commits: type(scope): description
English for all code, comments, and documentation
Norwegian for project-internal communication

4.1 KiB Raw Blame History Unescape Escape