claudepath 0.1.0__tar.gz

claudepath-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.8", "3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v

claudepath-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing (no API token needed)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

claudepath-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build / distribution
+dist/
+build/
+*.egg-info/
+*.egg
+
+# PyPI credentials
+.pypirc
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# IDEs
+.idea/
+.vscode/
+*.iml
+
+# macOS
+.DS_Store

claudepath-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0] - 2026-02-25
+
+### Added
+- `claudepath mv` — move a project directory and update all Claude Code references
+- `claudepath remap` — update references only (directory already moved manually)
+- `claudepath list` — list all projects tracked by Claude Code
+- `claudepath help` — show usage and examples
+- `--dry-run` flag to preview changes without modifying files
+- `--no-backup` flag to skip automatic backup
+- `--yes` flag to skip confirmation prompt
+- `--claude-dir` flag to override the Claude data directory
+- Automatic backup to `~/.claude/backups/claudepath/{timestamp}/` before any changes
+- Automatic rollback on failure
+- Proper JSON parsing for `sessions-index.json` (fixes gap in existing community tools)
+- Recursive update of subagent `.jsonl` files
+- Line-by-line processing for large session files (>9MB)

claudepath-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Chullo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claudepath-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: claudepath
+Version: 0.1.0
+Summary: Move or rename Claude Code projects without losing session history and context
+Project-URL: Homepage, https://github.com/Mahiler1909/claudepath
+Project-URL: Repository, https://github.com/Mahiler1909/claudepath
+Project-URL: Issues, https://github.com/Mahiler1909/claudepath/issues
+Author: Fernando Chullo
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,cli,move,project
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# claudepath
+
+Move or rename [Claude Code](https://claude.ai/claude-code) projects without losing session history, memory, and context.
+
+## The Problem
+
+When you move or rename a project directory, Claude Code loses all your session history because sessions are keyed to the absolute path of your project. You end up with orphaned data in `~/.claude/projects/` and a fresh start.
+
+**claudepath** fixes this by updating all path references in Claude Code's data files after a move.
+
+## Installation
+
+```bash
+# With pipx (recommended — isolated install)
+pipx install claudepath
+
+# With pip
+pip install claudepath
+```
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap Mahiler1909/tools
+brew install claudepath
+```
+
+## Usage
+
+### Move a project
+
+Moves the directory on disk **and** updates all Claude Code references:
+
+```bash
+claudepath mv ~/old/location/my-project ~/new/location/my-project
+```
+
+### Remap after a manual move
+
+If you already moved the directory yourself, just update Claude's references:
+
+```bash
+claudepath remap ~/old/location/my-project ~/new/location/my-project
+```
+
+### Preview changes (dry run)
+
+See exactly what would change without modifying anything:
+
+```bash
+claudepath mv ~/old/path ~/new/path --dry-run
+```
+
+### List tracked projects
+
+```bash
+claudepath list
+```
+
+### Full help
+
+```bash
+claudepath help
+claudepath mv --help
+```
+
+## What it updates
+
+| File / Directory | What changes |
+|---|---|
+| `~/.claude/projects/{encoded-dir}/` | Renamed to match new path |
+| `sessions-index.json` | `originalPath`, `projectPath`, `fullPath` updated (proper JSON parsing) |
+| `{session}.jsonl` files | `cwd` and file path references updated (line-by-line, handles large files) |
+| Subagent `.jsonl` files | Same as above, recursive |
+| `~/.claude/history.jsonl` | `project` field updated for all matching entries |
+
+> **Note:** `file-history/`, `todos/`, `tasks/`, and `shell-snapshots/` are keyed by session UUID, not by project path — they don't need updating.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Preview all changes without writing anything |
+| `--no-backup` | Skip creating a backup before modifying files |
+| `--yes` / `-y` | Skip the confirmation prompt |
+| `--claude-dir <path>` | Override the Claude data directory (default: `~/.claude`) |
+
+## Backup & Rollback
+
+By default, claudepath creates a backup before making any changes:
+
+```
+~/.claude/backups/claudepath/{timestamp}/
+```
+
+The backup includes:
+- The full project data directory (`~/.claude/projects/{encoded}/`)
+- `~/.claude/history.jsonl`
+
+If any step fails, claudepath automatically restores from the backup. Use `--no-backup` only if you already have your own backup or want to skip the extra time.
+
+## How Claude Code encodes paths
+
+Claude Code stores project data in `~/.claude/projects/` using an encoded directory name: every `/` in the absolute path is replaced with `-`.
+
+```
+/Users/foo/my-project  →  -Users-foo-my-project
+```
+
+This means moving `/Users/foo/old-name` to `/Users/foo/new-name` requires:
+1. Renaming `-Users-foo-old-name` to `-Users-foo-new-name`
+2. Updating all path strings inside the data files
+
+## License
+
+MIT

claudepath-0.1.0/README.md

@@ -0,0 +1,116 @@
+# claudepath
+
+Move or rename [Claude Code](https://claude.ai/claude-code) projects without losing session history, memory, and context.
+
+## The Problem
+
+When you move or rename a project directory, Claude Code loses all your session history because sessions are keyed to the absolute path of your project. You end up with orphaned data in `~/.claude/projects/` and a fresh start.
+
+**claudepath** fixes this by updating all path references in Claude Code's data files after a move.
+
+## Installation
+
+```bash
+# With pipx (recommended — isolated install)
+pipx install claudepath
+
+# With pip
+pip install claudepath
+```
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap Mahiler1909/tools
+brew install claudepath
+```
+
+## Usage
+
+### Move a project
+
+Moves the directory on disk **and** updates all Claude Code references:
+
+```bash
+claudepath mv ~/old/location/my-project ~/new/location/my-project
+```
+
+### Remap after a manual move
+
+If you already moved the directory yourself, just update Claude's references:
+
+```bash
+claudepath remap ~/old/location/my-project ~/new/location/my-project
+```
+
+### Preview changes (dry run)
+
+See exactly what would change without modifying anything:
+
+```bash
+claudepath mv ~/old/path ~/new/path --dry-run
+```
+
+### List tracked projects
+
+```bash
+claudepath list
+```
+
+### Full help
+
+```bash
+claudepath help
+claudepath mv --help
+```
+
+## What it updates
+
+| File / Directory | What changes |
+|---|---|
+| `~/.claude/projects/{encoded-dir}/` | Renamed to match new path |
+| `sessions-index.json` | `originalPath`, `projectPath`, `fullPath` updated (proper JSON parsing) |
+| `{session}.jsonl` files | `cwd` and file path references updated (line-by-line, handles large files) |
+| Subagent `.jsonl` files | Same as above, recursive |
+| `~/.claude/history.jsonl` | `project` field updated for all matching entries |
+
+> **Note:** `file-history/`, `todos/`, `tasks/`, and `shell-snapshots/` are keyed by session UUID, not by project path — they don't need updating.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Preview all changes without writing anything |
+| `--no-backup` | Skip creating a backup before modifying files |
+| `--yes` / `-y` | Skip the confirmation prompt |
+| `--claude-dir <path>` | Override the Claude data directory (default: `~/.claude`) |
+
+## Backup & Rollback
+
+By default, claudepath creates a backup before making any changes:
+
+```
+~/.claude/backups/claudepath/{timestamp}/
+```
+
+The backup includes:
+- The full project data directory (`~/.claude/projects/{encoded}/`)
+- `~/.claude/history.jsonl`
+
+If any step fails, claudepath automatically restores from the backup. Use `--no-backup` only if you already have your own backup or want to skip the extra time.
+
+## How Claude Code encodes paths
+
+Claude Code stores project data in `~/.claude/projects/` using an encoded directory name: every `/` in the absolute path is replaced with `-`.
+
+```
+/Users/foo/my-project  →  -Users-foo-my-project
+```
+
+This means moving `/Users/foo/old-name` to `/Users/foo/new-name` requires:
+1. Renaming `-Users-foo-old-name` to `-Users-foo-new-name`
+2. Updating all path strings inside the data files
+
+## License
+
+MIT

claudepath-0.1.0/homebrew/claudepath.rb

@@ -0,0 +1,20 @@
+class Claudepath < Formula
+  include Language::Python::Virtualenv
+
+  desc "Move Claude Code projects without losing session history and context"
+  homepage "https://github.com/Mahiler1909/claudepath"
+  url "https://files.pythonhosted.org/packages/source/c/claudepath/claudepath-0.1.0.tar.gz"
+  # sha256 will be filled in after PyPI publish
+  sha256 "FILL_IN_AFTER_PYPI_PUBLISH"
+  license "MIT"
+
+  depends_on "python@3.11"
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  test do
+    system "#{bin}/claudepath", "help"
+  end
+end

claudepath-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claudepath"
+version = "0.1.0"
+description = "Move or rename Claude Code projects without losing session history and context"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "Fernando Chullo" }
+]
+keywords = ["claude", "claude-code", "anthropic", "cli", "project", "move"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+claudepath = "claudepath.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Mahiler1909/claudepath"
+Repository = "https://github.com/Mahiler1909/claudepath"
+Issues = "https://github.com/Mahiler1909/claudepath/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claudepath"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

claudepath-0.1.0/src/claudepath/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

claudepath-0.1.0/src/claudepath/__main__.py

@@ -0,0 +1,4 @@
+from claudepath.cli import main
+
+if __name__ == "__main__":
+    main()

claudepath-0.1.0/src/claudepath/backup.py

@@ -0,0 +1,110 @@
+"""
+Backup and rollback utilities for claudepath.
+
+Before modifying any Claude Code data files, a backup is created.
+If any step fails, the backup can be restored automatically.
+
+Backups are stored in: ~/.claude/backups/claudepath/{timestamp}/
+"""
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def create_backup(
+    project_dir: Path,
+    history_path: Path,
+    backup_base: Path,
+) -> Path:
+    """Create a backup of the project directory and history.jsonl.
+
+    Args:
+        project_dir: The ~/.claude/projects/{encoded}/ directory to back up.
+        history_path: The ~/.claude/history.jsonl file to back up.
+        backup_base: Base directory for backups (~/.claude/backups/claudepath/).
+
+    Returns:
+        Path to the created backup directory.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_dir = backup_base / timestamp
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    # Back up the project directory
+    if project_dir.exists():
+        dest = backup_dir / "project_dir"
+        shutil.copytree(str(project_dir), str(dest))
+
+    # Back up history.jsonl
+    if history_path.exists():
+        shutil.copy2(str(history_path), str(backup_dir / "history.jsonl"))
+
+    # Write a manifest so restore knows what to put back where
+    manifest = backup_dir / "manifest.txt"
+    manifest.write_text(
+        f"project_dir={project_dir}\nhistory_path={history_path}\n",
+        encoding="utf-8",
+    )
+
+    return backup_dir
+
+
+def restore_backup(backup_dir: Path) -> bool:
+    """Restore files from a backup directory created by create_backup().
+
+    Reads the manifest to know where to restore each item.
+    Returns True on success, False if anything went wrong.
+    """
+    manifest = backup_dir / "manifest.txt"
+    if not manifest.exists():
+        return False
+
+    config = {}
+    for line in manifest.read_text(encoding="utf-8").splitlines():
+        if "=" in line:
+            k, v = line.split("=", 1)
+            config[k.strip()] = v.strip()
+
+    project_dir = Path(config.get("project_dir", ""))
+    history_path = Path(config.get("history_path", ""))
+
+    success = True
+
+    # Restore project directory
+    backup_project = backup_dir / "project_dir"
+    if backup_project.exists() and project_dir:
+        if project_dir.exists():
+            shutil.rmtree(project_dir)
+        try:
+            shutil.copytree(str(backup_project), str(project_dir))
+        except OSError:
+            success = False
+
+    # Restore history.jsonl
+    backup_history = backup_dir / "history.jsonl"
+    if backup_history.exists() and history_path:
+        try:
+            shutil.copy2(str(backup_history), str(history_path))
+        except OSError:
+            success = False
+
+    return success
+
+
+def get_backup_base(claude_dir: Path) -> Path:
+    """Return the base directory for claudepath backups."""
+    return claude_dir / "backups" / "claudepath"
+
+
+def find_latest_backup(backup_base: Path) -> Optional[Path]:
+    """Return the most recently created backup directory, or None."""
+    if not backup_base.exists():
+        return None
+    backups = sorted(
+        [d for d in backup_base.iterdir() if d.is_dir()],
+        key=lambda d: d.name,
+        reverse=True,
+    )
+    return backups[0] if backups else None