Multi-phase layered staging areas for Git — a safe space to experiment with AI agents before committing.
Standard Git gives you three phases: Working Tree → Index (Staged) → Committed (HEAD).
When coding with AI agents, one staging area isn't enough. Agents generate large, fast, half-baked diffs where some hunks are ready, some need another pass, and others are raw experiments.
git-drafts (gd) lets you stack as many revision layers as you need on top of HEAD using native Git indices (GIT_INDEX_FILE), so you can iterate, isolate hunks, and never commit until you're sure — and then commit all or part of your verified layer.
- Built for AI-agent workflows: Keep raw agent output in
draft, human-checked edits inreviewed, and commit-ready changes inready— without polluting your commit history or losing track of what you actually vetted. - As many layers as you want: Start with
ready < reviewed < draft, or insert custom phases (tested,security-checked,polish, etc.) at any position in the stack. - Hunk-level precision (
-p& IDE): Promote, demote, drop, or partially commit individual hunks without touching your working tree. - Don't commit prematurely: Experiment across multiple agent turns in layered draft buffers before anything touches
HEAD. - Seamless VS Code integration: Embedded Draft Layers panel right inside Source Control, bidirectional
.git/indexmirroring, multiselect batch actions, and diff-editor hunk buttons. - 100% Git-native & fast: Zero-dependency Rust binary driving Git's own plumbing with stat-keyed tree caching. Zero repo format lock-in;
.git/hooks, GPG signing, and standardgitcommands keep working. - Reversible: Up to 15 undo snapshots (
gd undo) plus automatic 3-waymerge-treere-anchoring whenHEADmoves externally.
Layers are stored in .git/drafts/ as an ordered stack of standard Git index files from most revised (closest to HEAD) to least revised (closest to Working Tree):
flowchart BT
WT["[WT] Working Tree (unstaged & untracked)"]
L3["[L3] draft — raw AI-agent experiments"]
L2["[L2] reviewed — human-checked hunks"]
L1["[L1] ready — commit target · mirrors .git/index"]
HEAD["HEAD (committed history)"]
WT -- "gd stage ↑" --> L3
L3 -- "gd promote ↑" --> L2
L2 -- "gd promote ↑" --> L1
L1 -- "gd commit (all or -p) ↑" --> HEAD
L1 -. "gd demote ↓" .-> L2
L2 -. "gd demote ↓" .-> L3
L3 -. "gd demote --to wt ↓" .-> WT
Each layer index holds a cumulative tree snapshot (HEAD ⊆ L1 ⊆ L2 ⊆ ... ⊆ Ln ⊆ WT):
- What is shown inside layer
kis the exact delta betweenL(k-1)andLk. - Promoting (
↑) moves paths or hunks towardready. - Demoting (
↓) pushes paths or hunks away from commit. - Committing (
gd commit) commitsL1(ready) — or only selected paths/hunks fromL1— whileL2..Lnremain intact above the newHEAD.
git(2.38+ recommended for 3-waymerge-treere-anchoring)- Rust toolchain (
cargo/rustc)
cargo install --git https://github.com/Girgis98/git-drafts.gitOr build from source:
git clone https://github.com/Girgis98/git-drafts.git
cd git-drafts
cargo install --path . --lockedThis installs both gd and git-drafts (run gd <cmd> or git drafts <cmd>).
gd init
# Initialized layers: ready < reviewed < draftEnable bidirectional .git/index mirroring (for IDEs) or custom layer names:
gd init --sync-git-index
gd init ready audited draft raw-agentgd stage -A # or: gd stage src/auth.rs
gd status # alias: gd st[L1] ready (commit target) (0 files)
(clean)
[L2] reviewed (0 files)
(clean)
[L3] draft (2 files)
M src/auth.rs
A src/token.rs
[WT] working-tree (0 modified, 0 untracked)
(clean)
gd diff draft # diff of L3 (reviewed..draft)
gd diff wt # unstaged diff in working tree
gd diff --from head --to draftgd promote src/token.rs # draft -> reviewed
gd promote src/token.rs # reviewed -> ready
gd promote --from draft --to ready -p src/auth.rs # interactive hunk splitLet your agent continue editing src/auth.rs in the working tree, then stage new experiments into draft:
gd stage src/auth.rsPreviously promoted hunks stay isolated in ready/reviewed, while new experiments sit cleanly above them in draft.
gd commit -m "feat(auth): add token validation" # commit entire ready layer
gd commit src/token.rs -m "feat(auth): add token util" # partial file commit
gd commit -p -m "feat(auth): partial auth fix" # partial hunk commitgd demote src/auth.rs # move one layer toward WT
gd demote --from draft --to wt -A # unstage draft back to working tree
gd drop draft --cascade src/exp.rs # remove from draft & upper layers (keeps WT)
gd drop draft --hard src/exp.rs # remove from layers AND revert WT
gd undo # restore previous layer state (last 15 ops)gd layer list
gd layer add qa --above reviewed # insert phase between reviewed & draft
gd layer rename qa security-check
gd layer rm security-check --merge-down # or --merge-up / --dropgit-drafts integrates at three levels:
- VS Code / Cursor Extension (VS Code Marketplace · Source):
- Draft Layers tree directly inside Source Control (with multiselect
Stage,Promote ↑,Demote ↓,Drop,Commit File) - Dedicated Git Drafts Activity Bar (
Draft Pipelinewebview +Changed Filestree) - Inline actions on built-in VS Code Git items (
Stage to Top Draft,Stage to Layer...,Demote from Ready ↓) - Diff editor title buttons (
Promote Hunk ↑/Demote Hunk ↓) and live Status Bar counter
Or build from source:code --install-extension GirgisMamdouh.git-drafts
cd editors/vscode npm ci && npm run compile npx @vscode/vsce package --out git-drafts.vsix code --install-extension git-drafts.vsix
- Draft Layers tree directly inside Source Control (with multiselect
- Bidirectional
.git/indexMirror (any IDE):gd config sync-git-index truekeeps[L1] readysynced with.git/index, so built-in Git UIs showreadyunder Staged Changes whilereviewed/draftstay isolated. - Machine-readable CLI Primitives:
gd status --json,gd blob <layer|head|wt> <path> --allow-missing, andgd patch-apply --from A --to B.
Keep AI coding assistants productive without letting half-tested edits leak into Git history — coding agents stage drafts, review agents promote vetted hunks, and commits stay gated behind human or Lead approval.
Initialize instructions, the canonical Agent Skill (SKILL.md), and MCP configuration in any repo:
gd agent init # writes AGENTS.md, .agents/skills/git-drafts/SKILL.md, & updates detected configs
gd agent init --target all # adds CLAUDE.md, GEMINI.md, Cursor .mdc, Copilot instructions, & .vscode/mcp.json
gd agent snippet # prints the concise Markdown rule block for manual pastingIn VS Code, click AI Agents in the Draft Pipeline toolbar (or run Git Drafts: Setup Agent Instructions & MCP) to pick your files and MCP guardrail role interactively.
Supported --target & file mappings
| Target flag | Generated / updated path | Used by |
|---|---|---|
agents |
AGENTS.md |
Codex, Antigravity, universal agents |
skill |
.agents/skills/git-drafts/SKILL.md |
Agent Skill-compatible assistants |
claude |
CLAUDE.md |
Claude Code |
gemini |
GEMINI.md |
Gemini CLI |
cursor |
.cursor/rules/git-drafts.mdc |
Cursor (alwaysApply: true) |
copilot |
.github/copilot-instructions.md |
GitHub Copilot |
mcp |
.vscode/mcp.json |
VS Code / MCP stdio clients (defaults to --role reviewer) |
auto (default) |
AGENTS.md + SKILL.md + any already-present tool files |
Minimal repo footprint |
all |
All of the above | Teams using mixed AI tools |
(Markdown injections use <!-- git-drafts:start --> / <!-- git-drafts:end --> markers so re-running is idempotent and preserves your existing rules.)
- Mode A · Solo Dev + 1 AI Assistant (Default
--role reviewer):
Your assistant writes code, runs tests, stages into[L3] draft, and promotes verified files/hunks to[L2] reviewed— whiledraft_commitis blocked. You inspect the clean diff in VS Code and commit[L1] readywhen sure. - Mode B · Multi-Agent Swarm (
Coder → Reviewer → Lead):
Assign each agent its own MCP role process so layer boundaries are enforced on the server side rather than relying on prompts alone:
| Role | Launch Command | Permitted Layer Scope |
|---|---|---|
| Coder | gd mcp --role coder |
Inspect (status, diff, blob) + draft_stage / draft_demote / draft_drop on top draft layer only · cannot promote or commit |
Reviewer (default in init) |
gd mcp --role reviewer |
Coder tools + draft_promote / draft_demote / draft_patch_apply across layers · cannot commit or manage layers |
| Lead | gd mcp --role lead |
Full pipeline including draft_commit, draft_init, and draft_layer_manage |
Example: multi-role .vscode/mcp.json & built-in MCP tool list (12 tools)
{
"servers": {
"git-drafts-coder": { "type": "stdio", "command": "gd", "args": ["mcp", "--role", "coder"] },
"git-drafts-reviewer": { "type": "stdio", "command": "gd", "args": ["mcp", "--role", "reviewer"] },
"git-drafts-lead": { "type": "stdio", "command": "gd", "args": ["mcp", "--role", "lead"] }
}
}- Read-only (
readOnlyHint: true):draft_status,draft_diff,draft_blob - Draft / Review mutations:
draft_stage,draft_promote,draft_demote,draft_patch_apply,draft_undo,draft_init - Destructive / Commit gate (
destructiveHint: true):draft_drop,draft_commit,draft_layer_manage
| Command | Description |
|---|---|
gd init [--force] [--sync-git-index] [layers...] |
Initialize layers (default: ready reviewed draft) |
gd status / gd st [--json] |
Show parallel per-layer file status (L1..Ln + WT) |
gd diff [<layer>|wt] [--from A --to B] [-- <paths...>] |
Show diff for a layer or between any two states |
gd stage [-l <layer>] [-p|-A] [<paths...>] |
Stage WT changes into <layer> (default: top layer) |
gd promote [--from L] [--to L] [-p|-A] [<paths...>] |
Move changes toward HEAD (ready) |
gd demote [--from L] [--to L|wt] [-p|-A] [<paths...>] |
Move changes back toward draft / WT |
gd drop <layer> [-p|-A] [--cascade] [--hard] [<paths...>] |
Discard changes from a layer |
gd commit [-p] [<paths...>] [git-commit-opts...] |
Commit [L1] ready (all or selected paths/hunks) |
gd layer list | add | rm | rename |
Manage revision layers dynamically |
gd blob <spec> <path> [--allow-missing] |
Print raw file bytes at a layer/head/wt |
gd patch-apply --from A --to B |
Apply unified diff from stdin between layers |
gd config sync-git-index [true|false] |
Mirror [L1] ready into .git/index |
gd agent init [--target T] [--role R] [--mcp-command CMD] |
Generate AGENTS.md, SKILL.md, & MCP config (default role: reviewer) |
gd agent snippet |
Print concise agent instruction block |
gd mcp [--role coder|reviewer|lead] |
Start stdio MCP server with role guardrails |
gd undo |
Restore previous layer snapshot |
Licensed under the MIT License.