Metadata-Version: 2.4
Name: taskpods
Version: 0.1.0
Summary: Parallel AI task pods via git worktrees
Author-email: Yanai Ron <yanai.ron@gmail.com>
Maintainer-email: Yanai Ron <yanai.ron@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yanairon/taskpods
Project-URL: Documentation, https://github.com/yanairon/taskpods#readme
Project-URL: Repository, https://github.com/yanairon/taskpods.git
Project-URL: Issues, https://github.com/yanairon/taskpods/issues
Project-URL: Changelog, https://github.com/yanairon/taskpods/blob/main/CHANGELOG.md
Keywords: git,worktree,ai,development,workflow,parallel
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# taskpods: Parallel AI Task Pods via Git Worktrees

`taskpods` is a tiny command‑line tool that lets you spawn disposable "AI pods" in your Git repository.  Each pod is its own worktree and branch, so you can run Copilot, Cursor, or Claude Code on isolated tasks without polluting your main branch.  When you're done, you can commit and push the work to a pull request or nuke the pod entirely.

## Features

- **Instant sandbox:** `taskpods start <name>` creates a new worktree under `.taskpods/<name>` and checks out a branch `pods/<name>` from a base branch (default `main`).
- **Clean exit:** `taskpods done <name>` stages, commits, and pushes everything in the pod, optionally opening a GitHub pull request via [`gh` CLI], then removes the worktree.
- **Abort button:** `taskpods abort <name>` deletes an unpushed pod and its branch without a trace.
- **Status overview:** `taskpods list` shows your active pods and where they live in the file system.
- **House‑keeping:** `taskpods prune` removes pods whose branches have been merged into their base branch.

## Installation

### Quick Install (Recommended)

Install directly from the repository:

```bash
pip install git+https://github.com/yanairon/taskpods.git
```

### Alternative Installation Methods

**From PyPI** (when available):
```bash
pip install taskpods
```

**Manual installation**:
```bash
# Download and install manually
curl -O https://raw.githubusercontent.com/yanairon/taskpods/main/taskpods.py
chmod +x taskpods.py
sudo mv taskpods.py /usr/local/bin/taskpods
```

**Requirements**:
- Python 3.9+
- Git 2.5+ with worktree support
- A Git repository with a remote named `origin`

## Usage

### Create a new pod

```bash
taskpods start fix‑typos
```

This will:

1. Fetch the latest changes from `main` and fast‑forward your local `main`.
2. Create a new branch `pods/fix‑typos` from `main`.
3. Add a Git worktree at `.taskpods/fix‑typos`.
4. Drop you into a new editor window (Cursor if available, otherwise VS Code) with the worktree opened.

### Finish a pod and create a pull request

```bash
taskpods done fix‑typos -m "Fix docs typos" --remove
```

This will stage and commit all changes in the worktree with the given message, push the branch to `origin`, open a pull request via the [`gh` CLI] (if installed), and remove the worktree.  The branch remains so you can still interact with the PR.

### Abort a pod

```bash
taskpods abort fix‑typos
```

If the branch hasn't been pushed to `origin`, this will delete the worktree and local branch.  It refuses to abort pods whose branches are already on `origin` to avoid data loss.

### List active pods

```bash
taskpods list
```

Lists all worktrees under `.taskpods`, showing the pod name, branch, and path.

### Prune merged pods

```bash
taskpods prune
```

Finds pods whose remote branches are fully merged into their base branch and removes their worktrees.

## Requirements

- **Python 3.9+** – This script uses only the standard library.
- **Git** – You need Git installed with worktree support (Git 2.5+).  The repository must already be initialised with a remote named `origin`.
- **Editor (optional)** – The script will try to open your editor.  It prefers `cursor` (Cursor's CLI), then `code` (VS Code).  If neither is found, it won't open anything.
- **`gh` CLI (optional)** – If installed, `taskpods done` will automatically open a GitHub pull request.  Otherwise, it simply pushes the branch and prints a success message.

## Support

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/X8X51K73WN)

## License

This project is released under the MIT License.  See the [LICENSE](LICENSE) file for details.

---

### Why worktrees?

Git worktrees let you have multiple branches checked out in separate directories without duplicating your entire `.git` object store.  They're faster than clones, don't waste disk space, and make cleanup trivial.  `taskpods` wraps a handful of `git worktree` commands with sensible defaults and adds quality‑of‑life features like automatic PR creation and safe aborts.

### DISCLAIMER

This tool is provided "as is" with no warranty.  It writes to your Git repository and could potentially cause data loss if used incorrectly.  Read the code, use it at your own risk, and always back up anything important before experimenting.

---

## Development

*For contributors and developers:*

### Setting up the development environment

```bash
git clone https://github.com/yanairon/taskpods.git
cd taskpods
pip install -e ".[dev]"
pre-commit install
```

### Running tests

```bash
# Run all tests
make test

# Run tests with coverage
make test-cov

# Run all quality checks
make check
```

### Code quality

The project uses several tools to maintain code quality:

- **Black** - Code formatting
- **Flake8** - Linting
- **MyPy** - Type checking
- **Pre-commit** - Automated quality checks

Run `make format` to format code and `make lint` to check for issues.

## Contributing

Contributions, bug reports, and feature requests are welcome!  Feel free to open an issue or submit a pull request.
