GitAgentProtocol (Open GAP) and gapman: Your Repository, Your Agent
Overview
GitAgentProtocol, also known as Open GAP, introduces a bold idea: treat a git repository as a living, portable agent. At the heart of the project sits gapman, the reference CLI that makes agents feel like native software projects. The vision is simple but powerful: a framework-agnostic, git-native standard for defining AI agents that can work across Claude Code, OpenAI, LangChain, CrewAI, and AutoGen. Instead of looping through disparate formats and runtimes, a single repository becomes an agent that can be exported to adapters and executed in diverse environments.
The core value proposition is deeper than a single toolchain. It’s about a community-driven, auditable, and compliant approach to agent design that fits modern software practices. The project emphasizes a Git-native model—versioning, branching, diffing, and collaboration are built in. It’s not just about the agent’s prompts; it’s about the whole lifecycle: identity, behavior rules, memory, tools, compliance, and orchestration, all living alongside the code that defines the agent.
Why This Approach Matters
A universal, portable agent definition: No more bespoke, framework-bound formats. Your repository defines the agent, and adapters translate that identity into the right runtime.
Built-in collaboration: Branching and PRs enable human-in-the-loop reviews for skill acquisition, memory updates, and policy changes.
Compliance by design: The framework includes first-class support for financial and regulatory requirements, with explicit patterns for segregation of duties and auditable records.
Composability and scalability: Agents can extend, depend on, and delegate to other agents, creating a modular, scalable agent ecosystem.
Transparency and traceability: Every change to an agent is captured in git history, with diffs and blame information ensuring a complete audit trail.
The Standard: Architecture of a Git-native Agent
The idea is that your repository becomes your agent. Drop a curated set of files into any git repo, and the project becomes a portable, framework-agnostic agent definition. Everything else, like the CLI, adapters, and patterns, builds on top of this foundation.
Two essential files (the minimum you need)
agent.yaml: Manifest—name, version, model, skills, tools, compliance, and more.
SOUL.md: Identity, personality, communication style, values.
Everything else is optional, chosen by you to fit your needs. This minimalist approach keeps the core identity clean while allowing rich extensions.
In practice, only two files are strictly required: agent.yaml and SOUL.md. The rest is optional, tailored to your needs. This is a deliberate design to keep the identity portable and versionable—everything else can be layered on top as required.
Patterns: Architectural Patterns Emerge
Human-in-the-Loop for RL Agents
When an agent learns a new skill or writes to memory, it opens a branch and a pull request for human review before merging. This keeps learning tightly coupled to human oversight and quality control.
Image reference:
Segregation of Duties (SOD)
A critical pattern to prevent single-agent dominance over a process. By defining roles (maker, checker, executor, auditor) and a conflict matrix, the system ensures proper safeguards. The validator catches violations before deployment. A sample YAML excerpt demonstrates roles and conflicts:
maker: create, submit
checker: review, approve, reject
Conflicts: maker vs checker
Handoff workflows ensure that certain actions require multi-party approval.
Image reference:
Live Agent Memory
The memory folder is a living archive. A runtime subfolder holds dailylog.md, key-decisions.md, and context.md to persist state across sessions. This enables a true memory layer that agents can reference over time.
Image reference:
Agent Versioning
Every git commit is a version of your agent. You can roll back prompts, revert skills, and explore past states—full undo history for the agent. Image reference:
Shared Context & Skills via Monorepo
Context, skills, and tools are shared at the repository root so every agent in the monorepo benefits from a single source of truth.
Image reference:
Branch-based Deployment
Adopt standard software workflows by promoting changes through environments using branches (dev → staging → main). This provides a familiar, reliable deployment model for agents as they mature.
Image reference:
Knowledge Tree
Store entity relationships as a hierarchical tree with embeddings. This structure supports runtime reasoning over structured data.
Image reference:
Agent Forking & Remixing
Fork a public agent repo, tailor its SOUL.md, add your skills, and submit upstream improvements. It’s collaborative by design, aligning AI agent development with open-source practices.
Image reference:
CI/CD for Agents
Run validations on every push via CI. Test agent behavior, block bad merges, and automate deployment—treat agent quality like code quality.
Image reference:
Agent Diff & Audit Trail
Git diff shows exactly what changed between agent versions. Git blame traces every line to its author and timestamp—full traceability baked in.
Image reference:
Tagged Releases
Tag stable agent versions (e.g., v1.1.0). Use tags to pin production, canary new versions on staging, and rollback instantly if needed.
Image reference:
Secret Management via .gitignore
Keep sensitive keys out of version control. API keys and secret configurations can live in a local .env file, ignored by Git. This keeps secrets local while enabling shareable configurations.
Image reference:
Agent Lifecycle with Hooks
Define bootstrap and teardown in the hooks directory to control startup and shutdown behavior. This ensures predictable lifecycle management.
Image reference:
SkillsFlow: Deterministic Workflows
Define multi-step workflows in workflows/, chaining skill, agent, and tool steps with explicit ordering and data flow. Each run follows a deterministic path, ensuring consistent behavior.
Code example (simplified):
Tip: prompt overrides and data flow are per-step, ensuring a tight, auditable script of execution.
Porting Framework Agents to GitAgent
GitAgent focuses on porting the identity layer—prompts, rules, roles, and tool schemas—into a portable format. What ports cleanly includes system prompts, persona definitions, hard constraints, tool schemas, and SOD policies. What stays in the framework includes runtime orchestration, live tool execution, memory I/O, and iterative loops. A well-known example demonstrates multiple agents (orchestrator → planner → researcher) with a centralized identity layer that travels across runtimes.
The quick-start journey demonstrates how to begin with gapman and grow into a production-ready agent system.
SR 11-7: Model Risk Management, validation cadence, ongoing monitoring
SR 23-4: Third-Party Risk, vendor due diligence, SOC reports
SEC / CFPB
Reg S-P: Customer privacy, PII handling
CFPB Circular 2022-03: Explainable adverse action, Less Discriminatory Alternative
DUTIES & Enforcement
Roles & permissions and a conflict matrix
Handoff workflows that require multi-agent participation for critical actions
Isolation: separate state and credentials between roles
Enforcement: strict or advisory
These principles are designed to be validated by the built-in tooling and ensured through the repository structure, so adherence to regulatory requirements can be audited alongside code quality.
Adapters: Translating Identity into Runtime
Adapters are the translation layer that makes the same agent definition usable in multiple runtimes. They bridge the gap between the portable identity and the runtime-specific system prompts, tool schemas, and orchestration logic.
Common adapters include
system-prompt: Concatenated system prompts usable by any LLM
claude-code: Claude Code format
openai: OpenAI Agents SDK Python code
crewai: CrewAI YAML configuration
lyzr: Lyzr Studio integration
github: GitHub Actions agent
git: Git-native execution
opencode: OpenCode configuration
gemini: Google Gemini CLI
openclaw: OpenClaw format
nanobot: Nanobot format
cursor: Cursor-based format
Exporting and running with adapters is a core workflow, enabling teams to validate and deploy agents across ecosystems without rewriting the agent’s identity.
Inheritance & Composition: Extending Agents
Agents can extend a parent agent or compose with dependencies. This makes it possible to build complex hierarchies while preserving a clean identity layer.
The repository includes several examples that illustrate different levels of completeness and complexity:
examples/minimal: two-file hello world (agent.yaml + SOUL.md)
examples/standard: code review agent with skills, tools, and rules
examples/full: production compliance agent with all directories, hooks, workflows, SOD, and regulatory artifacts
examples/gitagent-helper: helper agent that assists with creating gitagent definitions
examples/lyzr-agent: Lyzr Studio integration
Specification and Validation
Full specification is available in spec/SPECIFICATION.md, with JSON Schemas for validation in spec/schemas/. This ensures a formal, machine-readable standard that can be used by validators and adapters alike.
Star History and Community
GitAgentProtocol has a recognizable presence in the open-source community. A star history visualization reflects the project’s adoption trajectory, and the community is encouraged to share their own agent creations and experiences.
License
MIT
Immersive Visuals and Patterns
The design language of GitAgentProtocol uses a series of visuals to illustrate patterns and workflows. The imagery emphasizes the cognitive and operational layers of an agent—memory, decision-making, versioning, and governance. The banner sets the tone, while the supporting diagrams reinforce the habits of living repositories and their agents.
A gallery of pattern images to explore
Human-in-the-Loop for RL Agents
Image:
Live Agent Memory
Image:
Agent Versioning
Image:
Shared Context
Image:
Branch-based Deployment
Image:
Knowledge Tree
Image:
Agent Forking & Remixing
Image:
CI/CD for Agents
Image:
Agent Diff & Audit Trail
Image:
Tagged Releases
Image:
Secret Management
Image:
Agent Lifecycle Hooks
Image:
A Final Note: The GitAgent Promise
GitAgentProtocol and gapman invite you to reimagine AI agents as first-class software artifacts. The repository is not just a codebase; it’s a living contract between people and machines. It codifies who the agent is, what it should do, how it should behave in compliance with regulations, and how it evolves through collaborations, reviews, and governance.
If you’ve ever wanted a portable, auditable, and scalable way to define AI agents that can travel across runtimes, this is your invitation to explore the GitAgent world. Set up a repository that becomes a robust, versioned agent—and watch how the same identity can propel multiple runtimes, adapters, and teams toward shared goals. The journey begins with two files, but it ends in a universe of modular, trustworthy agents that you can fork, remix, and improve—together.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.