agent-worktree-manager 0.2.0__tar.gz

agent_worktree_manager-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jan Wyzula
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

agent_worktree_manager-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include docs *.md
+recursive-include examples *.toml
+recursive-include tests *.py

agent_worktree_manager-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: agent-worktree-manager
+Version: 0.2.0
+Summary: Manage isolated Python environments and Git worktrees across projects
+Author: Jan Wyzula
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: packaging>=23
+Requires-Dist: platformdirs>=3
+Requires-Dist: pip>=23.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Provides-Extra: release
+Requires-Dist: python-semantic-release==10.6.2; extra == "release"
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Dynamic: license-file
+
+# Agent Worktree Manager
+
+Working on several branches or with coding agents means keeping track of both
+source checkouts and their Python environments. `awm` pairs Git worktrees with
+isolated environments and provides a terminal UI to browse and clean them up
+across projects.
+
+Start with an environment that already works. AWM reproduces its installed
+dependencies and points selected editable packages at new worktrees. Other
+editable packages keep their original source links. Install AWM once, separately
+from your project environments.
+
+Supports Python 3.11–3.14 on macOS and Linux; Git is required. Standard venv/pip
+is the default; uv and conda backends are optional. AWM and your project
+environments can use different Python versions.
+
+## Installation
+
+From PyPI, once the first release is published, choose either:
+
+```sh
+uv tool install agent-worktree-manager
+# Or install into your chosen Python environment:
+python -m pip install agent-worktree-manager
+```
+
+To install from a source checkout now, run at this repository's root:
+
+```sh
+uv tool install --editable .
+# Or:
+python -m pip install -e .
+```
+
+To activate a sandbox in your current terminal from the TUI, enable shell integration:
+
+```sh
+eval "$(awm shell-init zsh)"  # use bash for Bash
+```
+
+Add the same line to `~/.zshrc` (or `~/.bashrc`) to enable it in new terminals.
+Then press `s` on a sandbox to close AWM and activate its environment.
+
+## Register your first project
+
+From your project's Git checkout, register its existing Python environment:
+
+```sh
+awm init --name my-project --base /absolute/path/to/base-env --repo app=.
+awm doctor
+awm create my-task --repo app
+awm run my-task -- python --version
+awm
+```
+
+`--base` is the environment directory, not its Python executable. Use
+`--backend uv` for a uv base or `--backend conda` for a conda base. Repeat
+`--repo ALIAS=PATH` to include more repositories. Registration writes `awm.toml`
+and machine-specific settings in git-ignored `.awm/`, and adds the project to
+your global overview. From elsewhere, select it with `awm --project my-project`.
+
+## Use with coding agents
+
+The bundled `awm` skill guides agents through creating, resuming, inspecting,
+and cleaning up worktrees with their environments. Install it for either agent:
+
+```sh
+# Codex
+awm skill --install "$HOME/.agents/skills/awm"
+# Claude Code
+awm skill --install "$HOME/.claude/skills/awm"
+```
+
+In Codex, select it through `/skills` or mention `$awm`. In Claude Code, use
+`/awm`. For example: “create a sandbox for fixing the login tests and work there.”
+See the [agent guide](docs/agents.md) for custom locations and updating a skill.
+
+## Contributing
+
+Please follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+for commit messages, for example `feat(tui): add sandbox shell shortcut` or
+`fix(env): preserve editable paths`. These messages drive automated versioning
+and release notes.
+
+## License
+
+[BSD 3-Clause](LICENSE) — Copyright (c) 2026, Jan Wyzula.
+
+## Documentation
+
+[Usage](docs/usage.md) · [Configuration](docs/configuration.md) ·
+[AI agent skill](docs/agents.md)

agent_worktree_manager-0.2.0/README.md

@@ -0,0 +1,92 @@
+# Agent Worktree Manager
+
+Working on several branches or with coding agents means keeping track of both
+source checkouts and their Python environments. `awm` pairs Git worktrees with
+isolated environments and provides a terminal UI to browse and clean them up
+across projects.
+
+Start with an environment that already works. AWM reproduces its installed
+dependencies and points selected editable packages at new worktrees. Other
+editable packages keep their original source links. Install AWM once, separately
+from your project environments.
+
+Supports Python 3.11–3.14 on macOS and Linux; Git is required. Standard venv/pip
+is the default; uv and conda backends are optional. AWM and your project
+environments can use different Python versions.
+
+## Installation
+
+From PyPI, once the first release is published, choose either:
+
+```sh
+uv tool install agent-worktree-manager
+# Or install into your chosen Python environment:
+python -m pip install agent-worktree-manager
+```
+
+To install from a source checkout now, run at this repository's root:
+
+```sh
+uv tool install --editable .
+# Or:
+python -m pip install -e .
+```
+
+To activate a sandbox in your current terminal from the TUI, enable shell integration:
+
+```sh
+eval "$(awm shell-init zsh)"  # use bash for Bash
+```
+
+Add the same line to `~/.zshrc` (or `~/.bashrc`) to enable it in new terminals.
+Then press `s` on a sandbox to close AWM and activate its environment.
+
+## Register your first project
+
+From your project's Git checkout, register its existing Python environment:
+
+```sh
+awm init --name my-project --base /absolute/path/to/base-env --repo app=.
+awm doctor
+awm create my-task --repo app
+awm run my-task -- python --version
+awm
+```
+
+`--base` is the environment directory, not its Python executable. Use
+`--backend uv` for a uv base or `--backend conda` for a conda base. Repeat
+`--repo ALIAS=PATH` to include more repositories. Registration writes `awm.toml`
+and machine-specific settings in git-ignored `.awm/`, and adds the project to
+your global overview. From elsewhere, select it with `awm --project my-project`.
+
+## Use with coding agents
+
+The bundled `awm` skill guides agents through creating, resuming, inspecting,
+and cleaning up worktrees with their environments. Install it for either agent:
+
+```sh
+# Codex
+awm skill --install "$HOME/.agents/skills/awm"
+# Claude Code
+awm skill --install "$HOME/.claude/skills/awm"
+```
+
+In Codex, select it through `/skills` or mention `$awm`. In Claude Code, use
+`/awm`. For example: “create a sandbox for fixing the login tests and work there.”
+See the [agent guide](docs/agents.md) for custom locations and updating a skill.
+
+## Contributing
+
+Please follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+for commit messages, for example `feat(tui): add sandbox shell shortcut` or
+`fix(env): preserve editable paths`. These messages drive automated versioning
+and release notes.
+
+## License
+
+[BSD 3-Clause](LICENSE) — Copyright (c) 2026, Jan Wyzula.
+
+## Documentation
+
+[Usage](docs/usage.md) · [Configuration](docs/configuration.md) ·
+[AI agent skill](docs/agents.md)

agent_worktree_manager-0.2.0/agent_worktree_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Portable, project-owned worktree environments."""
+
+__version__ = "0.2.0"

agent_worktree_manager-0.2.0/agent_worktree_manager/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agent_worktree_manager.cli import main
+
+sys.exit(main())

agent_worktree_manager-0.2.0/agent_worktree_manager/agent_skill.py

@@ -0,0 +1,49 @@
+"""Export the bundled, agent-independent worktree skill."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+
+from .errors import AWMError
+
+SKILL_FILES = ("SKILL.md", "agents/openai.yaml")
+
+
+def bundled_files() -> dict[str, bytes]:
+    root = files("agent_worktree_manager").joinpath("skills", "awm")
+    return {name: root.joinpath(*name.split("/")).read_bytes() for name in SKILL_FILES}
+
+
+def install_skill(destination: Path) -> Path:
+    destination = Path(os.path.abspath(destination.expanduser()))
+    content = bundled_files()
+    if destination.is_symlink():
+        raise AWMError(f"Skill destination must not be a symlink: {destination}")
+    if destination.exists():
+        if destination.is_dir() and all(
+            (destination / name).is_file()
+            and not (destination / name).is_symlink()
+            and (destination / name).read_bytes() == value
+            for name, value in content.items()
+        ):
+            return destination
+        raise AWMError(
+            f"Skill destination already exists with different contents: {destination}; "
+            "review or move the existing skill before installing"
+        )
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = Path(tempfile.mkdtemp(prefix=".awm-skill-", dir=destination.parent))
+    try:
+        for name, value in content.items():
+            path = temporary / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(value)
+        temporary.rename(destination)
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+    return destination