feat: build claude-code from source for version control

.github/workflows/update-claude-code.yml

@@ -0,0 +1,63 @@
+name: Update Claude Code
+
+on:
+  schedule:
+    # Run daily at 6 AM UTC
+    - cron: '0 6 * * *'
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v30
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+
+      - name: Update claude-code package
+        id: update
+        run: |
+          # Script exits 0 if already at latest (no changes to commit)
+          ./nix/claude-code/update.sh
+
+          # Capture version for PR title
+          VERSION=$(grep 'version = "' nix/claude-code/package.nix | head -1 | sed 's/.*version = "\([^"]*\)".*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Update flake.lock
+        run: nix flake update
+
+      - name: Verify build
+        run: nix develop --command claude --version
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(deps): update claude-code to ${{ steps.update.outputs.version }}"
+          title: "chore(deps): update claude-code to ${{ steps.update.outputs.version }}"
+          body: |
+            Automated update of claude-code package.
+
+            **Changes:**
+            - claude-code updated to ${{ steps.update.outputs.version }}
+            - Updated flake.lock
+
+            **Verification:**
+            - Package builds successfully
+            - `claude --version` returns expected version
+
+            ---
+            *This PR was automatically created by the update-claude-code workflow.*
+          branch: update-claude-code
+          delete-branch: true

CONTRIBUTING.md

@@ -145,11 +145,13 @@ The Nix environment provides:
 | Tool | Description |
 |------|-------------|
 | `deepwork` | CLI using your local source code (editable install) |
+| `claude` | Claude Code CLI (built from source for version control) |
 | `pytest` | Test runner with all plugins |
 | `ruff` | Fast Python linter and formatter |
 | `mypy` | Static type checker |
 | `uv` | Python package manager |
 | `python` | Python 3.11 interpreter |
+| `update` | Updates claude-code and flake inputs |
 
 #### CI Usage
 
@@ -161,6 +163,25 @@ nix develop --command ruff check src/
 nix develop --command mypy src/
 ```
 
+#### Updating Development Dependencies
+
+The Nix environment includes Claude Code built from source to ensure version control (the nixpkgs version can lag behind npm releases). Use the `update` command to keep dependencies current:
+
+```bash
+# In the dev shell - updates claude-code and flake inputs
+update
+```
+
+To manually update Claude Code:
+
+```bash
+./nix/claude-code/update.sh
+```
+
+This fetches the latest version from npm, computes the necessary hashes using `prefetch-npm-deps`, and updates `package.nix` automatically.
+
+A GitHub Action automatically checks for new Claude Code versions daily and creates PRs when updates are available.
+
 ### Option 2: Manual Setup (Without Nix)
 
 If you prefer not to use Nix:

flake.nix

@@ -14,6 +14,8 @@
           # Allow unfree packages to support the Business Source License 1.1
           config.allowUnfree = true;
         };
+        # Local claude-code package for version control (update via nix/claude-code/update.sh)
+        claude-code = pkgs.callPackage ./nix/claude-code/package.nix { };
         # Read version from pyproject.toml to avoid duplication
         pyproject = builtins.fromTOML (builtins.readFile ./pyproject.toml);
         deepwork = pkgs.python311Packages.buildPythonPackage {
@@ -44,8 +46,8 @@
             # System tools
             jq  # For JSON processing
 
-            # CLI tools
-            claude-code  # Claude Code CLI
+            # CLI tools (claude-code is locally built, see nix/claude-code/)
+            claude-code
             gh           # GitHub CLI
           ];
 
@@ -79,6 +81,9 @@
             # Set PYTHONPATH for editable install access to src/
             export PYTHONPATH="$PWD/src:$PYTHONPATH"
 
+            # Add nix/ scripts to PATH (for 'update' command)
+            export PATH="$PWD/nix:$PATH"
+
             # Only show welcome message in interactive shells
             if [[ $- == *i* ]]; then
               echo ""
@@ -94,6 +99,7 @@
               echo "  mypy src/          Type check"
               echo "  claude-code        Claude Code CLI"
               echo "  gh                 GitHub CLI"
+              echo "  update             Update claude-code and flake inputs"
               echo ""
             fi
           '';