claude-commit 0.1.1__tar.gz → 0.3.0__tar.gz

{claude_commit-0.1.1/src/claude_commit.egg-info → claude_commit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-commit
-Version: 0.1.1
+Version: 0.3.0
 Summary: AI-powered git commit message generator using Claude Agent SDK
 Author-email: Johannlai <johannli666@gmail.com>
 License: MIT
@@ -27,7 +27,7 @@ Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
-# claude-commit
+# claude-commit [![PyPI version](https://badge.fury.io/py/claude-commit.svg)](https://badge.fury.io/py/claude-commit)
 
 🤖 AI-powered git commit message generator using Claude Agent SDK and Claude Code CLI
 
@@ -35,23 +35,9 @@ Dynamic: license-file
 
 `claude-commit` uses Claude AI to analyze your code changes and write meaningful commit messages. Claude reads your files, understands the context, and generates commit messages following best practices.
 
-## Quick Start
+## Demo
 
-**Install:**
-```bash
-pip install claude-commit
-
-# Required dependency
-npm install -g @anthropic-ai/claude-code
-```
-
-**Use:**
-```bash
-git add .
-claude-commit --commit
-```
-
-That's it! Claude will analyze your changes and create a commit.
+[![asciicast](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L.svg)](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L?autoplay=1&speed=3)
 
 ## Installation
 
@@ -61,19 +47,44 @@ That's it! Claude will analyze your changes and create a commit.
 - Node.js
 - Git
 
-### Install Steps
+### Recommended: pipx (for CLI tools)
+
+`pipx` is the **best way to install Python CLI tools**. It creates isolated environments automatically:
 
 ```bash
-# 1. Install Claude Code CLI (required)
-npm install -g @anthropic-ai/claude-code
+# 1. Install pipx
+brew install pipx              # macOS
+# or
+pip install --user pipx        # Linux/Windows
+pipx ensurepath
 
-# 2. Install claude-commit
-pip install claude-commit
+# 2. Install Claude Code CLI (required)
+npm install -g @anthropic-ai/claude-code
 
-# Or use pipx for isolation
+# 3. Install claude-commit
 pipx install claude-commit
 ```
 
+### Alternative: pip
+
+If you prefer pip, use one of these methods:
+
+**Option 1: User installation (no admin rights needed)**
+```bash
+# Install to user directory
+pip install --user claude-commit
+
+# Make sure ~/.local/bin is in your PATH
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**Option 2: Virtual environment**
+```bash
+python3 -m venv ~/.venvs/claude-commit
+source ~/.venvs/claude-commit/bin/activate
+pip install claude-commit
+```
+
 ### Authentication
 
 `claude-commit` supports two ways to authenticate with Claude:
@@ -138,7 +149,7 @@ Create shortcuts for common commands:
 # Install to your shell config
 claude-commit alias install
 
-# Activate in current terminal
+# Activate in current terminal. Very important!
 source ~/.zshrc    # zsh
 source ~/.bashrc   # bash
 ```
@@ -238,28 +249,103 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
 ## Troubleshooting
 
-**Claude Code not found?**
+### Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+
+```
+Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+Error output: Check stderr output for details
+Traceback (most recent call last):
+```
+
+**Solution**: This error means you haven't authenticated with Claude. Choose one method:
+
+**Method A: Official Claude Code login (recommended)**
+```bash
+claude
+```
+
+**Method B: Set custom API endpoint**
+```bash
+export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"
+export ANTHROPIC_AUTH_TOKEN="your-auth-token"
+# model name (optional)
+export ANTHROPIC_MODEL="your-model-name"
+
+# Add to ~/.zshrc or ~/.bashrc to persist
+echo 'export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"' >> ~/.zshrc
+echo 'export ANTHROPIC_AUTH_TOKEN="your-auth-token"' >> ~/.zshrc
+```
+
+### "externally-managed-environment" error (macOS/Linux)
+
+If you see this error when using `pip install`:
+
+```
+error: externally-managed-environment
+```
+
+**Solution**: Use `pipx` (recommended for CLI tools):
+```bash
+brew install pipx
+pipx install claude-commit
+```
+
+Or use `pip install --user`:
+```bash
+pip install --user claude-commit
+```
+
+**Why this happens**: Modern Python installations (Python 3.11+) protect the system Python to prevent conflicts. This is not a bug in `claude-commit`.
+
+### Claude Code not found
+
 ```bash
 npm install -g @anthropic-ai/claude-code
 ```
 
-**No changes detected?**
+### No changes detected
+
 ```bash
 git add .              # stage changes
 # or
 claude-commit --all    # include unstaged
 ```
 
-**Analysis too slow?**
+### Analysis too slow
+
 ```bash
 claude-commit --max-diff-lines 200
 ```
 
+### Command not found after installation
+
+If `claude-commit` is not found after installation:
+
+**With pipx:**
+```bash
+pipx ensurepath
+# Restart your terminal
+```
+
+**With pip --user:**
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### Aliases not working
+
+```bash
+claude-commit alias install
+source ~/.zshrc  # or ~/.bashrc
+```
+
 ## Development
 
 ```bash
 # Clone and setup
-git clone https://github.com/yourusername/claude-commit.git
+git clone https://github.com/JohannLai/claude-commit.git
 cd claude-commit
 python -m venv venv
 source venv/bin/activate
@@ -285,7 +371,9 @@ MIT License - see [LICENSE](LICENSE) file
 
 - [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk)
 - [Conventional Commits](https://www.conventionalcommits.org/)
-- [Issue Tracker](https://github.com/yourusername/claude-commit/issues)
+- [GitHub Repository](https://github.com/JohannLai/claude-commit)
+- [PyPI Package](https://pypi.org/project/claude-commit/)
+- [Issue Tracker](https://github.com/JohannLai/claude-commit/issues)
 
 ---
 

{claude_commit-0.1.1 → claude_commit-0.3.0}/README.md

@@ -1,4 +1,4 @@
-# claude-commit
+# claude-commit [![PyPI version](https://badge.fury.io/py/claude-commit.svg)](https://badge.fury.io/py/claude-commit)
 
 🤖 AI-powered git commit message generator using Claude Agent SDK and Claude Code CLI
 
@@ -6,23 +6,9 @@
 
 `claude-commit` uses Claude AI to analyze your code changes and write meaningful commit messages. Claude reads your files, understands the context, and generates commit messages following best practices.
 
-## Quick Start
+## Demo
 
-**Install:**
-```bash
-pip install claude-commit
-
-# Required dependency
-npm install -g @anthropic-ai/claude-code
-```
-
-**Use:**
-```bash
-git add .
-claude-commit --commit
-```
-
-That's it! Claude will analyze your changes and create a commit.
+[![asciicast](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L.svg)](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L?autoplay=1&speed=3)
 
 ## Installation
 
@@ -32,19 +18,44 @@ That's it! Claude will analyze your changes and create a commit.
 - Node.js
 - Git
 
-### Install Steps
+### Recommended: pipx (for CLI tools)
+
+`pipx` is the **best way to install Python CLI tools**. It creates isolated environments automatically:
 
 ```bash
-# 1. Install Claude Code CLI (required)
-npm install -g @anthropic-ai/claude-code
+# 1. Install pipx
+brew install pipx              # macOS
+# or
+pip install --user pipx        # Linux/Windows
+pipx ensurepath
 
-# 2. Install claude-commit
-pip install claude-commit
+# 2. Install Claude Code CLI (required)
+npm install -g @anthropic-ai/claude-code
 
-# Or use pipx for isolation
+# 3. Install claude-commit
 pipx install claude-commit
 ```
 
+### Alternative: pip
+
+If you prefer pip, use one of these methods:
+
+**Option 1: User installation (no admin rights needed)**
+```bash
+# Install to user directory
+pip install --user claude-commit
+
+# Make sure ~/.local/bin is in your PATH
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**Option 2: Virtual environment**
+```bash
+python3 -m venv ~/.venvs/claude-commit
+source ~/.venvs/claude-commit/bin/activate
+pip install claude-commit
+```
+
 ### Authentication
 
 `claude-commit` supports two ways to authenticate with Claude:
@@ -109,7 +120,7 @@ Create shortcuts for common commands:
 # Install to your shell config
 claude-commit alias install
 
-# Activate in current terminal
+# Activate in current terminal. Very important!
 source ~/.zshrc    # zsh
 source ~/.bashrc   # bash
 ```
@@ -209,28 +220,103 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
 ## Troubleshooting
 
-**Claude Code not found?**
+### Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+
+```
+Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+Error output: Check stderr output for details
+Traceback (most recent call last):
+```
+
+**Solution**: This error means you haven't authenticated with Claude. Choose one method:
+
+**Method A: Official Claude Code login (recommended)**
+```bash
+claude
+```
+
+**Method B: Set custom API endpoint**
+```bash
+export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"
+export ANTHROPIC_AUTH_TOKEN="your-auth-token"
+# model name (optional)
+export ANTHROPIC_MODEL="your-model-name"
+
+# Add to ~/.zshrc or ~/.bashrc to persist
+echo 'export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"' >> ~/.zshrc
+echo 'export ANTHROPIC_AUTH_TOKEN="your-auth-token"' >> ~/.zshrc
+```
+
+### "externally-managed-environment" error (macOS/Linux)
+
+If you see this error when using `pip install`:
+
+```
+error: externally-managed-environment
+```
+
+**Solution**: Use `pipx` (recommended for CLI tools):
+```bash
+brew install pipx
+pipx install claude-commit
+```
+
+Or use `pip install --user`:
+```bash
+pip install --user claude-commit
+```
+
+**Why this happens**: Modern Python installations (Python 3.11+) protect the system Python to prevent conflicts. This is not a bug in `claude-commit`.
+
+### Claude Code not found
+
 ```bash
 npm install -g @anthropic-ai/claude-code
 ```
 
-**No changes detected?**
+### No changes detected
+
 ```bash
 git add .              # stage changes
 # or
 claude-commit --all    # include unstaged
 ```
 
-**Analysis too slow?**
+### Analysis too slow
+
 ```bash
 claude-commit --max-diff-lines 200
 ```
 
+### Command not found after installation
+
+If `claude-commit` is not found after installation:
+
+**With pipx:**
+```bash
+pipx ensurepath
+# Restart your terminal
+```
+
+**With pip --user:**
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### Aliases not working
+
+```bash
+claude-commit alias install
+source ~/.zshrc  # or ~/.bashrc
+```
+
 ## Development
 
 ```bash
 # Clone and setup
-git clone https://github.com/yourusername/claude-commit.git
+git clone https://github.com/JohannLai/claude-commit.git
 cd claude-commit
 python -m venv venv
 source venv/bin/activate
@@ -256,7 +342,9 @@ MIT License - see [LICENSE](LICENSE) file
 
 - [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk)
 - [Conventional Commits](https://www.conventionalcommits.org/)
-- [Issue Tracker](https://github.com/yourusername/claude-commit/issues)
+- [GitHub Repository](https://github.com/JohannLai/claude-commit)
+- [PyPI Package](https://pypi.org/project/claude-commit/)
+- [Issue Tracker](https://github.com/JohannLai/claude-commit/issues)
 
 ---
 

{claude_commit-0.1.1 → claude_commit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-commit"
-version = "0.1.1"
+version = "0.3.0"
 description = "AI-powered git commit message generator using Claude Agent SDK"
 readme = "README.md"
 requires-python = ">=3.9"

{claude_commit-0.1.1 → claude_commit-0.3.0}/src/claude_commit/main.py

@@ -6,29 +6,28 @@ Analyzes your git repository changes and generates a meaningful commit message
 using Claude's AI capabilities.
 """
 
-import sys
-import asyncio
 import argparse
+import asyncio
+import sys
+import time
 from pathlib import Path
 from typing import Optional
-import time
 
-from rich.console import Console
-from rich.panel import Panel
-from rich.progress import Progress, SpinnerColumn, TextColumn
 import pyperclip
-
 from claude_agent_sdk import (
-    query,
-    ClaudeAgentOptions,
     AssistantMessage,
-    TextBlock,
-    ToolUseBlock,
-    ToolResultBlock,
-    ResultMessage,
+    ClaudeAgentOptions,
     CLINotFoundError,
     ProcessError,
+    ResultMessage,
+    TextBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    query,
 )
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from .config import Config, resolve_alias
 
@@ -40,10 +39,42 @@ SYSTEM_PROMPT = """You are an expert software engineer tasked with analyzing cod
 Your goal: Generate a clear, accurate, and meaningful commit message that captures the essence of the changes.
 
 Available tools you can use:
-- Bash: Run git commands (git diff, git status, git log, etc.) and other shell commands
-- Read: Read any file in the repository to understand context
-- Grep: Search for patterns across files to understand relationships
-- Glob: Find files matching patterns
+
+1. **Bash**: Run git commands and shell commands
+   - `git log`, `git status`, `git diff`, `git show`
+   - Any shell commands for system inspection
+
+2. **Read**: Read file contents to understand context
+   - Read modified files to understand their purpose
+   - Read related files to understand dependencies
+   - Can specify line ranges for large files: `{"file_path": "file.py", "offset": 10, "limit": 50}`
+   - Supports images (returns base64 encoded data)
+
+3. **Grep** (⭐ POWERFUL - use extensively!): Search patterns across files
+   - Search for function/class definitions: `grep -n "def function_name"` or `grep -n "class ClassName"`
+   - Find where functions are called: `grep -n "function_name("`
+   - Search for imports: `grep -n "from module import"` or `grep -n "import package"`
+   - Find variable usage: `grep -n "variable_name"`
+   - Search with context: use -A (after), -B (before), -C (context) flags
+   - Case-insensitive search: use -i flag
+   - Search in specific file types: use --type flag (e.g., `--type py`)
+   - Count occurrences: use --output_mode count
+   - Limit results: use head_limit parameter
+   - **Why Grep is powerful**: It helps you understand code relationships WITHOUT reading entire files
+     * See where a modified function is called (usage impact)
+     * Find related functions or classes (context)
+     * Understand dependencies (imports and references)
+     * Discover patterns across the codebase
+
+4. **Glob**: Find files matching patterns
+   - `*.py`, `**/*.js`, `**/test_*.py`
+   - Useful to find related files (e.g., test files, config files)
+
+5. **Edit** (⭐ USEFUL for analysis): Make precise edits
+   - **NOTE**: You won't actually edit files, but you can use this tool's pattern matching to understand complex changes
+   - Helps identify exact strings in files when git diff is unclear
+   - Can search for specific code patterns: `{"file_path": "file.py", "old_string": "pattern to find"}`
+   - Useful when you need to understand multi-line changes or context around changes
 
 Analysis approach (you decide what's necessary):
 1. IMPORTANT: First check recent commit history (git log -10 --oneline or git log -10 --pretty=format:"%s") to understand the existing commit message style
@@ -56,12 +87,35 @@ Analysis approach (you decide what's necessary):
    - The purpose and context of changed functions/classes
    - How the changes fit into the larger codebase
    - The intent behind the modifications
-4. Search for related code (grep) to understand dependencies and impacts
+4. **USE GREP extensively** to understand code relationships (examples):
+   - Modified function `process_data()`? → `grep -n "process_data("` to see where it's called
+   - New class `UserManager`? → `grep -n "class.*Manager"` to find similar patterns
+   - Imports changed? → `grep -n "from new_module import"` to see usage
+   - Refactoring? → `grep --output_mode count "old_pattern"` to understand scope
+   - Want context? → `grep -C 5 "function_name"` to see surrounding code
+   - Find test files? → `grep -n "test_function_name"` or use glob `**/test_*.py`
 5. Consider the scope: is this a feature, fix, refactor, docs, chore, etc.?
 
+**Pro tip**: Grep is faster than reading entire files. Use it to quickly assess impact before deciding which files to read in detail.
+
 Commit message guidelines:
-- **FOLLOW THE EXISTING FORMAT**: Match the style, language, and conventions used in recent commits
+- **MUST FOLLOW THE EXISTING FORMAT**: Match the style, language, and conventions used in recent commits
 - If no clear pattern exists in history, use conventional commits format (feat:, fix:, docs:, refactor:, test:, chore:, style:, perf:)
+    - feat: for new features
+    - fix: for bug fixes
+    - docs: for documentation changes
+    - refactor: for code refactoring
+    - test: for test changes
+    - chore: for chore changes
+    - style: for style changes
+    - perf: for performance improvements
+    - build: for build changes
+    - ci: for CI/CD changes
+    - revert: for reverting changes
+    - feat!: for breaking changes
+    - fix!: for breaking bug fixes
+    - perf!: for breaking performance improvements
+    - chore!: for breaking chore changes
 - First line: < 50 chars (or follow existing convention), imperative mood, summarize the main change
 - **IMPORTANT**: Use multi-line format with bullet points for detailed changes:
   ```
@@ -77,15 +131,23 @@ Commit message guidelines:
 
 Examples of excellent commit messages (multi-line format):
 
-Conventional commits style:
+Conventional commits style(Remember to follow the existing format):
 ```
+# for new features
 feat: add user authentication system
 
 - Implement JWT-based authentication with refresh tokens
 - Add login and registration endpoints
 - Create user session management
 - Add password hashing with bcrypt
-```
+
+# for bug fixes
+fix: correct formatting issue
+
+- Preserve empty lines in commit messages
+
+# for document changes
+docs: update README.md
 
 ```
 fix: prevent memory leak in connection pool
@@ -95,7 +157,7 @@ fix: prevent memory leak in connection pool
 - Improve error handling for failed connections
 ```
 
-With gitmoji:
+With gitmoji,(✨, 🐛, ♻️, etc. ✨ for feature, 🐛 for bug, ♻️ for refactor)
 ```
 ✨ add user authentication system
 
@@ -154,7 +216,7 @@ async def generate_commit_message(
 Context:
 - Working directory: {repo_path.absolute()}
 - Analysis scope: {"staged changes only (git diff --cached)" if staged_only else "all uncommitted changes (git diff)"}
-- You have access to: Bash, Read, Grep, and Glob tools
+- You have access to: Bash, Read, Grep, Glob, and Edit tools
 
 Your task:
 1. **FIRST**: Check the recent commit history (e.g., `git log -3 --oneline` or `git log -3 --pretty=format:"%s"`) to understand the commit message format/style used in this project
@@ -182,7 +244,12 @@ Recommendations (not requirements - use your judgment):
 - Start with `git log -3 --oneline` to check the commit message style
 - Then use `git status` and `git diff {"--cached" if staged_only else ""}` to see what changed
 - For non-trivial changes, READ the modified files to understand their purpose
-- Use grep to find related code or understand how functions are used
+- **USE GREP extensively** to understand impact and context:
+  * If a function was modified, grep for its usage: `grep -n "function_name("` 
+  * If a class was added/changed, find related classes: `grep -n "class.*Base"` or similar patterns
+  * If imports changed, see where they're used: `grep -n "imported_module"`
+  * To understand scope, count usages: `grep --output_mode count "pattern"`
+  * Get context around matches: `grep -C 3 "pattern"` (3 lines before/after)
 - Consider the broader context of the codebase
 
 When you're confident you understand the changes, output your commit message in this exact format:
@@ -196,7 +263,13 @@ Begin your analysis now.
     try:
         options = ClaudeAgentOptions(
             system_prompt=SYSTEM_PROMPT,
-            allowed_tools=["Bash", "Read", "Grep", "Glob"],
+            allowed_tools=[
+                "Bash",  # Run shell commands
+                "Read",  # Read file contents
+                "Grep",  # Search patterns in files (POWERFUL!)
+                "Glob",  # Find files by pattern
+                "Edit",  # Make precise edits to files (useful for analyzing multi-line changes)
+            ],
             permission_mode="acceptEdits",
             cwd=str(repo_path.absolute()),
             max_turns=10,
@@ -442,8 +515,8 @@ def handle_alias_command(args):
             print("📋 No aliases configured")
             return
 
-        import platform
         import os
+        import platform
 
         # Detect shell and platform
         shell = os.environ.get("SHELL", "")
@@ -609,8 +682,8 @@ def handle_alias_command(args):
 
     elif args[0] == "uninstall":
         # Remove shell aliases
-        import platform
         import os
+        import platform
 
         shell = os.environ.get("SHELL", "")
 

{claude_commit-0.1.1 → claude_commit-0.3.0/src/claude_commit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-commit
-Version: 0.1.1
+Version: 0.3.0
 Summary: AI-powered git commit message generator using Claude Agent SDK
 Author-email: Johannlai <johannli666@gmail.com>
 License: MIT
@@ -27,7 +27,7 @@ Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
-# claude-commit
+# claude-commit [![PyPI version](https://badge.fury.io/py/claude-commit.svg)](https://badge.fury.io/py/claude-commit)
 
 🤖 AI-powered git commit message generator using Claude Agent SDK and Claude Code CLI
 
@@ -35,23 +35,9 @@ Dynamic: license-file
 
 `claude-commit` uses Claude AI to analyze your code changes and write meaningful commit messages. Claude reads your files, understands the context, and generates commit messages following best practices.
 
-## Quick Start
+## Demo
 
-**Install:**
-```bash
-pip install claude-commit
-
-# Required dependency
-npm install -g @anthropic-ai/claude-code
-```
-
-**Use:**
-```bash
-git add .
-claude-commit --commit
-```
-
-That's it! Claude will analyze your changes and create a commit.
+[![asciicast](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L.svg)](https://asciinema.org/a/ZubvhPFyP7hPFLsqZiZUc930L?autoplay=1&speed=3)
 
 ## Installation
 
@@ -61,19 +47,44 @@ That's it! Claude will analyze your changes and create a commit.
 - Node.js
 - Git
 
-### Install Steps
+### Recommended: pipx (for CLI tools)
+
+`pipx` is the **best way to install Python CLI tools**. It creates isolated environments automatically:
 
 ```bash
-# 1. Install Claude Code CLI (required)
-npm install -g @anthropic-ai/claude-code
+# 1. Install pipx
+brew install pipx              # macOS
+# or
+pip install --user pipx        # Linux/Windows
+pipx ensurepath
 
-# 2. Install claude-commit
-pip install claude-commit
+# 2. Install Claude Code CLI (required)
+npm install -g @anthropic-ai/claude-code
 
-# Or use pipx for isolation
+# 3. Install claude-commit
 pipx install claude-commit
 ```
 
+### Alternative: pip
+
+If you prefer pip, use one of these methods:
+
+**Option 1: User installation (no admin rights needed)**
+```bash
+# Install to user directory
+pip install --user claude-commit
+
+# Make sure ~/.local/bin is in your PATH
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**Option 2: Virtual environment**
+```bash
+python3 -m venv ~/.venvs/claude-commit
+source ~/.venvs/claude-commit/bin/activate
+pip install claude-commit
+```
+
 ### Authentication
 
 `claude-commit` supports two ways to authenticate with Claude:
@@ -138,7 +149,7 @@ Create shortcuts for common commands:
 # Install to your shell config
 claude-commit alias install
 
-# Activate in current terminal
+# Activate in current terminal. Very important!
 source ~/.zshrc    # zsh
 source ~/.bashrc   # bash
 ```
@@ -238,28 +249,103 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
 ## Troubleshooting
 
-**Claude Code not found?**
+### Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+
+```
+Fatal error in message reader: Command failed with exit code 1 (exit code: 1)
+Error output: Check stderr output for details
+Traceback (most recent call last):
+```
+
+**Solution**: This error means you haven't authenticated with Claude. Choose one method:
+
+**Method A: Official Claude Code login (recommended)**
+```bash
+claude
+```
+
+**Method B: Set custom API endpoint**
+```bash
+export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"
+export ANTHROPIC_AUTH_TOKEN="your-auth-token"
+# model name (optional)
+export ANTHROPIC_MODEL="your-model-name"
+
+# Add to ~/.zshrc or ~/.bashrc to persist
+echo 'export ANTHROPIC_BASE_URL="https://your-endpoint.com/api/v1"' >> ~/.zshrc
+echo 'export ANTHROPIC_AUTH_TOKEN="your-auth-token"' >> ~/.zshrc
+```
+
+### "externally-managed-environment" error (macOS/Linux)
+
+If you see this error when using `pip install`:
+
+```
+error: externally-managed-environment
+```
+
+**Solution**: Use `pipx` (recommended for CLI tools):
+```bash
+brew install pipx
+pipx install claude-commit
+```
+
+Or use `pip install --user`:
+```bash
+pip install --user claude-commit
+```
+
+**Why this happens**: Modern Python installations (Python 3.11+) protect the system Python to prevent conflicts. This is not a bug in `claude-commit`.
+
+### Claude Code not found
+
 ```bash
 npm install -g @anthropic-ai/claude-code
 ```
 
-**No changes detected?**
+### No changes detected
+
 ```bash
 git add .              # stage changes
 # or
 claude-commit --all    # include unstaged
 ```
 
-**Analysis too slow?**
+### Analysis too slow
+
 ```bash
 claude-commit --max-diff-lines 200
 ```
 
+### Command not found after installation
+
+If `claude-commit` is not found after installation:
+
+**With pipx:**
+```bash
+pipx ensurepath
+# Restart your terminal
+```
+
+**With pip --user:**
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### Aliases not working
+
+```bash
+claude-commit alias install
+source ~/.zshrc  # or ~/.bashrc
+```
+
 ## Development
 
 ```bash
 # Clone and setup
-git clone https://github.com/yourusername/claude-commit.git
+git clone https://github.com/JohannLai/claude-commit.git
 cd claude-commit
 python -m venv venv
 source venv/bin/activate
@@ -285,7 +371,9 @@ MIT License - see [LICENSE](LICENSE) file
 
 - [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk)
 - [Conventional Commits](https://www.conventionalcommits.org/)
-- [Issue Tracker](https://github.com/yourusername/claude-commit/issues)
+- [GitHub Repository](https://github.com/JohannLai/claude-commit)
+- [PyPI Package](https://pypi.org/project/claude-commit/)
+- [Issue Tracker](https://github.com/JohannLai/claude-commit/issues)
 
 ---