gitagent

Agent workspace manager over Git: isolate, review and consolidate multi-agent changes into a single commit per feature — directly on main.

gitagent is a lightweight CLI that wraps git worktree so a superagent can spawn isolated subagents per feature, collect their work as proposals (patch + manifest), accept/reject/revise them, and finally produce one clean commit on main — then clean everything up. It never pushes.

Branchless workflow: you never need to git checkout ga/<feature>. All commands accept --feature <name>. Your local repo stays on main (or wherever you are) throughout.

The headline feature: multiple features in parallel. Create one git branch per feature (ga/<name>), run gitagent start on each, and switch between them. Each feature keeps its own session, agents, proposals, and integration branch. The superagent merges each finished feature branch into main with normal git.

Two planes are kept strictly separate:

• .git — the source of truth. Untouched until finalize, which writes exactly one commit on main (or a configured target).
• .gitagent/ — an ephemeral coordination layer, one subdirectory per feature: worktrees, patches, manifests, decisions, audit log. Discardable and reset after finalize/abort.

gitagent does not reimplement Git. Proposals are stored as git diff patches plus JSON metadata, never as a second history.

Decision / application split (Option B)

gitagent cleanly separates deciding from applying:

So a minimal flow is: accept each → finalize. Run integrate standalone when you want to see conflicts before the final commit.

Install

The PyPI distribution is gawt (the name gitagent on PyPI is a different, unrelated project). The command it installs is still called gitagent.

# end user (isolated environment)
pipx install gawt
# or
uv tool install gawt

# from GitHub
pipx install "git+https://github.com/david-fm/gawt"

# local development
git clone https://github.com/david-fm/gawt && cd gawt
uv tool install . -e   # or: pipx install -e .

Requires Python 3.11+ and a working git on PATH.

Quick start (single feature)

gitagent init

# Start a feature from main (no checkout needed)
gitagent start --feature auth-rate-limiting

# each subagent gets an isolated worktree + ephemeral branch
gitagent spawn --feature auth-rate-limiting --id a_backend --role "implement limiter"
gitagent spawn --feature auth-rate-limiting --id a_tests --role "write tests"

# subagents work in their own folders, then propose (no commit to .git)
gitagent propose --feature auth-rate-limiting --agent a_backend \
                 --title "Token bucket limiter" --confidence 0.85
gitagent propose --feature auth-rate-limiting --agent a_tests \
                 --title "Limiter tests" --confidence 0.9

# superagent reviews and marks decisions
gitagent proposals --feature auth-rate-limiting
gitagent show --feature auth-rate-limiting p_7f3a
gitagent accept --feature auth-rate-limiting p_7f3a
gitagent revise --feature auth-rate-limiting p_9b2c --feedback "add edge cases"
# ... a_tests re-proposes (a new pid is generated) ...
gitagent accept --feature auth-rate-limiting p_9b2c

# OPTIONAL: pre-flight apply to surface conflicts before committing
gitagent integrate --feature auth-rate-limiting

# consolidate into ONE commit on main, then reset
gitagent finalize --feature auth-rate-limiting \
                  --message "feat(auth): add rate limiting with tests"
# → 1 commit on main, .gitagent reset, no push

Multi-feature in parallel

Features are identified by name, not by branch. finalize lands each feature directly on main — no manual merges needed.

gitagent init

# === Feature A: auth rate limiting (no checkout needed) ===
gitagent start --feature auth-rate-limiting
gitagent spawn --feature auth-rate-limiting --id a_backend
# ... a_backend works, proposes, you accept, integrate, finalize ...
gitagent finalize --feature auth-rate-limiting --message "feat(auth): rate limiting"
# → 1 commit on main, ga/auth-rate-limiting deleted

# === Feature B: user profile (parallel) ===
gitagent start --feature user-profile
gitagent spawn --feature user-profile --id a_frontend
# ... a_frontend works, proposes, you accept, integrate, finalize ...
gitagent finalize --feature user-profile --message "feat(user): profile page"
# → 1 commit on main, ga/user-profile deleted

# Both commits are on main. No git merge needed.

gitagent status (without --feature) shows every feature and its session state. Use --feature <name> for the detail view of a single feature.

integrate resets the integration worktree to the live target branch before applying proposals, so cross-feature conflicts surface immediately.

Commands

How it works

• Branchless supervisor: all commands accept --feature <name>. Without it, the current branch is used as default (with a deprecation warning). Your local checkout is never disturbed.
• One feature = one session: identified by name, stored in .gitagent/features/<key>/. The ga/<name> branch is internal — created at start, deleted at finalize.
• Isolation: git worktree add gives every agent its own HEAD, index and working tree while sharing the object store — ideal for parallelism.
• Per-feature storage: each feature gets its own directory under .gitagent/features/<key>/, holding its session, agents, proposals, integration worktree, and locks. The audit log (log.jsonl) is global and spans all features.
• Proposals as patches: git -C <worktree> diff --cached <base_sha> --binary is stored as change.patch and re-applied with git apply --3way on the integration worktree. Agent "commits" never pollute the final history.
• Live cross-feature conflict detection: integrate resets the integration worktree to the current state of the target branch (default main) before applying proposals. If another feature was already finalized on main, its changes are visible and 3-way merge conflicts surface immediately.
• Single commit on main: finalize uses a detached temp worktree on the target branch, squash-merges the integration branch, creates one commit, and updates the target ref via update-ref. The user's checkout is untouched. The ga/<feature> branch is deleted (use --keep-feature-branch to preserve it).
• Conflicts: a conflicting patch is marked conflict at integrate time — the session stays alive so the superagent can revise, fix the integration worktree manually (then re-accept + re-integrate), or abort.
• Concurrency: file locks (fcntl) guard review-state writes; accept is safe to race (it only marks).
• Audit: every event is appended to .gitagent/log.jsonl (parseable by another agent/LLM). Spans all features.
• Dual output: humans get Rich tables; --json and diff give raw, pipe-friendly output for orchestration.

Layout

.gitagent/
├── features/
│   ├── <feature-key>/
│   │   ├── session.json          # active session: id, feature, base_sha, state
│   │   ├── agents/<agent-id>/
│   │   │   ├── meta.json         # role, worktree path, ephemeral branch, state
│   │   │   └── worktree/         # git worktree for this agent
│   │   ├── proposals/<proposal-id>/
│   │   │   ├── manifest.json     # agent, base_sha, files, summary, confidence
│   │   │   ├── change.patch      # git diff of the proposal
│   │   │   └── review.json       # pending|accepted|integrated|rejected|revise|conflict + feedback
│   │   ├── integration/worktree/ # integration branch under construction
│   │   └── locks/                # fcntl lockfiles for concurrent writes
│   └── ...
└── log.jsonl                     # append-only audit trail (global, all features)

Proposal states: pending → accepted → integrated | conflict | revise | rejected. Session states: open → integrating → finalized | aborted.

Installing the agent skill

gitagent ships with a skill so any AI agent can use it freely — it teaches another agent the full CLI surface, the decision/application split, the branchless multi-feature workflow, conflict resolution recipes, and the supervisor/coder/reviewer patterns.

The skill lives in the repo at skills/gitagent/SKILL.md (single file — opencode's skill system only reads SKILL.md) and gets installed into the local opencode skills directory so future agent sessions can load it.

From a gitagent install (pipx / pip / uv tool)

gitagent install-skill
# → installs bundled skill to ~/.agents/skills/gitagent
# → re-run to refresh after upgrading gitagent

From a git clone (developers / source installs)

git clone https://github.com/david-fm/gawt
cd gawt
make install-skill
# (equivalent to: bash scripts/install-skill.sh)

Manual

cp -R skills/gitagent ~/.agents/skills/

The skill will be available to agents in future sessions. Re-run any of the above commands to refresh the installed copy.

Design principle

finalize never runs git push. It produces a local commit on the feature branch and stops. The superagent merges feature branches into main with normal git (squash, PR, whatever the team uses).

License

MIT © David Florez Mazuera