agent-tools
Worktree-based agent workflow management toolkit.
Overview
agent-tools provides a Python-based CLI for managing isolated Git worktrees for agent workflows. It replaces shell scripts with a maintainable, testable Python package that can be used locally, as a submodule, or in CI/CD pipelines.
Features
- Isolated Worktrees: Each agent gets its own isolated Git worktree
- Domain-based CLI:
ws,cfg,envdomains with clear action names - Backward Compatible: Legacy aliases supported (deprecated in v0.3, removed in v0.4)
- Manual PR Creation: Push branch and create PR manually in GitHub UI
- Cross-platform: Works on Windows, Linux, and macOS
- Installable: Can be installed via pip or used as submodule
Quick Start
Installation
# From source
cd agt
uv pip install -e . # or: pip install -e .
# Or as submodule
git submodule add -b main https://github.com/tnedr/agent-ops .tools
cd .tools/agt
uv pip install -e . # or: pip install -e .
Note: This project follows UV Cache Workflow Guidelines. If using uv, ensure UV_CACHE_DIR is set (e.g., E:\uv-cache on Windows).
Usage
New domain-based commands (v0.3+):
# Start a new agent worktree
agt ws new
# Run commands in the worktree
agt ws run python my_script.py
# Commit changes
agt ws save "feat: new feature"
# Push to remote (then open PR manually)
agt ws push
# Optional: cleanup after PR is merged
agt ws clean
Legacy aliases (deprecated, will be removed in v0.4):
agt start # → agt ws new
agt commit # → agt ws save
agt run # → agt ws run
agt push # → agt ws push
agt clean # → agt ws clean
See COMMANDS.md for complete command reference.
VS Code Integration
Generate VS Code Command Runner settings with agt commands:
agt vscode init # Creates/updates .vscode/settings.json
This adds the following commands to VS Code/Cursor:
agt start: Start a new agent worktreeagt run: Run a command in the agent worktree (with input prompt)agt commit: Commit changes (with input prompt for message)agt push: Push branch to remoteagt merge: Merge agent branch back to baseagt clean: Remove agent worktree
Usage in VS Code/Cursor:
- Press
F1→Command Runner: Run... - Select any
agt *command - Or use in chat:
> run command: agt start
Note: The agt vscode init command preserves existing commands in your .vscode/settings.json, so you can combine it with other Command Runner configurations.
Documentation
Examples
See the examples/ directory for:
demo_local.sh: Local workflow exampledemo_action.yml: GitHub Actions workflow example
Development
Setup
cd agt
uv pip install -e ".[dev]" # or: pip install -e ".[dev]"
Note: Uses UV Cache Workflow - minimal .venv, global cache.
Run Tests
uv run pytest tests/ -v # or: pytest tests/ -v
Run Linter
uv run ruff check . # or: ruff check .
Project Structure
agt/
├── __init__.py # Package metadata
├── __main__.py # Allows `python -m agt`
├── worktree.py # Low-level Git worktree operations
├── cli.py # CLI entrypoint and command handlers
└── pyproject.toml # Package configuration
bin/
└── agt # Standalone entrypoint script
docs/ # Documentation
tests/ # Test suite
examples/ # Usage examples
.github/ # CI/CD workflows and actions
License
MIT
Metadata
Release files for agent-tools-drnt 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_tools_drnt-0.4.3.tar.gz | 27.4 kB | Without provenance | Details for agent_tools_drnt-0.4.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_tools_drnt-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for agent_tools_drnt-0.4.3-py3-none-any.whl |
Total release size: 39.4 kB
Release files / agent_tools_drnt-0.4.3.tar.gz
| Download URL | agent_tools_drnt-0.4.3.tar.gz |
|---|---|
| Size | 27.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
61b7aa1a58362315217e160af6951e534ad17034aa10b951a17c8c2f9f92a841
|
|
BLAKE2b-256 checksum How to use checksums |
7056ba8581d48cd4dde4d9b5e043ed9239907fce120344eb4992f45d516ccb0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / agent_tools_drnt-0.4.3-py3-none-any.whl
| Download URL | agent_tools_drnt-0.4.3-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
287495757791154e471f67f8050910715df5b7698e46b8795025eb69daa87370
|
|
BLAKE2b-256 checksum How to use checksums |
ca939d3204f5339d86f5e61a0479f5b3aee971b35efa818b5f8f026e16b4df01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for agent-tools-drnt 0.4.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.