Skip to content

Add Windows support and cross-platform hook system#161

Draft
nhorton wants to merge 3 commits intomainfrom
claude/deepwork-windows-support-V5ImW
Draft

Add Windows support and cross-platform hook system#161
nhorton wants to merge 3 commits intomainfrom
claude/deepwork-windows-support-V5ImW

Conversation

@nhorton
Copy link
Contributor

@nhorton nhorton commented Jan 26, 2026

Summary

This PR adds full Windows support to DeepWork and refactors the hook system to be cross-platform. The main changes include:

  1. Windows Installation & Distribution: Added PowerShell-based installer scripts and PyInstaller configuration to build standalone Windows executables that can be distributed without Python.

  2. Cross-Platform Hook System: Migrated from shell script-based hooks to Python module-based hooks that work on Windows, macOS, and Linux without requiring bash.

  3. Documentation: Added comprehensive Windows installation guide and updated README with Windows support information.

Key Changes

Windows Support

  • scripts/build-windows.ps1: PowerShell script to build standalone Windows executable using PyInstaller
  • scripts/install-windows.ps1: PowerShell installer that downloads/installs DeepWork and adds it to user PATH
  • scripts/install-windows.bat: Batch wrapper for PowerShell installer
  • .github/workflows/build-windows.yml: GitHub Actions workflow to automatically build and release Windows executables
  • scripts/deepwork.spec: PyInstaller spec file for building the Windows executable
  • doc/installation/windows.md: Comprehensive Windows installation guide with troubleshooting

Cross-Platform Hook System

  • src/deepwork/hooks/user_prompt_submit.py: New Python module hook (replaces shell script) that captures work tree state at prompt submission
  • src/deepwork/hooks/capture_prompt.py: Cross-platform work tree capture utility (replaces capture_prompt_work_tree.sh)
  • src/deepwork/hooks/hook_entry.py: Entry point for invoking hooks via deepwork hook <name> command
  • Updated hook configuration: Changed from shell script paths to deepwork hook <name> commands in settings files

Code Updates

  • src/deepwork/core/hooks_syncer.py: Updated to generate cross-platform commands and use forward slashes in paths (works in bash on all platforms)
  • src/deepwork/core/adapters.py: Removed Windows-specific bash permission requirement for job scripts (no longer needed with Python hooks)
  • .claude/settings.json: Updated hook configuration to use deepwork hook commands
  • .deepwork/jobs/deepwork_rules/hooks/global_hooks.yml: Migrated to Python module-based hooks
  • src/deepwork/hooks/__init__.py: Updated documentation to reflect cross-platform approach

Tests

  • tests/unit/test_cross_platform_hooks.py: New test suite for cross-platform hook implementations
  • tests/unit/test_adapters.py: Updated permission count assertions (removed job script bash permission)

Documentation

  • README.md: Added Windows platform support note and Windows installation section
  • .gitignore: Added exception to keep scripts/deepwork.spec in version control

Implementation Details

Why Python Modules for Hooks?

  • Cross-platform compatibility: Works on Windows, macOS, and Linux without bash dependencies
  • Consistent behavior: Same code path regardless of platform or installation method
  • Better integration: Hooks can directly import DeepWork modules instead of shelling out

Path Handling

  • Hook commands use forward slashes (e.g., .deepwork/jobs/test/hooks/script.sh) which work in bash on all platforms including Windows (via Git Bash/WSL)
  • The deepwork hook <name> command works everywhere regardless of how DeepWork was installed (pip, pipx, Windows EXE, etc.)

Windows Executable Distribution

  • PyInstaller bundles Python and all dependencies into a single .exe file
  • GitHub Actions automatically builds and releases Windows executables on each release
  • Users can download pre-built executables or build from source

- Add PyInstaller spec for building standalone Windows executable
- Create PowerShell and batch installer scripts for Windows PATH setup
- Convert bash hook scripts to cross-platform Python modules
- Update hooks_syncer to use forward slashes for path compatibility
- Add GitHub Actions workflow for automated Windows builds on release
- Add Windows installation documentation

Cross-platform hooks now use `deepwork hook <name>` command format
which works on Windows, macOS, and Linux regardless of installation method.
Remove the old bash-based hook scripts that have been replaced by
cross-platform Python modules:
- user_prompt_submit.sh -> deepwork.hooks.user_prompt_submit
- capture_prompt_work_tree.sh -> deepwork.hooks.capture_prompt

Also removes duplicate UserPromptSubmit hook entry from settings.json.
- Update architecture.md to reflect cross-platform Python hooks
- Remove references to deprecated bash scripts
- Update hook system diagrams and descriptions
- Bump version to 0.6.0 for Windows support feature
- Add changelog entry documenting all changes
@nhorton nhorton marked this pull request as draft January 29, 2026 15:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants