A script to manage git worktrees for agent-based development. This tool simplifies creating, managing, and running processes within isolated worktrees, each with its own environment configuration.
- View Docs
- View Case Studies
- View AI Dev Log
Agro is simple, powerful, flexible and open-source.
- Simple: get started with a pip install and two commands.
- No signups, free trials or api keys needed.
- Works in your terminal with git, no new tools to learn.
- Powerful: compare the results of different coding agents.
- Run agents in parallel with built in support for environment reproduction and unique env vars.
- Flexible: works with multiple different cli agents, models, and IDE / editors.
- Works with all IDE's including: VSCode, Vim, Emacs, Cursor, and others.
- Open-source: avoid lock-in and subscriptions for your development environment.
- Agro is command line and always opensource. You can modify at will and share with others.
- Agro uses git under the hood so you can always substitue any or all parts of the recommended workflow with your own bash or git commands.
There is no magic, it's just shell calls to git, claude, aider, ps, etc.
- Since git's not going anywhere you'll always have support for your workflow, and
- Wrapping coder-agents allows drop-in addition or replacement as they become available.
So you can take agro to your nineteen side-projects and four remote jobs, and it will work everywhere.
Supported Agents: aider, claude code, gemini cli
- Shared context files
- Customizable agent behavior
Supported Models: Anthropic, OpenAI, Google, Grok4 and more
Agro-Builds-Agro: If you think vibe-coding can't stand-up to multiple iterations, this is your chance to think again. Agro is 150 commits and going strong (roughly 80% ai generated). See the Dev Log and Case Studies to see a record of all the prompts and their accepted solutions.
Install with pip or uv tool:
pip install agro
# or
uv tool install agroYou can install this tool and its dependencies from the local clone of the project directory using uv:
git clone [email protected]:sutt/agro.git"
cd agro
uv tool install . --no-cacheFor local dev updates run the ./redeploy script to reinstall the local repo as agro.
Also see the case studies for more advanced guidance on using this tool
0A. Clone the Demo Repo
git clone https://github.com/sutt/agro-demo
cd agro-demo
# setup environment and run server
uv sync
uv run python app/main.py
# hit ctrl+c to shutdown server, and let's start...0B. Copy the supplied docs
Copy the public git-tracked .public-agdocs directory to an internal git-ignored repo .agdocs
cp -r .public-agdocs .agdocsThe .agdocs directory is the default lookup for where agro will attempt to access configurations, guidance, and
This repo comes with tasks (.md files in /specs/ subdirectory). These should now be available if you copied it correctly in the step above.
.agdocs/
├── conf
│ └── agro.conf.yml
├── guides
│ └── GUIDE.md
├── specs
│ ├── add-about.md
│ ├── infer-model.md
│ └── query-web.md
└── swap
1. Launch four agents in parallel
$ agro exec add-about 2 # launch two agents of aider
$ agro exec add-about claude # if you have claude-code installed
$ agro exec add-about gemini # if you have gemini installedAgro is configured to use aider by default. Add the name of the coding agent you have installed as the argument to use the one you have installed, see docs for more info on this.
For the purposes of this tutorial, you don't need to launch all three different type of agents, simple use one or two that you have installed. If you don't have any installed, find instructions of how to install here.
These commands launched agents on a pre-written task in .agdocs/specs/add-about.md. (Ultimately you will write your own but let's start with a simple pre-written one.)
add-about.md
add an about page and route add a unique message of encouragment to the about page add a test run the test to make sure it passes before exiting
Basic Output
- notice the git worktree / branch management + launch of aider, claude and gemini
♻️ Cleanup for index 1 complete.
🏃 Agent for index 1 started successfully.
Worktree: /home/user/dev/agro/agro-demo/trees/t1
Task file: /home/user/dev/agro/agro-demo/.agdocs/specs/add-about.md
Branch: output/add-about.1
Agent type: aider
Initial commit SHA: 31ad99
Start time: 2025-07-18 09:12:20
♻️ Cleanup for index 2 complete.
🏃 Agent for index 2 started successfully.
Worktree: /home/user/dev/agro/agro-demo/trees/t2
Task file: /home/user/dev/agro/agro-demo/.agdocs/specs/add-about.md
Branch: output/add-about.2
Agent type: aider
Initial commit SHA: 31ad99
Start time: 2025-07-18 09:12:20
♻️ Cleanup for index 3 complete.
🏃 Agent for index 3 started successfully.
Worktree: /home/user/dev/agro/agro-demo/trees/t3
Task file: /home/user/dev/agro/agro-demo/.agdocs/specs/add-about.md
Branch: output/add-about.3
Agent type: claude
Initial commit SHA: 31ad99
Start time: 2025-07-18 09:13:13
♻️ Cleanup for index 4 complete.
🏃 Agent for index 4 started successfully.
Worktree: /home/user/dev/agro/agro-demo/trees/t4
Task file: /home/user/dev/agro/agro-demo/.agdocs/specs/add-about.md
Branch: output/add-about.4
Agent type: gemini
Initial commit SHA: 31ad99
Start time: 2025-07-18 09:13:27Now you should see multiple branches created, one for each agent:
$ git branch
* master
+ output/add-about.1
+ output/add-about.2
+ output/add-about.3
+ output/add-about.42. Launch Server on each worktree
agro muster -c server-start- The argument
-c/--common-cmdarg allows us to pass an alias for common commands we'll use. See docs on common commands for more info.
Output
agro muster -c server-start output
--- Running command in t1 (output/add-about.1) ---
$ uv run python app/main.py > server.log 2>&1 & echo $! > server.pid
--- Running command in t2 (output/add-about.2) ---
$ uv run python app/main.py > server.log 2>&1 & echo $! > server.pid
--- Running command in t3 (output/add-about.3) ---
$ uv run python app/main.py > server.log 2>&1 & echo $! > server.pid
--- Running command in t4 (output/add-about.4) ---
$ uv run python app/main.py > server.log 2>&1 & echo $! > server.pidCheck About Page Contents You could do this in browser as well
# check worktree t1 - aider agent (#1)
curl http://127.0.0.1:8001/about
# {"message":"Keep up the great work!"}
# check worktree t2 - aider agent (#2)
curl http://127.0.0.1:8002/about
# {"message":"You are doing great!"}
# check worktree t3 - claude agent
curl http://localhost:8003/about
# {"message":"🌱 Every great journey begins with a single step. You're already on your way to something amazing!","title":"About AgSwap","description":"Welcome to AgSwap - where agricultural innovation meets community collaboration."}
# check worktree t4 - gemini agent
curl http://localhost:8004/about
# {"message":"Keep up the great work, you're awesome!"}
Now clean up the server:
# run muster with server-kill (builtin common command) to take it down each worktree
$ agro muster -c server-kill
--- Running command in t1 (output/add-about.1) ---
$ kill $(cat server.pid) && rm -f server.pid server.log
--- Running command in t2 (output/add-about.2) ---
$ kill $(cat server.pid) && rm -f server.pid server.log
--- Running command in t3 (output/add-about.3) ---
$ kill $(cat server.pid) && rm -f server.pid server.log
--- Running command in t4 (output/add-about.4) ---
$ kill $(cat server.pid) && rm -f server.pid server.log
# checking agent1's worktree env, we see the server is no longer responding
$ curl http://localhost:8001
curl: (7) Failed to connect to localhost port 8001 after 0 ms: Connection refused3. Checking tests
We run our existing tests with:
$ uv run pytest -q
3 passed in 0.28sSo we see have 3 existing tests, now let's check the output of our agents:
$ agro muster -c testq output
--- Running command in t1 (output/add-about.1) ---
$ uv run pytest -q
4 passed in 0.25s
--- Running command in t2 (output/add-about.2) ---
$ uv run pytest -q
4 passed in 0.28s
--- Running command in t3 (output/add-about.3) ---
$ uv run pytest -q
4 passed in 0.25s
--- Running command in t4 (output/add-about.4) ---
$ uv run pytest -q
3 passed in 0.24sCool, so we see all Agents left the tests green, and Agents 1-3 added a new unit test (since they now have 4 tests and we started with 3 tests).
Check the code changes from each agent
TODO - add the agro diff command
TODO - add the branch-patterns example
For example:
Create and commit a spec file and pass to an agent
agro init # if you don't already have an `.agdocs` at root
# create a spec
agro task hello-world
# then add the text to the spec: "add hello world to the readme of this project"
# equivalent to:
echo "add hello world to the readme of this project" > .agdocs/specs/hello-world.md
agro exec
# when not supplying an argument for the task name,
# agro will chose the most recently modified .md file in specs/, so
# this is equivalent to:
agro exec hello-world 1 aiderTODO - add a full tutorial here
TODO
usage: agro [-v / -vv] <subcommand> [subcommand-args]
A script to manage git branches & worktrees for agent-based development.
Main command:
exec [args] [taskfile] [num-trees] [exec-cmd]
Run an agent in new worktree(s)
args:
-n <num-trees> Number of worktrees / agents to create.
-c <exec-cmd> Custom command to launch agent on worktree.
-a <agent-type> Specify agent type to override config.
Supported: aider, claude, gemini.
Other Commands:
muster [opts] [command] [branch-patterns] Run a command in specified worktrees.
diff [branch-patterns] [diff-opts] Show git diff for specified worktrees.
surrender [branch-patterns] Kill running agent processes (default: all).
grab <branch-name> Checkout a branch, creating a copy if it's in use.
fade <branch-patterns> Delete local branches matching a regex pattern.
clean [opts] [branch-patterns] Clean up worktrees and/or branches.
state [branch-patterns] Show the worktree to branch mappings (default: all).
task [task-name] Create a new task spec file and open it.
init Initialize agro project structure in .agdocs/.
mirror Mirror internal docs to public docs directory.
make <index> Create a new worktree.
delete <indices>|--all Delete one, multiple, or all worktrees.
Branch-patterns examples (for regex like matching):
output/add-thing Match output/add-thing*
output/add-thing.{2,5} Match output/add-thing.2, output/add-thing.5
output/add-thing.{1-4} Match output/add-thing.1, ... output/add-thing.4
Common options for 'make' and 'exec':
--fresh-env Use .env.example as the base instead of .env.
--no-env-overrides Do not add port overrides to the .env file.
Options for 'muster':
-c, --common-cmd <key> Run a pre-defined command from config.
Options for 'clean':
--soft Only delete worktrees, not branches.
--hard Delete both worktrees and branches (default).
Options for 'init':
--conf Only add a template agro.conf.yml to .agdocs/conf
The script will create two directories in the code repo:
.agdocs/- specs, configs, logs for agro (whenagro initrun)trees/- root for worktrees (whenagro execrun)- both of these are added to gitignore by default
- .agdocs/
- specs/
- task1
- task2
...
- swap/ <- gitignored
- shared logs
- conf/
- agro.conf.yml
- guides/
- GUIDE.md
- other-guide.md
- ...
- <your-code>
- <your-configs>
- trees/
- t1/
- <your-code>
- <t1-configs>
- t2/
- <your-code>
- <t1-configs>
...
agro will port .env files into the worktrees and override particular settings for parallel execution environments. And clone the env ironment (currently only supported for uv) from the main workspace into the
agro muster 'uv run which python' output/add-about.{1,2}
--- Running command in t1 (trees/t1) ---
$ uv run which python
/home/user/tools_dev/agscript/trees/t1/.venv/bin/python
--- Running command in t2 (trees/t2) ---
$ uv run which python
/home/user/tools_dev/agscript/trees/t2/.venv/bin/python
Or
agro muster 'cat .env' output/add-about.{1,2}
--- Running command in t1 (output/add-about.1) ---
$ cat .env
API_PORT=8000
### Worktree Overrides ---
API_PORT=8001
--- Running command in t2 (output/add-about.2) ---
$ cat .env
API_PORT=8000
### Worktree Overrides ---
API_PORT=8002
Three functionalities needed for the ai-generated workflow:
- Wrapper around CLI-Agents
- Agents operate in non-interactive mode (both YOLO and safe modes available)
- Markdown file based tasks
- You can track these with git and publish to github or keep them internal
- see this example Dev Log for agro.
- You can track these with git and publish to github or keep them internal
- A git branch + worktree workflow for reviewing generated code:
- Don't dread the process of reviewing reams of ai generated code, embrace it with some
What it doesn't do: agro is not an agent itself. Agro is a micro-framework to call other agents and simiplify workflow for dipatching, review, and comparison between different agents and models.
- python
- uv + virtualenv
- node
- npm
Check out the full docs here: Agro Docs