agent-zsh

zsh workflows for agent-assisted open-source maintenance.

agent-zsh turns local repository state into reviewable context and wraps risky git operations with stricter checks. It is built for maintainers who jump between pull requests, checkpoint unfinished work, and need compact artifacts for code review.

Why This Exists

Maintainers spend a lot of time reconstructing context: what changed, what files matter, which branch is safe to rewrite, and where unfinished work went. agent-zsh makes those transitions explicit.

The plugin is intentionally local-first. It writes Markdown review artifacts, creates recoverable local branches, and refuses ambiguous branch state before history-changing operations.

What It Does

• Builds PR, commit, and whole-repo review bundles.
• Parks dirty work in local checkpoint branches with saved context.
• Guards force pushes with same-branch upstream checks, backups, and pinned leases.
• Guards reset-to-origin flows with previews and backup branches.
• Keeps everything local unless you explicitly run a git command that talks to origin.

Requirements

• zsh 5.8 or newer
• git
• Optional: fd, fzf, and gh for adjacent maintainer workflows

Install

Clone the repo and source the plugin:

git clone https://github.com/fallintoplace/agent-zsh ~/.agent-zsh
source ~/.agent-zsh/agent-zsh.plugin.zsh

Oh My Zsh:

git clone https://github.com/fallintoplace/agent-zsh \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/agent-zsh

Then add agent-zsh to your plugin list:

plugins=(git agent-zsh)

The stable command is agz. If you also want an agent command and do not already have one, set:

export AGENT_ZSH_ENABLE_AGENT_ALIAS=1

Quick Start

agz doctor
agz review pr
agz review commit HEAD
agz review repo --chunks 12
agz checkpoint save "parser cleanup"
agz checkpoint list
agz git forcepush --dry-run

30-Second Demo

tmp="$(mktemp -d)"
git clone https://github.com/fallintoplace/agent-zsh "$tmp/agent-zsh"
source "$tmp/agent-zsh/agent-zsh.plugin.zsh"

mkdir "$tmp/demo" && cd "$tmp/demo"
git init -q
git config user.name "Demo"
git config user.email "demo@example.com"
echo "# Demo" > README.md
git add README.md && git commit -q -m "chore: initial"
git branch -M main

git switch -q -c feature/cache
mkdir src
echo "cache_key=v1" > src/cache.txt
git add src/cache.txt && git commit -q -m "feat: add cache key"

agz review pr --base main
agz review repo --chunks 4

Command Map

Command	Purpose
agz review pr	Write a review bundle for the current branch compared with its base.
agz review commit	Write a review bundle for one commit or the last N commits.
agz review repo	Split tracked source files into chunked review files.
agz checkpoint save	Save dirty work into a local checkpoint branch with metadata.
agz checkpoint list	Show local checkpoint branches and saved context paths.
agz checkpoint resume	Switch to a checkpoint branch.
agz git forcepush	Force push with strict upstream matching, backups, and lease safety.
agz git reset-origin	Reset the current branch to origin/<same-branch> after preview and confirmation.
agz doctor	Check local dependencies.

Review Bundles

agz review pr writes a Markdown file under review-bundle/ by default. It includes:

• target metadata
• reviewer brief
• commits
• diff stat
• changed files
• full diff
• content blocks for changed files at HEAD

agz review pr --base origin/main
agz review pr --base main --output /tmp/my-pr-review.md

agz review commit handles either a specific commit or the last N commits:

agz review commit HEAD
agz review commit 3

agz review repo is for broad repo orientation. It skips common generated, dependency, and binary paths, then writes:

review-bundle/repo-<timestamp>/
  00_CONTEXT.md
  01_MANIFEST.md
  01_repo_chunk.md
  02_repo_chunk.md
  ...

Checkpoints

Checkpoints are local branches named agz/checkpoint/... plus metadata stored in the git common directory. They are useful when you want to park unfinished work before changing tasks.

agz checkpoint save "try new cache key"
agz checkpoint list
agz checkpoint show
agz checkpoint resume

save commits the dirty work on a checkpoint branch, then returns you to the source branch. Nothing is pushed.

Guarded Git

The guarded git commands are intentionally demanding:

• current branch must track origin/<same-branch>
• local tracking refs are fetched before decisions
• dirty working trees are rejected
• previews are available with --dry-run
• history-rewriting operations create backup branches

agz git forcepush --dry-run
agz git reset-origin --dry-run

Safety Model

agent-zsh is conservative by design:

• forcepush and reset-origin require origin/<same-branch> tracking.
• guarded git commands reject dirty worktrees.
• force pushes use a pinned --force-with-lease.
• backup branches are created before rewriting or discarding local history.
• checkpoint data stays in local git branches and git metadata directories.

Status

This is a pre-1.0 project. The first goal is a tight maintainer workflow that is easy to install, easy to audit, and recoverable when branch state gets messy.

Development

Run syntax checks and the integration test:

zsh -n agent-zsh.plugin.zsh lib/agent-zsh/*.zsh completions/_agz
zsh test/run.zsh

License

MIT