intelaisense: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

intelaisense is a Claude Code plugin that gives an AI coding agent a perception layer — ambient, on-write signals (the "squiggly line" analog) pushed into the agent's context as it works. It is not an application; it is hooks + a dispatcher + pluggable signals, packaged like the containuity plugin.

Commands

Tests use pytest in an isolated venv (the system Python is externally-managed; do not pip install into it):

.venv/bin/python -m pytest tests/ -q          # full suite
.venv/bin/python -m pytest tests/test_staleness.py -v   # one file
.venv/bin/python -m pytest tests/test_dispatch.py::test_malformed_stdin_exits_zero -v  # one test

If .venv is missing: python3 -m venv .venv && .venv/bin/python -m pip install pytest.

Plugin packaging smoke check: bash scripts/validate.sh (parses the manifest + hooks.json, checks the hook entry exists).

Control the signals for a project: python3 scripts/cli.py status|enable <signal>|disable <signal> [--dir=PATH].

Architecture

The flow is: hook → dispatcher → signals → additionalContext.

• hooks/hooks.json registers PreToolUse (Edit|Write) and PostToolUse (Read|Edit|Write), both invoking the thin shell wrapper hooks/intelaisense.sh, which execs scripts/dispatch.py.
• scripts/dispatch.py is the single entry point. It reads the hook JSON from stdin, builds an Event, loads config, opens the StateStore, runs discover_signals(config), and for each signal calls run() only when (event_type, tool_name) is in that signal's interests(). It formats annotations under a char budget and prints {"hookSpecificOutput": {"additionalContext": ...}} only when there is text.
• scripts/intelaisense/ is the package: types.py (Event, Annotation), state.py (StateStore), config.py (load_config + DEFAULTS), output.py (format_annotations), and signals/ (base.py + the three signal modules).
• signals/__init__.py is a lazy registry: it maps signal name → (module, class) and imports inside discover_signals under try/except, so a missing or broken signal module is skipped, never fatal.