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, env domains 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 worktree
• agt 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 remote
• agt merge: Merge agent branch back to base
• agt 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

• Quick Start Guide
• CLI Reference
• Architecture
• Changelog

Examples

See the examples/ directory for:

• demo_local.sh: Local workflow example
• demo_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