docs: CHANGELOG, README, and CLAUDE.md for hooks release#29
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughAdds an event-driven hook system with a unified Changes
Sequence Diagram(s)mermaid GitHook->>Entrypoint: invoke Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@CHANGELOG.md`:
- Around line 8-38: The package.json version field is out of sync with
CHANGELOG.md; update the "version" property in package.json from "0.2.1" to
"0.3.0" (edit the version key in package.json), then regenerate/update any
lockfiles (package-lock.json / yarn.lock / pnpm-lock.yaml) or build artifacts
that embed the version so everything stays consistent.
In `@README.md`:
- Around line 137-175: The ASCII architecture diagram code block in README.md
lacks a language identifier; update the triple-backtick fence that opens the
diagram to include a language identifier (e.g., change ``` to ```text) so
markdown linting rules accept it and the block remains rendered as plain text;
locate the block containing the box diagram (the ASCII art starting with the top
border "┌─────────────────────────────────────────────┐") and modify its opening
fence accordingly.
- Around line 58-70: The fenced code block in README.md lacks a language
identifier which fails markdown linting; update the opening triple-backtick to
include a language (e.g., change ``` to ```text) for the block that shows the
workflow diagram (the three-step Claude Code session / git-mem hook sequence) so
the linter recognizes it as a text block.
- Line 155: The README's architecture diagram incorrectly places "EventBus +
Handlers" in the Application layer; split responsibilities to match CLAUDE.md
and clean architecture: move the EventBus implementation to the Infrastructure
layer, keep the IEventBus interface in the Domain layer, and place Event
handlers in the Application layer; update the diagram text/labels to reflect
"IEventBus (Domain) / EventBus (Infrastructure) / Handlers (Application)" and
ensure references to EventBus, IEventBus, and handlers in documentation (e.g.,
CLAUDE.md) are consistent.
There was a problem hiding this comment.
Pull request overview
Documentation-focused release prep for git-mem’s Claude Code hooks + DI/EventBus architecture, aiming to provide a consolidated README quick start, an internal architecture guide for Claude, and a formal changelog for upcoming releases.
Changes:
- Added a new
CHANGELOG.mdwith release entries (including a v0.3.0 section). - Rewrote
README.mdwith Quick Start, Claude Code hooks integration docs, config reference, MCP server notes, and an architecture diagram. - Updated
CLAUDE.mdwith current architecture/bootstrapping details, hook flow notes, and updated testing section.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.
| File | Description |
|---|---|
| README.md | New user-facing usage/docs for CLI, Claude hooks, and MCP setup/config |
| CLAUDE.md | Updated internal “how the repo works” guidance for Claude Code |
| CHANGELOG.md | Introduces a changelog with recent version entries and a v0.3.0 release section |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **`git-mem init-hooks`** command — one-command setup for Claude Code hooks: | ||
| - Creates `.claude/settings.json` with hook registrations | ||
| - Creates `.git-mem.json` with default configuration | ||
| - Safe merge preserves other tools' hooks in `settings.json` | ||
| - `--remove` flag cleanly uninstalls git-mem hooks only | ||
| - `--scope user` for `~/.claude/settings.json` (user-wide) | ||
| - **Unified `git-mem hook <event>` command** — single entry point for all hook events, reads JSON from stdin, routes to handlers via EventBus |
There was a problem hiding this comment.
This entry describes a user-facing git-mem init-hooks command, but the current CLI only registers git-mem init (and uses init-hooks internally). If init-hooks is not meant to be a public command anymore, the changelog should reflect the actual UX (e.g., “git-mem init sets up Claude hooks …”).
| ### Recall memories | ||
|
|
||
| ```bash | ||
| git-mem recall --query "authentication" |
There was a problem hiding this comment.
The Quick Start recall example uses git-mem recall --query "...", but the CLI takes the search string as an optional positional argument (git-mem recall [query]) and does not define a --query flag. Update the example to pass the query as the argument (or add a --query option in the CLI if that’s the intended UX).
| git-mem recall --query "authentication" | |
| git-mem recall "authentication" |
README.md
Outdated
| ```bash | ||
| git-mem init-hooks --remove | ||
| ``` | ||
|
|
||
| This removes git-mem entries from `.claude/settings.json` (preserving other tools' hooks) and deletes `.git-mem.json`. |
There was a problem hiding this comment.
git-mem init-hooks --remove is documented as the uninstall path, but init-hooks is not currently a CLI command (only init is). Either document the actual removal workflow supported by the current CLI, or reintroduce a user-facing remove option/command.
| ```bash | |
| git-mem init-hooks --remove | |
| ``` | |
| This removes git-mem entries from `.claude/settings.json` (preserving other tools' hooks) and deletes `.git-mem.json`. | |
| To remove git-mem's Claude Code integration, manually: | |
| 1. Open `.claude/settings.json` and remove any hooks whose `command` starts with `git-mem hook` (this preserves other tools' hooks). | |
| 2. Delete `.git-mem.json` from your repository. |
CLAUDE.md
Outdated
|
|
||
| **Entry points:** | ||
| - `src/cli.ts` — Commander.js CLI with 6 commands (remember, recall, context, liberate, sync, init-mcp) | ||
| - `src/cli.ts` — Commander.js CLI with 8 commands (remember, recall, context, liberate, sync, init-mcp, hook, init-hooks) |
There was a problem hiding this comment.
This line claims the CLI has 8 commands including init-mcp and init-hooks, but src/cli.ts currently registers init, remember, recall, liberate, context, sync, and hook (no init-mcp/init-hooks). Update the command list to match the actual CLI surface, and consider mentioning that init replaces the older separate init commands.
| - `src/cli.ts` — Commander.js CLI with 8 commands (remember, recall, context, liberate, sync, init-mcp, hook, init-hooks) | |
| - `src/cli.ts` — Commander.js CLI with 7 commands (init, remember, recall, liberate, context, sync, hook); `init` replaces the older `init-mcp` and `init-hooks` commands |
README.md
Outdated
| ### Setup | ||
|
|
||
| ```bash | ||
| git-mem init-hooks --yes |
There was a problem hiding this comment.
git-mem init-hooks is referenced here, but the current CLI only exposes git-mem init (see src/cli.ts), and init-hooks is not registered as a command. Either update the docs to use git-mem init for hook setup, or re-expose init-hooks in the CLI if it’s meant to be user-facing.
| git-mem init-hooks --yes | |
| git-mem init --yes |
| | `sessionStart.enabled` | `true` | Load memories on session start | | ||
| | `sessionStart.memoryLimit` | `20` | Max memories to load | | ||
| | `sessionStop.enabled` | `true` | Capture memories on session end | | ||
| | `sessionStop.autoLiberate` | `true` | Auto-scan commits for memories | | ||
| | `sessionStop.threshold` | `3` | Minimum commit triage score | | ||
| | `promptSubmit.enabled` | `false` | Surface context per prompt | | ||
| | `promptSubmit.surfaceContext` | `true` | Include memories in prompt context | |
There was a problem hiding this comment.
The config table keys are inconsistent with the JSON structure shown above. Options like sessionStart.enabled / sessionStop.threshold are nested under hooks in .git-mem.json, so the documented paths should be hooks.sessionStart.enabled, hooks.sessionStop.threshold, etc. (Also promptSubmit.recordPrompts exists in the JSON but isn’t listed in the table.)
| | `sessionStart.enabled` | `true` | Load memories on session start | | |
| | `sessionStart.memoryLimit` | `20` | Max memories to load | | |
| | `sessionStop.enabled` | `true` | Capture memories on session end | | |
| | `sessionStop.autoLiberate` | `true` | Auto-scan commits for memories | | |
| | `sessionStop.threshold` | `3` | Minimum commit triage score | | |
| | `promptSubmit.enabled` | `false` | Surface context per prompt | | |
| | `promptSubmit.surfaceContext` | `true` | Include memories in prompt context | | |
| | `hooks.sessionStart.enabled` | `true` | Load memories on session start | | |
| | `hooks.sessionStart.memoryLimit` | `20` | Max memories to load | | |
| | `hooks.sessionStop.enabled` | `true` | Capture memories on session end | | |
| | `hooks.sessionStop.autoLiberate` | `true` | Auto-scan commits for memories | | |
| | `hooks.sessionStop.threshold` | `3` | Minimum commit triage score | | |
| | `hooks.promptSubmit.enabled` | `false` | Surface context per prompt | | |
| | `hooks.promptSubmit.recordPrompts` | `false` | Record user prompts as memories | | |
| | `hooks.promptSubmit.surfaceContext` | `true` | Include memories in prompt context | |
| ```bash | ||
| git-mem init-mcp | ||
| ``` |
There was a problem hiding this comment.
git-mem init-mcp is referenced here, but the CLI does not currently expose an init-mcp command (only init is registered in src/cli.ts). Update the docs to reflect how MCP configuration is actually generated (e.g., via git-mem init, or re-add init-mcp as a CLI command).
| Uses `InjectionMode.CLASSIC` (matches constructor parameter names to registration names). `ICradle` in `types.ts` defines the typed container shape with all interface references. | ||
| Uses `InjectionMode.CLASSIC` (matches constructor parameter names to registration names). `ICradle` in `types.ts` defines the typed container shape with all interface references. The container also registers the `EventBus` with three hook handlers (`session:start`, `session:stop`, `prompt:submit`) wired during creation. | ||
|
|
||
| **Hook event flow:** `git-mem hook <event>` → `readStdin()` → `loadHookConfig()` → `createContainer()` → `eventBus.emit(typedEvent)` → handlers return `IEventResult[]` → output to stdout (context), summary to stderr. Hooks have a 10s hard timeout and never throw — failures are caught and reported silently. |
There was a problem hiding this comment.
Hook failures are not “reported silently”: hookCommand writes summaries and errors to stderr (e.g., git-mem: hook failed.) even though it exits 0. Consider rewording this to reflect that hooks don’t disrupt Claude Code (exit 0 / don’t throw past the entry point), but do emit stderr diagnostics.
| **Hook event flow:** `git-mem hook <event>` → `readStdin()` → `loadHookConfig()` → `createContainer()` → `eventBus.emit(typedEvent)` → handlers return `IEventResult[]` → output to stdout (context), summary to stderr. Hooks have a 10s hard timeout and never throw — failures are caught and reported silently. | |
| **Hook event flow:** `git-mem hook <event>` → `readStdin()` → `loadHookConfig()` → `createContainer()` → `eventBus.emit(typedEvent)` → handlers return `IEventResult[]` → output to stdout (context), summary to stderr. Hooks have a 10s hard timeout and never throw past the entry point — failures are caught so they don't disrupt Claude Code (exit 0), but summaries and errors are reported via stderr (for example, `git-mem: hook failed.`). |
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| ## [0.3.0] - 2026-02-12 |
There was a problem hiding this comment.
The changelog introduces a 0.3.0 release entry, but package.json is currently version 0.2.1. Either bump the package version as part of this release documentation, or adjust the changelog entry/versioning so the repository stays consistent.
| ## [0.3.0] - 2026-02-12 | |
| ## [Unreleased] |
- Bump package.json version to 0.3.0 to match CHANGELOG - Add 'text' language identifier to workflow diagram code block - Add 'text' language identifier to architecture diagram code block - Fix architecture diagram: move Handlers to Application layer, keep EventBus implementation in Infrastructure layer Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> AI-Agent: Claude-Code/2.1.42 AI-Model: claude-opus-4-5-20251101
|
Addressed review feedback:
|
- Combined new intro from main with detailed hook docs from branch - Updated liberate → extract throughout - Updated init-hooks/init-mcp → unified init command - Kept architecture diagram with text language identifier Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> AI-Agent: Claude-Code/2.1.42 AI-Model: claude-opus-4-5-20251101
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `session-start` — loads stored memories into Claude's context at session start | ||
| - `session-stop` — captures new memories from commits made during the session | ||
| - `prompt-submit` — surfaces relevant memories per prompt (disabled by default) | ||
| - **`git-mem init-hooks`** command — one-command setup for Claude Code hooks: |
There was a problem hiding this comment.
The command name should be git-mem init not git-mem init-hooks. The CLI only exposes the unified init command that handles both hooks and MCP configuration. The init-hooks.ts file exists as a utility module but is not exposed as a separate command.
| - **`git-mem init-hooks`** command — one-command setup for Claude Code hooks: | |
| - **`git-mem init`** command — one-command setup for Claude Code hooks: |
| **Infrastructure** (`src/infrastructure/`) — Implements domain interfaces. `GitClient` wraps git CLI. `NotesService` reads/writes `refs/notes/mem`. `TrailerService` queries commit trailers. `MemoryRepository` persists `IMemoryEntity[]` as JSON in git notes. `HeuristicPatterns` provides regex-based extraction rules. `EventBus` provides pub/sub event dispatch with error isolation (failing handlers don't crash the hook). | ||
|
|
||
| **Entry points:** | ||
| - `src/cli.ts` — Commander.js CLI with 6 commands (remember, recall, context, extract, sync, init) |
There was a problem hiding this comment.
The CLI has 8 commands, not 6. The commands are: init, remember, recall, context, extract, sync, trailers, and hook. The description is missing trailers and hook from the count and list.
| - `src/cli.ts` — Commander.js CLI with 6 commands (remember, recall, context, extract, sync, init) | |
| - `src/cli.ts` — Commander.js CLI with 8 commands (init, remember, recall, context, extract, sync, trailers, hook) |
|
|
||
| ### Added | ||
|
|
||
| - MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, liberate |
There was a problem hiding this comment.
The tool name should be extract not liberate. The MCP server registers four tools: remember, recall, context, and extract (as seen in src/mcp/server.ts lines 19-22). There is no liberate tool in the current implementation.
| - MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, liberate | |
| - MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, extract |
| - `git-mem remember` — store memories as git notes | ||
| - `git-mem recall` — search and retrieve memories | ||
| - `git-mem context` — match staged changes against stored memories | ||
| - `git-mem liberate` — scan git history, score commits, extract memories |
There was a problem hiding this comment.
The command name should be extract not liberate. Looking at src/cli.ts, the commands are: init, remember, recall, extract, context, sync, trailers, and hook. There is no liberate command in the CLI.
| @@ -14,7 +14,7 @@ Each commit is updated with background AI metadata, which Claude can use to impr | |||
|
|
|||
| Every **new** commit is automatically populated with the folowing metadata.. | |||
There was a problem hiding this comment.
Spelling error: 'folowing' should be 'following'
| Every **new** commit is automatically populated with the folowing metadata.. | |
| Every **new** commit is automatically populated with the following metadata.. |
| - **Hook services:** | ||
| - `MemoryContextLoader` — loads memories with configurable limits | ||
| - `ContextFormatter` — formats memories as structured markdown | ||
| - `SessionCaptureService` — scans recent commits via `LiberateService`, extracts memories |
There was a problem hiding this comment.
Should reference ExtractService not LiberateService. The SessionCaptureService delegates to ExtractService (see src/application/services/SessionCaptureService.ts line 28 which injects IExtractService, and line 41 which calls extractService.extract()). There is no LiberateService in the current codebase.
| - `SessionCaptureService` — scans recent commits via `LiberateService`, extracts memories | |
| - `SessionCaptureService` — scans recent commits via `ExtractService`, extracts memories |
| ### Added | ||
|
|
||
| - MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, liberate | ||
| - `git-mem init-mcp` command for MCP server configuration |
There was a problem hiding this comment.
The command name should be git-mem init not git-mem init-mcp. The CLI only exposes a unified init command that handles both hooks and MCP configuration. There is no separate init-mcp command (the init-mcp.ts file exists as a utility module but is not exposed as a separate command).
| - `git-mem init-mcp` command for MCP server configuration | |
| - `git-mem init` command for MCP server configuration |
Summary
CHANGELOG.mdwith v0.3.0 entry covering DI container, EventBus, Claude Code hooks, init-hooks command, and .git-mem.json configREADME.mdwith Quick Start, Claude Code Integration section (setup, hooks table, full config reference), MCP Server section, and architecture diagramCLAUDE.mdwith hook services/handlers in Application layer, EventBus in Infrastructure, hook entry points, EventBus + hook event flow in bootstrapping, updated test counts (265 unit / 46 integration), and hook-specific technical detailsCloses GIT-59
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Chores