# taskpods: Parallel AI Task Pods via Git Worktrees
[](https://github.com/yanairon/taskpods/actions)
[](https://codecov.io/gh/yanairon/taskpods)
[](https://pypi.org/project/taskpods/)
[](https://pypi.org/project/taskpods/)
[](https://github.com/yanairon/taskpods/blob/main/LICENSE)
[](https://github.com/psf/black)
`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 from PyPI:
```bash
pip install taskpods
```
### Alternative Installation Methods
**From GitHub** (latest development version):
```bash
pip install git+https://github.com/yanairon/taskpods.git
```
**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 preferred editor. You can configure it via:
- Environment variable: `export TASKPODS_EDITOR="vim"`
- Configuration file: `~/.taskpodsrc`
- Command line: `taskpods start my-feature --editor vim`
- Auto-detection: Falls back to common editors if none configured
- **`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.
## Editor Configuration
### Environment Variable
```bash
export TASKPODS_EDITOR="vim"
export TASKPODS_EDITOR="code"
export TASKPODS_EDITOR="cursor"
```
### Configuration File
Create `~/.taskpodsrc`:
```json
{
"editor": "vim",
"default_base": "main"
}
```
### Command Line
```bash
taskpods start my-feature --editor vim
taskpods start my-feature --editor code
taskpods start my-feature --editor cursor
```
### Supported Editors
- **Modern**: Cursor, VS Code, Sublime Text, Atom
- **Terminal**: Vim, Neovim, Emacs
- **Custom**: Any editor available in your PATH
## Support
[](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.
Raw data
{
"_id": null,
"home_page": null,
"name": "taskpods",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Yanai Ron <yanai.ron@gmail.com>",
"keywords": "git, worktree, ai, development, workflow, parallel",
"author": null,
"author_email": "Yanai Ron <yanai.ron@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/1e/51174b870dc1040486583ca67b6259860755690ce72777ab77d640ea0fc4/taskpods-0.3.0.tar.gz",
"platform": null,
"description": "# taskpods: Parallel AI Task Pods via Git Worktrees\n\n[](https://github.com/yanairon/taskpods/actions)\n[](https://codecov.io/gh/yanairon/taskpods)\n[](https://pypi.org/project/taskpods/)\n[](https://pypi.org/project/taskpods/)\n[](https://github.com/yanairon/taskpods/blob/main/LICENSE)\n[](https://github.com/psf/black)\n\n`taskpods` is a tiny command\u2011line 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.\n\n## Features\n\n- **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`).\n- **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.\n- **Abort button:** `taskpods abort <name>` deletes an unpushed pod and its branch without a trace.\n- **Status overview:** `taskpods list` shows your active pods and where they live in the file system.\n- **House\u2011keeping:** `taskpods prune` removes pods whose branches have been merged into their base branch.\n\n## Installation\n\n### Quick Install (Recommended)\n\nInstall from PyPI:\n\n```bash\npip install taskpods\n```\n\n### Alternative Installation Methods\n\n**From GitHub** (latest development version):\n\n```bash\npip install git+https://github.com/yanairon/taskpods.git\n```\n\n**Manual installation**:\n\n```bash\n# Download and install manually\ncurl -O https://raw.githubusercontent.com/yanairon/taskpods/main/taskpods.py\nchmod +x taskpods.py\nsudo mv taskpods.py /usr/local/bin/taskpods\n```\n\n**Requirements**:\n\n- Python 3.9+\n- Git 2.5+ with worktree support\n- A Git repository with a remote named `origin`\n\n## Usage\n\n### Create a new pod\n\n```bash\ntaskpods start fix\u2011typos\n```\n\nThis will:\n\n1. Fetch the latest changes from `main` and fast\u2011forward your local `main`.\n2. Create a new branch `pods/fix\u2011typos` from `main`.\n3. Add a Git worktree at `.taskpods/fix\u2011typos`.\n4. Drop you into a new editor window (Cursor if available, otherwise VS Code) with the worktree opened.\n\n### Finish a pod and create a pull request\n\n```bash\ntaskpods done fix\u2011typos -m \"Fix docs typos\" --remove\n```\n\nThis 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.\n\n### Abort a pod\n\n```bash\ntaskpods abort fix\u2011typos\n```\n\nIf 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.\n\n### List active pods\n\n```bash\ntaskpods list\n```\n\nLists all worktrees under `.taskpods`, showing the pod name, branch, and path.\n\n### Prune merged pods\n\n```bash\ntaskpods prune\n```\n\nFinds pods whose remote branches are fully merged into their base branch and removes their worktrees.\n\n## Requirements\n\n- **Python 3.9+** \u2013 This script uses only the standard library.\n- **Git** \u2013 You need Git installed with worktree support (Git 2.5+). The repository must already be initialised with a remote named `origin`.\n- **Editor (optional)** \u2013 The script will try to open your preferred editor. You can configure it via:\n - Environment variable: `export TASKPODS_EDITOR=\"vim\"`\n - Configuration file: `~/.taskpodsrc`\n - Command line: `taskpods start my-feature --editor vim`\n - Auto-detection: Falls back to common editors if none configured\n- **`gh` CLI (optional)** \u2013 If installed, `taskpods done` will automatically open a GitHub pull request. Otherwise, it simply pushes the branch and prints a success message.\n\n## Editor Configuration\n\n### Environment Variable\n```bash\nexport TASKPODS_EDITOR=\"vim\"\nexport TASKPODS_EDITOR=\"code\"\nexport TASKPODS_EDITOR=\"cursor\"\n```\n\n### Configuration File\nCreate `~/.taskpodsrc`:\n```json\n{\n \"editor\": \"vim\",\n \"default_base\": \"main\"\n}\n```\n\n### Command Line\n```bash\ntaskpods start my-feature --editor vim\ntaskpods start my-feature --editor code\ntaskpods start my-feature --editor cursor\n```\n\n### Supported Editors\n- **Modern**: Cursor, VS Code, Sublime Text, Atom\n- **Terminal**: Vim, Neovim, Emacs\n- **Custom**: Any editor available in your PATH\n\n## Support\n\n[](https://ko-fi.com/X8X51K73WN)\n\n## License\n\nThis project is released under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n### Why worktrees?\n\nGit 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\u2011of\u2011life features like automatic PR creation and safe aborts.\n\n### DISCLAIMER\n\nThis 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.\n\n---\n\n## Development\n\n*For contributors and developers:*\n\n### Setting up the development environment\n\n```bash\ngit clone https://github.com/yanairon/taskpods.git\ncd taskpods\npip install -e \".[dev]\"\npre-commit install\n```\n\n### Running tests\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Run all quality checks\nmake check\n```\n\n### Code quality\n\nThe project uses several tools to maintain code quality:\n\n- **Black** - Code formatting\n- **Flake8** - Linting\n- **MyPy** - Type checking\n- **Pre-commit** - Automated quality checks\n\nRun `make format` to format code and `make lint` to check for issues.\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Parallel AI task pods via git worktrees",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/yanairon/taskpods/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/yanairon/taskpods#readme",
"Homepage": "https://github.com/yanairon/taskpods",
"Issues": "https://github.com/yanairon/taskpods/issues",
"Repository": "https://github.com/yanairon/taskpods.git"
},
"split_keywords": [
"git",
" worktree",
" ai",
" development",
" workflow",
" parallel"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d991d5b429547aced1727b5456a3417d8ef34ef558ee2d44ef65b03e57cc118",
"md5": "68a765c1c3156c3fdabbbcd2af007eb1",
"sha256": "d119ffe2196c141fa06644e2e5eaebf4671193fdb8e3f001a5771e77946d64dd"
},
"downloads": -1,
"filename": "taskpods-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68a765c1c3156c3fdabbbcd2af007eb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11591,
"upload_time": "2025-08-24T20:08:58",
"upload_time_iso_8601": "2025-08-24T20:08:58.728568Z",
"url": "https://files.pythonhosted.org/packages/6d/99/1d5b429547aced1727b5456a3417d8ef34ef558ee2d44ef65b03e57cc118/taskpods-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a21e51174b870dc1040486583ca67b6259860755690ce72777ab77d640ea0fc4",
"md5": "87028822b681f1d423385177908685f1",
"sha256": "736a51ee45a1e0c432ae983b3a9329380dd063ed4587aca6dc373e83c79183b4"
},
"downloads": -1,
"filename": "taskpods-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "87028822b681f1d423385177908685f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13548,
"upload_time": "2025-08-24T20:08:59",
"upload_time_iso_8601": "2025-08-24T20:08:59.774652Z",
"url": "https://files.pythonhosted.org/packages/a2/1e/51174b870dc1040486583ca67b6259860755690ce72777ab77d640ea0fc4/taskpods-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 20:08:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yanairon",
"github_project": "taskpods",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "taskpods"
}
JSON
