feat: defer changes until claude stops

Author: joshuanapoli

.claude/settings.json

@@ -17,6 +17,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "poetry run python-claude ruff format"
+          },
           {
             "type": "command",
             "command": "poetry run python-claude ruff check"
@@ -36,17 +40,9 @@
       {
         "matcher": "Write|Edit",
         "hooks": [
-          {
-            "type": "command",
-            "command": "poetry run python-claude ruff format"
-          },
           {
             "type": "command",
             "command": "poetry run python-claude edited"
-          },
-          {
-            "type": "command",
-            "command": "poetry run python-claude mypy"
           }
         ]
       }

README.md

@@ -9,14 +9,15 @@ Python hooks for Claude Code for projects using:
 The hooks ensure that the quality tools are automatically used:
 
 Each time a file is edited:
-- Reformat with `ruff format`
-- Type-check with `mypy`
-- Record the file
+- Record the file for later processing
 
-When claude is ready to stop:
-- Repair lints of edited files with `ruff check --fix`. (We do not do this while editing files, becaue it Claude tends to add `import` statements in a dedicated edit, ahead of adding the code that uses it. In this case, `ruff check --fix` would erase the "unused" import.)
-- Run the tests with `pytest`.
+When Claude is ready to stop:
+- Reformat edited files with `ruff format`
+- Repair lints of edited files with `ruff check --fix`
+- Type-check edited files with `mypy`
+- Run the tests with `pytest`
 
+Note: We defer `ruff format` and `ruff check` until Claude stops to avoid changing files while Claude is working. Changing files during editing would spoil Claude's edits and force it to reread files.
 ## Installation
 
 ```bash
@@ -29,12 +30,12 @@ This package provides hooks that can be used with Claude Code's hook system.
 
 ### Available Commands
 
-- `edited` - Tracks edited Python files for deferred processing
+- `edited` - Tracks edited Python files for deferred processing (used in PostToolUse hook)
 - `git status` - Shows git status
-- `mypy` - Runs mypy type checking on edited files when used as a PostToolUse hook or all files when used as a Stop hook
+- `mypy` - Runs mypy type checking on edited files (used in Stop hook)
 - `pytest` - Runs pytest
-- `ruff check` - Runs ruff check on collected files with auto-fix
-- `ruff format` - Runs ruff format on edited files
+- `ruff check` - Runs ruff check on collected files with auto-fix (used in Stop hook)
+- `ruff format` - Runs ruff format on collected files (used in Stop hook)
 - `session start` - Prints introductory message about automatic hooks
 
 ### Claude Code Settings
@@ -61,6 +62,10 @@ Add hooks to your Claude Code settings.json:
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "poetry run python-claude ruff format"
+          },
           {
             "type": "command",
             "command": "poetry run python-claude ruff check"
@@ -80,17 +85,9 @@ Add hooks to your Claude Code settings.json:
       {
         "matcher": "Write|Edit",
         "hooks": [
-          {
-            "type": "command",
-            "command": "poetry run python-claude ruff format"
-          },
           {
             "type": "command",
             "command": "poetry run python-claude edited"
-          },
-          {
-            "type": "command",
-            "command": "poetry run python-claude mypy"
           }
         ]
       }

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-claude"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python hooks for Claude Code"
 authors = [{name = "CVector", email = "support@cvector.com"}]
 readme = "README.md"

src/python_claude/hooks/edited_hook.py

@@ -1,4 +1,4 @@
-"""Collects edited Python files for deferred ruff check."""
+"""Collects edited Python files for deferred processing."""
 
 from pathlib import Path
 
@@ -14,25 +14,34 @@ def __init__(self, hook_input: HookInput | None = None) -> None:
         super().__init__(hook_input)
 
     @property
-    def track_file(self) -> Path:
-        """Get the path to the edited files tracking file."""
+    def check_track_file(self) -> Path:
+        """Get the path to the ruff check tracking file."""
         return self.log_dir / "edited-files.txt"
 
-    def run(self) -> int:
-        """Track the edited file if it's a Python file."""
-        file_path = self.input.file_path
-        if not file_path or not self.is_python_file(file_path):
-            return 0
+    @property
+    def format_track_file(self) -> Path:
+        """Get the path to the ruff format tracking file."""
+        return self.log_dir / "format-files.txt"
 
-        # Read existing tracked files
+    def _track_file(self, track_file: Path, file_path: str) -> None:
+        """Add file to tracking file if not already present."""
         tracked_files: set[str] = set()
-        if self.track_file.exists():
-            tracked_files = set(self.track_file.read_text().strip().split("\n"))
+        if track_file.exists():
+            tracked_files = set(track_file.read_text().strip().split("\n"))
             tracked_files.discard("")
 
-        # Add file if not already tracked
         if file_path not in tracked_files:
-            with open(self.track_file, "a") as f:
+            with open(track_file, "a") as f:
                 f.write(f"{file_path}\n")
 
+    def run(self) -> int:
+        """Track the edited file if it's a Python file."""
+        file_path = self.input.file_path
+        if not file_path or not self.is_python_file(file_path):
+            return 0
+
+        # Track for both ruff check and ruff format
+        self._track_file(self.check_track_file, file_path)
+        self._track_file(self.format_track_file, file_path)
+
         return 0

src/python_claude/hooks/ruff_format_hook.py

@@ -2,32 +2,54 @@
 
 import subprocess
 import sys
+from pathlib import Path
 
 from python_claude.hooks.base import Hook, HookInput
 
 
 class RuffFormatHook(Hook):
-    """Runs ruff format on edited Python files."""
+    """Runs ruff format on all files collected during the session."""
 
     name = "ruff-format"
 
     def __init__(self, hook_input: HookInput | None = None) -> None:
         super().__init__(hook_input)
 
+    @property
+    def track_file(self) -> Path:
+        """Get the path to the format files tracking file."""
+        return self.log_dir / "format-files.txt"
+
     def run(self) -> int:
-        """Run ruff format on the edited file if it's a Python file."""
-        file_path = self.input.file_path
-        if not file_path or not self.is_python_file(file_path):
+        """Run ruff format on all tracked files."""
+        # Check if tracking file exists and has content
+        if not self.track_file.exists() or self.track_file.stat().st_size == 0:
+            self.log("No edited Python files to format")
+            return 0
+
+        files: list[str] = []
+        for line in self.track_file.read_text().strip().split("\n"):
+            file_path = line.strip()
+            if file_path and Path(file_path).exists():
+                files.append(file_path)
+
+        if not files:
+            self.log("No existing Python files to format")
+            self.track_file.unlink(missing_ok=True)
             return 0
 
-        self.log(file_path)
+        self.log(f"Formatting {len(files)} files: {' '.join(files)}")
 
         result = subprocess.run(
-            ["poetry", "run", "ruff", "format", file_path],
+            ["poetry", "run", "ruff", "format", *files],
             cwd=self.project_dir,
             stdout=sys.stderr,
         )
 
         exit_code = result.returncode
         self.log(f"exit {exit_code}")
+
+        if exit_code == 0:
+            self.track_file.unlink(missing_ok=True)
+
         return exit_code

tests/test_edited_hook.py

@@ -19,8 +19,11 @@ def test_tracks_python_file(self, tmp_path: Path) -> None:
             hook = EditedHook(hook_input)
             exit_code = hook.run()
             assert exit_code == 0
-            assert hook.track_file.exists()
-            assert "/test/file.py" in hook.track_file.read_text()
+            # Check both tracking files
+            assert hook.check_track_file.exists()
+            assert "/test/file.py" in hook.check_track_file.read_text()
+            assert hook.format_track_file.exists()
+            assert "/test/file.py" in hook.format_track_file.read_text()
 
     def test_ignores_non_python_file(self, tmp_path: Path) -> None:
         hook_input = HookInput(
@@ -32,7 +35,8 @@ def test_ignores_non_python_file(self, tmp_path: Path) -> None:
             hook = EditedHook(hook_input)
             exit_code = hook.run()
             assert exit_code == 0
-            assert not hook.track_file.exists()
+            assert not hook.check_track_file.exists()
+            assert not hook.format_track_file.exists()
 
     def test_does_not_duplicate_files(self, tmp_path: Path) -> None:
         hook_input = HookInput(
@@ -45,5 +49,8 @@ def test_does_not_duplicate_files(self, tmp_path: Path) -> None:
             hook1.run()
             hook2 = EditedHook(hook_input)
             hook2.run()
-            content = hook2.track_file.read_text()
-            assert content.count("/test/file.py") == 1
+            # Check both tracking files don't have duplicates
+            check_content = hook2.check_track_file.read_text()
+            assert check_content.count("/test/file.py") == 1
+            format_content = hook2.format_track_file.read_text()
+            assert format_content.count("/test/file.py") == 1

tests/test_ruff_format_hook.py

@@ -0,0 +1,17 @@
+"""Tests for RuffFormatHook."""
+
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+from python_claude.hooks.base import HookInput
+from python_claude.hooks.ruff_format_hook import RuffFormatHook
+
+
+class TestRuffFormatHook:
+    def test_no_files_to_format(self, tmp_path: Path) -> None:
+        hook_input = HookInput(session_id=None, tool_input={}, raw={})
+        with patch.dict(os.environ, {"CLAUDE_PROJECT_DIR": str(tmp_path)}):
+            hook = RuffFormatHook(hook_input)
+            exit_code = hook.run()
+            assert exit_code == 0