gnap

GNAP (Git-Native Agent Protocol) is a Git-based agent orchestration protocol designed to let teams of AI agents collaborate through a shared git repository. It does not rely on servers, databases, or vendor lock-in, using only git as the transport and storage layer. Any agent capable of performing git push (such as OpenClaw, Codex, Claude Code, or a custom bot) can join. The protocol itself defines only four entities; everything else is application layer.

Purpose: to coordinate multiple AI agents (as well as human participants) to complete tasks together, suitable for scenarios that require auditing, offline work, or avoiding infrastructure maintenance.

Main capabilities:

• Zero infrastructure: no need to deploy servers or maintain databases.
• Any runtime: as long as an agent can read and write git, it can participate.
• Auditable by default: git history is the audit log.
• Human in the loop: humans and AI agents are both first-class participants.
• Offline-capable: agents can work disconnected and sync later.
• Composable: application layers such as budgets, workflows, and dashboards can be built on top of it.

The four entities:

1. agents.json: registers human or AI participants. Required fields are not listed in detail in the materials; details such as optional fields and reserved fields (Agent ID * is used for broadcast and cannot be used as an identifier) are not fully provided.
2. tasks: units of work, one JSON file per task, located at .gnap/tasks/{id}.json. Supports state transitions: review → in_progress (reviewer rejects, agent redoes the work), blocked → ready (unblocked, agent picks it up again).
3. runs: one attempt at a task, one JSON file per run, located at .gnap/runs/{task-id}-{attempt}.json. A task can have multiple runs; a failed run does not affect the task, and a new run can be created. Provides cost tracking, retry history, auditing, and performance comparison.
4. messages: communication between agents, one JSON file per message, located at .gnap/messages/{id}.json.

How to use:

• Add a .gnap/ directory to any git repository, containing a version file (a pure integer protocol version; agents should check it at startup and refuse to operate if the version is higher than supported) and the above JSON files.
• Agents run a heartbeat loop: pull the repository, find tasks assigned to themselves, perform the work, commit and push the results.
• Details such as commit conventions, conflict handling (standard git merge; on conflict, pull + rebase + retry push), consistency model (eventual consistency, bounded by the maximum heartbeat interval), and ordering fields (at in messages, created_at / updated_at in tasks) are mentioned in the materials but not fully expanded.
• New agent onboarding process: register (add an entry with status: active in agents.json), grant git read/write permissions, create the first task (such as a check-in task and assign it to the new agent), and the agent reads and completes the task on its next heartbeat.

Applicable scenarios:

• Multiple agents collaborating to complete tasks.
• Processes that require audit trails and human in the loop.
• Offline or intermittently connected environments.
• Teams that do not want to maintain servers and databases.
• Already in production use: Farol Labs' AI team (4 agents, 2 AI + 2 humans) shares 50+ tasks through a single git repository.

Limitations:

• The protocol defines only entities and transport; it does not include business logic (such as company goals, budgets, workflows, etc., which belong to the application layer).
• It relies on git's eventual consistency, and conflicts must be merged manually or automatically.
• Detailed field definitions, the complete rules of the state machine, and the specific format of commit conventions are not fully provided in the materials.