Plugin hooks fail on NixOS, Windows, and macOS without Homebrew

[ncrmro]

GitHub Issue: Plugin hooks fail on NixOS, Windows, and macOS without Homebrew

Repo: Unsupervisedcom/deepwork

Title: Plugin hooks fail on NixOS, Windows, and macOS without Homebrew

---

Summary

The Claude Code plugin distribution model assumes /bin/bash, jq, and uvx are available in all environments. This breaks on NixOS/Nix containers, Windows, and potentially macOS without Homebrew.

Issues

1. #!/bin/bash shebang fails on NixOS

All 11 shell scripts use #!/bin/bash, but /bin/bash does not exist in NixOS or Nix container environments. Bash is only available via /nix/store/.../bin/bash.

Error:

session_stop.sh: cannot execute: required file not found

Affected files:

• plugins/claude/hooks/post_compact.sh
• plugins/claude/hooks/post_commit_reminder.sh
• learning_agents/hooks/session_stop.sh
• learning_agents/hooks/post_task.sh
• learning_agents/scripts/*.sh (5 files)
• src/deepwork/hooks/claude_hook.sh
• src/deepwork/hooks/gemini_hook.sh

Fix: Change to #!/usr/bin/env bash (already used by make_new_job.sh in this repo).

2. jq not available on PATH

Three hook scripts depend on jq for JSON parsing: post_compact.sh, post_commit_reminder.sh, and post_task.sh. Hook scripts are invoked directly by Claude Code (not as deepwork subprocesses), so they inherit the shell's PATH.

• NixOS: jq is not on PATH unless the consumer's devShell includes it
• macOS: jq is not installed by default (requires Homebrew: brew install jq)
• Windows: jq is not available by default

Fix: Add graceful degradation guards (command -v jq) so hooks silently no-op instead of crashing. Document jq as a recommended dependency.

3. Plugin .mcp.json uses uvx, bypasses Nix-installed binary

The plugin's .mcp.json uses "command": "uvx" to fetch deepwork from PyPI. When deepwork is already installed via Nix flake, the binary is on PATH but uvx ignores it and tries to download from PyPI instead.

• NixOS: uvx/uv may not be available at all
• Windows: uvx fails initially (but recovers after installing uv)

Fix: deepwork install / deepwork repair should detect the environment (e.g., check if which deepwork resolves to /nix/store/) and write a project-level .mcp.json with "command": "deepwork" to override the plugin default.

4. Repair errata removes project .mcp.json indiscriminately

The repair workflow's errata step (Step 5) removes any deepwork serve entry from the project-level .mcp.json. This would delete a Nix-specific "command": "deepwork" override that is intentionally there.

Fix: Only remove uvx-based entries. Preserve entries that use "command": "deepwork" directly.

Platforms Affected

Platform	Shebang	jq	uvx/MCP
NixOS / Nix containers	Fails (/bin/bash missing)	Missing	Bypasses Nix binary
Windows	N/A (no bash)	Missing	Fails (recovers after installing uv)
macOS (no Homebrew)	Works	Missing	Works
macOS (with Homebrew)	Works	Works (if installed)	Works
Linux (non-Nix)	Works	Usually available	Works

Environment Details (NixOS reproduction)

$ which bash
/nix/store/.../bin/bash

$ ls /bin/bash
ls: cannot access '/bin/bash': No such file or directory

$ which jq
jq NOT FOUND

$ which deepwork
/nix/store/iqwsz1iaxc3qaamp97zcc25awviz0dcr-deepwork-wrapped/bin/deepwork