AgentGit

Git-native multi-agent orchestration. Agents work on isolated branches. Nothing merges without a real, deterministic validation gate.

English · Français · Protocol spec · Architecture · Comparison

---

Positioning, in one sentence

Coordination protocols like gnap answer who owns which task. AgentGit answers the question they deliberately leave open: how does a task's work get validated and merged without trusting an agent's self-report?

Read the full breakdown: docs/en/comparison.md.

How it works

Orchestrator
     │
  ┌──┼──┐
Agent Agent Agent      ← each on its own branch, own workspace
  │    │    │
Commit Commit Commit
  └──┼──┘
     │
scripts/validate.sh      ← runs a real command, reads a real exit code
     │
   pass? ── no ──▶ task marked "rejected", back to the agent
     │
    yes
     │
scripts/merge.sh         ← refuses to run unless state is "approved"
     │
   main

No task reaches main because an agent said so. It reaches main because scripts/validate.sh ran a command and got exit code 0. That's the entire value proposition — everything else in this repo supports that one rule.

Quickstart

Not published to npm yet — npx agentgit won't work until it is (see CHANGELOG.md for status). Two ways to try it today:

Option A — clone and run directly

git clone https://github.com/Tryboy869/AgentGit.git
cd your-other-project
node /path/to/AgentGit/bin/agentgit.js init

Option B — npm link (get a plain agentgit command)

git clone https://github.com/Tryboy869/AgentGit.git
cd AgentGit
npm link

cd ~/your-other-project
agentgit init

A few examples, once linked:

agentgit create-task "Add OAuth callback handler"
agentgit create-task "Write onboarding docs"
agentgit status
# AG-1   draft   agent/unassigned/AG-1   Add OAuth callback handler
# AG-2   draft   agent/unassigned/AG-2   Write onboarding docs

# an agent (or you) does the work on the created branch, then:
agentgit validate AG-1
agentgit merge AG-1     # only succeeds if AG-1 is "approved"

Once published, the same commands will work as npx agentgit ... — no clone or link needed.

You don't need the CLI at all — .agentgit/ is plain, documented JSON. See docs/en/protocol.md for the file format, and examples/.agentgit/ for a working example.

Design principles

• Git, not GitHub. The core only ever talks to a local Git repository. No hosting-platform API required. See docs/en/architecture.md.
• The file format is the contract, not the CLI. Any agent that can read files and run git can participate — in any language, on any runtime.
• Validation is deterministic or it doesn't count. No "the agent says it passed." A real command, a real exit code.
• Small core, honest boundaries. See what's explicitly out of scope in docs/en/architecture.md#mvp-boundary.

Where things live

Full map (for humans and for AI agents navigating this codebase): MAP.md.

Status

Pre-alpha. The validation and merge gates (scripts/validate.sh, scripts/merge.sh) are implemented and tested end-to-end. Automatic task decomposition, a reviewer agent, and a dashboard are not built yet — see CHANGELOG.md and the MVP boundary in docs/en/architecture.md.

Contributing

See CONTRIBUTING.md (French: CONTRIBUTING.fr.md).

License

MIT