Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: document Claude Code Windows hook runner

AkitaOnRailsff8a926c79ba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5eece20c..1c8d1518 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ 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).
## [Unreleased]
+### Fixed
+- Claude Code hook installs on native Windows now render Git Bash-compatible
+ `bash -c` commands that keep the POSIX `.sh` hook scripts and convert
+ drive-letter paths to Git Bash paths, matching Claude Code's actual hook
+ runner instead of emitting PowerShell commands ([#45]).
## [0.5.1] - 2026-05-27
### Changed
diff --git a/README.md b/README.md
index e017e3b6..3af2f73c 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@
| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. |
| macOS | Supported | Workspace tests run in CI; native source builds are supported. Docker images run natively on Apple Silicon via the `linux/arm64` manifest. |
| Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |
-| Native Windows | Experimental | PowerShell wrapper and `.ps1` hooks are available; real agent harness feedback still needed. See [`docs/windows.md`](docs/windows.md). |
+| Native Windows | Experimental | PowerShell wrapper is available. Claude Code uses Git Bash `.sh` hooks on native Windows; other script-hook agents use the current PowerShell defaults pending harness feedback. See [`docs/windows.md`](docs/windows.md). |
| Claude Code | Supported | MCP config + lifecycle hooks. |
| Codex | Supported | MCP config + lifecycle hooks. |
| OpenCode | Supported | Remote MCP config + generated TypeScript plugin. |
@@ -236,9 +236,10 @@ use `--mcp-url` if you installed MCP with a custom endpoint, and
### Install Notes
-- **Windows:** use the Linux path inside WSL2, or the native PowerShell
- wrapper and `.ps1` hooks for native Windows agents. Do not mix path
- worlds. See [`docs/windows.md`](docs/windows.md).
+- **Windows:** use the Linux path inside WSL2, or the native Windows wrapper
+ from PowerShell/cmd. Native Claude Code uses Git Bash `.sh` hooks; other
+ script-hook agents use PowerShell defaults. Do not mix path worlds. See
+ [`docs/windows.md`](docs/windows.md).
- **Docker compose:** `docker compose -f docker/docker-compose.yml up -d`
is supported; agent setup is the same as step 3 above.
- **Remote server:** set `AI_MEMORY_SERVER_URL=http://<server-ip>:49374`
diff --git a/docs/install.md b/docs/install.md
index fda3f6c0..42b151ec 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -410,6 +410,9 @@ Cursor, Gemini CLI, Antigravity CLI, and OpenClaw have lifecycle capture paths t
> Gemini CLI, and Antigravity CLI use shell/PowerShell hook scripts: (1) `docker cp` the
> bundled scripts to your home dir, (2) `docker run --rm install-hooks`
> to render the config snippet.
+> On native Windows, Claude Code is the exception to the PowerShell default:
+> it runs hooks through Git Bash, so ai-memory renders `bash -c` commands for
+> the `.sh` scripts.
> OpenClaw, OpenCode, and OMP are different: they use generated
> TypeScript plugin/extension files, so no shell-script extraction is
> needed for those clients.
@@ -609,8 +612,9 @@ server's environment.
On Windows, see [`docs/windows.md`](windows.md). The short version: run
the install commands from the same environment that launches the agent.
-WSL2-launched agents need WSL paths and POSIX `.sh` hooks; native Windows
-agents need Windows paths and PowerShell `.ps1` hooks.
+WSL2-launched agents need WSL paths and POSIX `.sh` hooks. Native Claude Code
+uses Git Bash `.sh` hooks with Windows paths converted to `/c/...`; other
+native Windows script-hook agents use PowerShell `.ps1` defaults.
When run from source, `install-hooks` finds the bundled scripts in
the repo's `hooks/` automatically:
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 05d202b9..fb2db0b2 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -23,7 +23,9 @@ Claude Code, OpenAI Codex, Cursor, Gemini CLI, Antigravity CLI, OpenClaw, OpenCo
OMP have automatic capture integrations (shell/PowerShell hooks for
Claude Code / Codex / Cursor / Gemini CLI / Antigravity CLI, TypeScript plugin/extension
files for OpenClaw / OpenCode / OMP) and are covered in the
-[main README](../README.md#quick-start).
+[main README](../README.md#quick-start). On native Windows, Claude Code uses
+Git Bash `.sh` hooks rather than the PowerShell default used by other
+script-hook agents.
Claude Desktop is **MCP-only** here: it exposes long-term memory to its
LLM via ai-memory's MCP tools (`memory_query`, `memory_recent`,
diff --git a/docs/windows.md b/docs/windows.md
index 1b124055..dee4b750 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -16,7 +16,11 @@ launches Claude Code, Codex, Cursor, Gemini CLI, or another agent.
The difference matters because hook configs contain executable paths.
WSL2 agents need Linux paths and POSIX `.sh` hooks. Native Windows
-agents need Windows paths and PowerShell `.ps1` hooks.
+agents need Windows paths, but the hook runner is agent-specific:
+Claude Code invokes hooks through Git Bash, so ai-memory renders
+`bash -c` commands that call `.sh` scripts with Git Bash paths
+(`/c/Users/...`). Other native Windows script-hook agents keep the
+PowerShell `.ps1` default until their harness behavior is verified.
## Scenario A: Everything Inside WSL2
@@ -93,12 +97,14 @@ ai-memory install-hooks --agent claude-code --apply
```
In this mode, the PowerShell wrapper runs the Linux container but tells
-the CLI to render Windows hook commands:
+the CLI to render hook commands for the native Windows agent:
- Config files are written through the mounted Windows home directory.
- Hook scripts are staged under `$HOME\.local\share\ai-memory\hooks\`.
-- Hook commands explicitly call `powershell.exe`.
-- Hook commands point at `.ps1` scripts.
+- Claude Code hook commands call `bash -c` and point at `.sh` scripts using
+ Git Bash paths such as `/c/Users/alice/...`.
+- Other native Windows script-hook agents currently call `powershell.exe` and
+ point at `.ps1` scripts.
Use the matching `--client` / `--agent` values for other clients, for
example `codex`, `cursor`, or `gemini-cli`.
@@ -130,17 +136,20 @@ target\debug\ai-memory.exe install-mcp --client claude-code --apply
target\debug\ai-memory.exe install-hooks --agent claude-code --apply
```
-Native Windows builds automatically render `.ps1` lifecycle hooks. The
-hook bundle ships matching `.sh` and `.ps1` event scripts, and tests
-enforce one-to-one event/agent parity between them.
+Native Windows builds render agent-specific lifecycle hooks. Claude Code uses
+Git Bash-compatible `.sh` commands on native Windows; other script-hook agents
+use the PowerShell `.ps1` default. The hook bundle ships matching `.sh` and
+`.ps1` event scripts, and tests enforce one-to-one event/agent parity between
+them.
## Current Harness Caveats
Windows hook support is new and needs real-world testing against native
Windows agent builds.
-- Claude Code may be used natively on Windows or from inside WSL2. Test
- which process launches the hooks before assuming path format.
+- Claude Code may be used natively on Windows or from inside WSL2. Native
+ Claude Code invokes hooks through Git Bash; WSL2 Claude Code uses normal
+ WSL paths.
- Codex, OpenCode, Cursor, Gemini CLI, and OpenClaw may each choose different
Windows config locations or shell execution behavior. ai-memory uses
the current best-known defaults, but they need validation on real
@@ -166,8 +175,9 @@ For native Windows:
1. Run all install commands from PowerShell or `cmd.exe` using
`ai-memory` / `ai-memory.ps1`.
-2. Confirm generated hook commands reference `.ps1` files under your
- Windows home directory.
+2. Confirm generated hook commands match the agent: Claude Code should use
+ `bash -c` plus `.sh` files with `/c/...` Git Bash paths; other script-hook
+ agents should use `.ps1` files under your Windows home directory.
3. Launch the native Windows agent.
4. Call `memory_status` from the agent.
5. Send a prompt, then run `ai-memory status` or `ai-memory recent`.