GitLoop Local

Start with PRD.md, then inspect the proposed entry points in hooks/post-push, notifier/server.py, and mcp/server.py and tools.py. The issue describes a multi-component design with unresolved open questions, so a contributor should first narrow it to a concrete component and acceptance criteria before implementation; no tests or bounded definition of done are provided.

gitloop — PRD

Status: Draft
Scope: Local inner-loop only — no CI/CD integration

Problem

Multiple AI coding agents (Claude, Codex, Copilot) working on tasks in parallel
have no shared, tool-agnostic way to signal progress, hand off work, or trigger
peer review. Each tool uses its own state — the pipeline is in someone's head.

gitloop makes git tags the canonical workflow state. Any tool, on any machine,
can participate by reading and writing tags. No shared database, no orchestration
service, no CI/CD dependency.

Works in conjunction with https://github.com/MrLesk/Backlog.md to watch tasks

Core idea

A git tag is a workflow step. The tag name encodes exactly where a task sits in
the pipeline. A post-push hook emits an event when a tag is pushed. A lightweight
notifier queues those events. Workers consume the queue via three MCP tools,
claim tasks atomically, and advance them to the next step.

The remote repo is the single source of truth. The notifier is a wake-up call
only — any worker can reconstruct full state with: git fetch && git tag -l

Tag schema

/TASK-N

Pipeline order:

in-progress/TASK-N agent claimed and started work
code-complete/TASK-N implementation committed, ready for tests
test-complete/TASK-N lint + tests + build passing locally
review-complete/TASK-N review passed, safe to merge
merged/TASK-N done, worktree can be pruned

Rejection loops back with a version increment:

review-complete/TASK-9 → rejected → in-progress/TASK-9/v2

Claim tag (race safety):

claimed/TASK-N

Pipeline flow

backlog.md (status: todo)
|
v
agent picks up task
git worktree add task/TASK-N
git tag in-progress/TASK-N && git push --tags
|
v (author works)
git tag code-complete/TASK-N && git push --tags
|
v (test runner / agent)
run lint + test + build
git tag test-complete/TASK-N && git push --tags pass
git tag in-progress/TASK-N/v2 && git push --tags fail, loop back
|
v (reviewer agent / human)
git diff main...task/TASK-N, write review.md, commit
git tag review-complete/TASK-N && git push --tags pass
git tag in-progress/TASK-N/v2 && git push --tags reject, loop back
|
v
git merge --no-ff task/TASK-N
git tag merged/TASK-N && git push --tags
backlog.md status: done
git worktree remove task/TASK-N

Components

1. post-push hook

File: .git/hooks/post-push
Language: bash (~25 lines)

Fires after every git push. Reads pushed refs, finds tags matching the step
schema, POSTs a JSON payload to the notifier for each one.

Payload shape:
step "code-complete"
task "TASK-9"
branch "task/TASK-9"
sha "a3f9c2"
repo "apim"
tool "claude" (read from git config gitloop.tool, default "unknown")

Fire-and-forget. If the notifier is down the push still succeeds.

2. tag-notifier

File: ~/src/gitloop/notifier/server.py
Language: Python, flask
Storage: ~/src/gitloop/notifier/events.db (SQLite, created on first run)
Port: 7777

Endpoints:
POST /event accept payload from hook, append to queue
GET /pending?step= return unclaimed events, filter by step if given
POST /claim mark event claimed by a worker id
GET /state full pipeline state across all tasks

For cross-machine use: expose via SSH tunnel or ngrok, no code changes needed.

3. MCP tools (worker side)

Files: ~/src/gitloop/mcp/server.py, tools.py
Language: Python, MCP SDK
Transport: stdio (local) or SSE (cross-machine)

get_pending_tasks
input: step (optional)
output: list of pending events from GET /pending

claim_task
input: task, worker_id
output: success | already_claimed
steps: POST /claim to notifier
git fetch
git push origin claimed/TASK-N
git push rejection = someone else got there first, return already_claimed

advance_task
input: task, next_step, message (optional)
output: success | blocked
steps: validate legal transition
git tag -a next_step/TASK-N -m "message"
git push --tags (hook fires, notifier receives event)

Legal transitions:
in-progress -> code-complete
code-complete -> test-complete | in-progress/vN
test-complete -> review-complete | in-progress/vN
review-complete -> merged
merged -> terminal

Repo layout

~/src/gitloop/
├── PRD.md
├── notifier/
│ ├── server.py
│ └── events.db
├── mcp/
│ ├── server.py
│ └── tools.py
└── hooks/
└── post-push

Install into a repo

ln -sf ~/src/gitloop/hooks/post-push .git/hooks/post-push
git config gitloop.notifier http://localhost:7777
git config gitloop.tool claude

Start the notifier

cd ~/src/gitloop/notifier && python server.py

Wire up MCP in claude_desktop_config.json

{
"mcpServers": {
"gitloop": {
"command": "python",
"args": ["/Users/you/src/gitloop/mcp/server.py"]
}
}
}

Out of scope for now

CI/CD integration
Notifier authentication
Persistent worker registration
Automatic worktree lifecycle
UI / dashboard

Open questions

1. Should advance_task enforce CI pass before allowing test-complete, or leave to caller?
2. SSE push from notifier vs polling GET /pending — worth it locally?
3. Should review.md be required on the branch before review-complete is legal?