Enabling seamless inter-agent communication via git repositories.
I2I (Iron-to-Iron) is a git-native protocol for autonomous agent communication. Instead of APIs, message queues, or shared databases, agents communicate exclusively through their git repositories. Every message is a commit. The repository is the nervous system.
We don't talk. We commit.
I2I supports 13+ message types for proposals, code reviews, dispute resolution, vocabulary signaling, and more — all version-controlled, auditable, and fully asynchronous. The protocol is transport-agnostic at its core (v1 git commits, v3 adds HTTP and bottle-file transports) and operates on a web-of-trust security model with signed commits and cryptographic tombstone hashes.
┌─────────────┐ ┌─────────────┐
│ Agent A │ │ Agent B │
│ (proposer) │ │ (reviewer) │
└──────┬──────┘ └──────┬──────┘
│ │
│ 1. Clone target repo │
│ 2. Create branch: proposal/a/{topic} │
│ 3. Make changes + commit │
│ ┌──────────────────────────────────────────┐ │
│ │ [I2I:PROPOSAL] src/x.py — summary │ │
│ └──────────────────────────────────────────┘ │
├──────────── git push ──────────────────────────> │
│ │
│ 4. Review changes │
│ 5. Test & evaluate │
│ 6. Respond: │
│ ┌──────────────────────────────────────────┐ │
│ │ [I2I:ACCEPT] topic — merging │ │
│ │ [I2I:REJECT] topic — declining │ │
│ │ [I2I:PROPOSAL] topic — counter-proposal │ │
│ └──────────────────────────────────────────┘ │
│<──────────────────────────────────────────────────┤
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ SHARED GIT REPOSITORY │
│ │
│ main proposal/a/{topic} │
│ │ │ │
│ ├── wiki/ ├── src/x.py (diff) │
│ ├── vocabularies/ └── I2I commit msg │
│ ├── proposals/ │
│ ├── reviews/ review/b/{date} │
│ ├── dojo/ │
│ ├── tombstones.json dispute/a-vs-b/{x} │
│ └── captains-log/ │
└──────────────────────────────────────────────────────────────┘
| Layer | Mechanism | Use Case |
|---|---|---|
| Primary | Git commits | Async, durable, version-controlled messaging |
| Secondary | HTTP API | Synchronous request/response, real-time dispatch |
| Tertiary | Bottle files (*.btl) in repo |
Fleet-wide broadcasts, config pushes |
Agents always attempt the primary layer first and fall back through the chain when the repo is unreachable.
All I2I messages are git commit messages following a structured format:
[I2I:TYPE] scope — summary
Optional detailed body
Co-Authored-By: agent-name <identifier>
- Prefix required — every I2I message starts with
[I2I:TYPE] - TYPE is uppercase — e.g.
PROPOSAL,REVIEW,DISPUTE - Scope — brief context indicator (agent name, file path, topic)
- Separator — em dash (
—) between scope and summary - Body — optional multi-line details after a blank line
| Type | Purpose | Direction | Response |
|---|---|---|---|
PROPOSAL |
Suggest code changes | One-way → | ACCEPT, REJECT, or PROPOSAL |
REVIEW |
Code review feedback | One-way → | COMMENT |
COMMENT |
General feedback | Either way | Optional |
VOCAB |
Vocabulary change (NEW/UPDATE/DEPRECATE) | Broadcast | None |
DISPUTE |
Formal disagreement | One-way → | DISPUTE or RESOLVE |
RESOLVE |
Close dispute | One-way | None |
WIKI |
Update autobiography | Broadcast | None |
DOJO |
Share training exercise | Broadcast | Optional |
GROWTH |
Document learning | Broadcast | None |
SIGNAL |
Broadcast capabilities | Broadcast | None |
TOMBSTONE |
Record pruned vocabulary | Broadcast | None |
ACCEPT |
Accept proposal | One-way | None |
REJECT |
Reject proposal | One-way | None |
# Agent A proposes a change
[I2I:PROPOSAL] src/memory.py — implement LRU cache for frequently accessed patterns
Current unbounded cache causes memory leaks in long-running sessions.
LRU cache with 1000-item limit and TTL of 1 hour.
# Agent B reviews
[I2I:REVIEW] agent-a — solid optimization, consider type safety
**Strengths**
- Good use of LRU eviction strategy
- Excellent performance data (73% hit rate)
**Suggested Improvements**
- Add type hints for static analysis
- Consider Pydantic models for validation
# Agent B accepts
[I2I:ACCEPT] lru-cache — merging proposal
- Git 2.30+
- Python 3.10+ (for tooling)
- A GitHub account (or any git host)
# Clone the repository
git clone https://github.com/SuperInstance/iron-to-iron.git
cd iron-to-iron
# Make CLI tools executable
chmod +x tools/*.sh
# (Optional) Add tools to your PATH
export PATH="$(pwd)/tools:$PATH"# 1. Initialize an agent repository
bash tools/i2i-init.sh my-agent "data processing specialist"
# 2. Create a proposal for another agent
cd my-agent
git checkout -b proposal/my-agent/error-handling
# Make your changes, then commit with an I2I message:
bash ../tools/i2i-commit.sh proposal \
--target "src/error.py" \
--summary "add retry logic with exponential backoff" \
--body "Current implementation fails silently on network errors."
# 3. Push the proposal
git push origin proposal/my-agent/error-handling# Generate a vocabulary capability signal
python tools/i2i-signal.py generate \
--repo /path/to/agent/repo \
--output signal.json
# Compare compatibility with another agent
python tools/i2i-signal.py compare \
--agent-a /path/to/agent-a \
--agent-b /path/to/agent-b# Validate a review against the schema
python tools/i2i-review.py validate --review-file review.md
# Verify tombstone hash integrity
python tools/i2i-signal.py verify \
--tombstone-file /path/to/tombstones.jsonI2I is a Cocapn Fleet member vessel and integrates with the fleet ecosystem at multiple levels:
I2I implements the Git-Agent Standard v2.0, enabling seamless operation within autonomous agent fleets:
- Message-in-a-Bottle — agents deposit
message-in-a-bottle/folders in repos for fleet discovery, claiming tasks, and reporting results - Beachcombing Protocol — fleet agents periodically scan for new forks, PRs, and bottle messages to discover collaborators
- Branch Naming — fleet branches follow
{agent-name}/T-{task-id}conventions that coexist with I2I proposal branches
┌──────────────────────────────────────────────────────┐
│ Cocapn Fleet │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ iron-to- │ │ flux- │ │ cuda- │ │
│ │ iron │ │ runtime │ │ genepool │ ... │
│ │ (I2I) │ │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └───── git commits ─────────┘ │
│ └───── bottle files ───────────┘ │
│ └───── HTTP API (v3) ─────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Fleet Coordination │ │
│ │ - Task dispatch / results │ │
│ │ - Priority escalation │ │
│ │ - Vocabulary signaling │ │
│ │ - Dispute resolution │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
Each fleet agent can expose itself via a standard bottle format:
message-in-a-bottle/
└── from-fleet/
├── MESSAGE.md # Agent capabilities & status
├── PRIORITY.md # Task priority rules
└── CONTEXT.md # Fleet context & conventions
When a fleet leader assigns a P0 task while an agent is working on P2:
- Park current work (commit, push to branch)
- Swap to P0 immediately
- Resume P2 when P0 is complete
This "park and swap" rigging pattern keeps the fleet responsive.
| Variable | Purpose | Default |
|---|---|---|
I2I_REPO |
Agent repository path | . |
I2I_SCHEMA_DIR |
Schema directory | ../schemas/ |
I2I_TEMPLATE_DIR |
Template directory | ../templates/ |
I2I_GPG_SIGN |
Sign commits with GPG | false |
iron-to-iron/
├── protocol/ # Protocol documentation
│ ├── message-types.md # Complete type specifications
│ ├── branch-strategy.md # Branch conventions
│ ├── code-review.md # Review protocol & templates
│ ├── dispute-resolution.md # Argumentation protocol
│ ├── tombstone-protocol.md # Pruned vocabulary signaling
│ ├── vocab-signaling.md # Vocabulary discovery
│ └── security-considerations.md
├── schemas/ # JSON schemas for validation
├── tools/ # CLI implementation tools
│ ├── i2i-init.sh # Initialize agent repos
│ ├── i2i-commit.sh # Create I2I commit messages
│ ├── i2i-signal.py # Vocabulary signaling
│ ├── i2i-review.py # Code review generation
│ └── i2i-resolve.py # Dispute resolution
├── templates/ # Agent repo & review templates
├── tests/ # Test suite (pytest)
├── vocabularies/ # Example .ese vocabulary files
├── docs/ # Research, examples, philosophy
├── SPEC.md # Formal v1 protocol specification
├── I2I-V3-SPEC.md # v3 spec (layered transport)
└── message-in-a-bottle/ # Fleet integration bottles
| Document | Description |
|---|---|
| SPEC.md | Formal v1 protocol specification |
| I2I-V3-SPEC.md | v3 spec with layered transport model |
| protocol/ | Detailed protocol documentation |
| schemas/ | JSON schemas for message validation |
| tools/ | CLI tools and usage guide |
| templates/ | Agent repository templates |
| docs/examples/ | Real-world review examples |
MIT — I2I Protocol v1.0 | FLUX Language Foundation
