needle: 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

Needle: Windows tray app (Tauri 2 + Vue 3 frontend, Rust backend) that monitors Claude Code sessions. Claude Code fires hooks on session events; Needle's own executable (needle.exe hook) receives them, forwards to the running app over local HTTP, and the app tracks per-session state in SQLite, updating the tray icon/panel live.

Commands

npm install
npm run tauri dev     # dev mode (Vite + Tauri, hot reload)
npm run build          # vue-tsc --noEmit && vite build (frontend only)
npm run tauri build    # release build, NSIS installer at src-tauri/target/release/bundle/nsis

cd src-tauri
cargo test             # all Rust unit tests
cargo test <name>       # single test by substring, e.g. cargo test transition

CI (.github/workflows/release.yml) on tag push v*: vue-tsc --noEmit + cargo test, then builds/publishes via tauri-apps/tauri-action.

Prerequisites: Rust (MSVC toolchain), Visual Studio Build Tools (C++ workload), Node.js 20+.

Architecture

Dual entry point of the same binary

src-tauri/src/main.rs branches on argv[1] before any Tauri init:

• needle.exe hook → hookmode::run(): reads a hook JSON payload from stdin, POSTs it to the running app's local HTTP server, exits. No GUI, no Tauri — this is what Claude Code actually invokes on every hook event, so it must stay fast and fail silently (a dead/unreachable app must never block a Claude Code session).
• needle.exe remove-hooks → strips Needle's entries from ~/.claude/settings.json (called by the NSIS uninstaller pre-uninstall hook).
• no args → normal Tauri app: opens the local HTTP server, tray icon, webview window, background cleanup job.

Event flow

hookmode → local HTTP (server.rs, axum, POST /event) → state::transition(current, event) (pure state machine, see state.rs) → db::upsert_session (SQLite, db.rs) → tray::on_session_changed (tray.rs): re-reads the session's Claude Code transcript for cost/model, updates tray tooltip, emits session-updated to the webview, and alerts (tray::alert_if_needed) if the new state warrants it — an OS notification when Settings.notifications_enabled is on, otherwise an in-app toast (toast.rs's toast::show, emits toast-show to the dedicated toast window, which navigates to the main panel via the open_panel_from_toast command when clicked). session-removed is emitted only from main.rs — on the 24h stale-purge in spawn_cleanup_job and on manual deletion via the delete_session command — never from tray.rs.