From fb15d5f884db3b3135b1aa9cb6fb788cb76b1a43 Mon Sep 17 00:00:00 2001 From: Yi Lu Date: Mon, 8 Jun 2026 09:08:44 -0700 Subject: [PATCH] docs(plugin): add claude_smart package code map MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add plugin/src/README.md mapping the claude_smart package — hook dispatcher, event handlers, session buffering, publish/adapter flow, and supporting modules. Navigation aid for coding agents following the repo's code-map README conventions. --- plugin/src/README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 plugin/src/README.md diff --git a/plugin/src/README.md b/plugin/src/README.md new file mode 100644 index 0000000..5387893 --- /dev/null +++ b/plugin/src/README.md @@ -0,0 +1,57 @@ +# claude_smart (plugin/src) +Description: Python package powering the claude-smart plugin — hook handlers that buffer Claude Code / Codex session activity, publish it to a local Reflexio backend, and inject the learned skills/preferences back into future sessions. + +> User-facing install/usage docs live in [`../README.md`](../README.md). This is the code map for the `claude_smart` package. + +## Main Entry Points + +| File | Purpose | +|------|---------| +| `hook.py` | Hook dispatcher. Parses the stdin JSON payload and routes each event (Setup, SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) to its handler in `events/`. | +| `cli.py` | `claude-smart` CLI: `install`, `uninstall`, `show`, `learn`, `restart`, `dashboard`, `clear-all`. | +| `state.py` | Per-session JSONL buffer at `~/.claude-smart/sessions/{session_id}.jsonl`; high-water mark for idempotent publish retries. | +| `publish.py` | Drains the session buffer, calls the Reflexio adapter, and stamps the watermark. Used by Stop, SessionEnd, and `learn`. | +| `reflexio_adapter.py` | Thin wrapper over `reflexio.ReflexioClient` — isolates import failures, 5s HTTP timeout, injects/queries learnings, degrades gracefully when the backend is down. | + +## Event Handlers (`events/`) + +| Handler | Hook | Role | +|---------|------|------| +| `session_start.py` | SessionStart | Apply extraction defaults, render stall banner, push optimizer context. | +| `user_prompt.py` | UserPromptSubmit | Inject learned playbooks/preferences into context. | +| `pre_tool.py` | PreToolUse (Edit/Write/Bash/NotebookEdit) | Inject project-specific context before tool execution. | +| `post_tool.py` | PostToolUse | Buffer the tool invocation (name, input, response, duration) into session state. | +| `stop.py` | Stop | Publish unpublished interactions (force extraction if configured). | +| `session_end.py` | SessionEnd | Final publish + aggregation; optional backend/dashboard shutdown. | + +## Supporting Modules + +| File | Purpose | +|------|---------| +| `env_config.py` | Parses `~/.reflexio/.env` (`REFLEXIO_URL`, `REFLEXIO_API_KEY`, `CLAUDE_SMART_READ_ONLY`, local embedding/CLI flags). | +| `runtime.py` | Host detection (Claude Code vs Codex); shared agent version. | +| `ids.py` | Session / project ID generation and resolution. | +| `context_inject.py`, `context_format.py`, `query_compose.py`, `cs_cite.py` | Build search queries, format learned skills as markdown, inject into context, format citations. | +| `stall_banner.py` | User-facing message when the Reflexio provider hits an auth/billing stall. | +| `optimizer_assistant.py` | Claude-code CLI agent that extracts Reflexio optimization hints. | +| `hook_log.py`, `internal_call.py` | Structured JSON logging to `~/.claude-smart/hook.log`; detect internal/test invocations to skip learning. | + +## Architecture + +``` +SessionStart -> bootstrap Reflexio backend (8071) + Next.js dashboard (3001) +PostToolUse -> state.py buffers each tool call to ~/.claude-smart/sessions/{id}.jsonl +Stop/SessionEnd -> publish.py -> reflexio_adapter -> Reflexio extracts playbooks + preferences +UserPromptSubmit / PreToolUse -> context_inject pulls relevant learnings back into context +``` + +- **Dual-host** — the same package runs under Claude Code (native slash commands) and Codex (shell-script fallbacks in `../scripts/`); host shape is normalized in `runtime.py`. +- **Offline-resilient** — if Reflexio is unreachable, interactions stay buffered and drain on the next successful publish. +- **Hooks registered** in `../hooks/hooks.json` (Claude Code) and `../hooks/codex-hooks.json` (Codex), dispatched through `../scripts/hook_entry.sh`. + +## Requirements / Problems to Avoid + +- **All learned state is external to the repo** — sessions buffer under `~/.claude-smart/`, Reflexio state under `~/.reflexio/`. Don't write generated runtime artifacts inside the plugin root. +- **Backend lives at `http://localhost:8071`**, dashboard at `http://localhost:3001`; both are long-lived across sessions (no hard shutdown on SessionEnd by default). +- **`CLAUDE_SMART_READ_ONLY`** skips publishing entirely — respect it in any new publish path. +- **Keep handlers fast** — tool-use hooks run on a 10–15s timeout; heavy work belongs in the backend, not the hook.