{"id":45841423,"url":"https://github.com/open-gitagent/gitagent","last_synced_at":"2026-04-03T05:01:57.865Z","repository":{"id":340394399,"uuid":"1165855406","full_name":"open-gitagent/gitagent","owner":"open-gitagent","description":"A framework-agnostic, git-native standard for defining AI agents","archived":false,"fork":false,"pushed_at":"2026-03-23T14:13:21.000Z","size":24577,"stargazers_count":1121,"open_issues_count":21,"forks_count":115,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-03-24T11:54:32.037Z","etag":null,"topics":["agent","agent-framework","agent-skills","agents","assistant","claude-code","gitagent","open-standard","openclaw","skills"],"latest_commit_sha":null,"homepage":"https://gitagent.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-gitagent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["shreyaskapale"]}},"created_at":"2026-02-24T16:08:24.000Z","updated_at":"2026-03-24T11:47:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/open-gitagent/gitagent","commit_stats":null,"previous_names":["open-gitagent/gitagent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/open-gitagent/gitagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-gitagent","download_url":"https://codeload.github.com/open-gitagent/gitagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31335170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T04:42:29.251Z","status":"ssl_error","status_checked_at":"2026-04-03T04:42:12.667Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-framework","agent-skills","agents","assistant","claude-code","gitagent","open-standard","openclaw","skills"],"created_at":"2026-02-27T00:15:06.359Z","updated_at":"2026-04-03T05:01:57.860Z","avatar_url":"https://github.com/open-gitagent.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"banner.png\" alt=\"gitagent banner\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n# gitagent | your repository becomes your agent\n\n[![npm version](https://img.shields.io/npm/v/@shreyaskapale/gitagent)](https://www.npmjs.com/package/@shreyaskapale/gitagent)\n[![CI](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml/badge.svg)](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Spec: v0.1.0](https://img.shields.io/badge/spec-v0.1.0-blue)](https://github.com/open-gitagent/gitagent/blob/main/spec/SPECIFICATION.md)\n[![Node \u003e= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n\nA framework-agnostic, git-native standard for defining AI agents. Clone a repo, get an agent.\n\n## Why\n\nEvery AI framework has its own structure. There's no universal, portable way to define an agent that works across Claude Code, OpenAI, LangChain, CrewAI, and AutoGen. **gitagent** fixes that.\n\n- **Git-native** — Version control, branching, diffing, and collaboration built in\n- **Framework-agnostic** — Export to any framework with adapters\n- **Compliance-ready** — First-class support for FINRA, Federal Reserve, SEC, and segregation of duties\n- **Composable** — Agents can extend, depend on, and delegate to other agents\n\n## The Standard\n\nYour repository becomes your agent. Drop these files into any git repo and it becomes a portable, framework-agnostic agent definition — everything else (CLI, adapters, patterns) builds on top of it.\n\n```\nmy-agent/\n│\n│   # ── Core Identity (required) ──────────────────────────\n├── agent.yaml              # Manifest — name, version, model, skills, tools, compliance\n├── SOUL.md                 # Identity, personality, communication style, values\n│\n│   # ── Behavior \u0026 Rules ──────────────────────────────────\n├── RULES.md                # Hard constraints, must-always/must-never, safety boundaries\n├── DUTIES.md               # Segregation of duties policy and role boundaries\n├── AGENTS.md               # Framework-agnostic fallback instructions\n│\n│   # ── Capabilities ──────────────────────────────────────\n├── skills/                 # Reusable capability modules (SKILL.md + scripts)\n│   └── code-review/\n│       ├── SKILL.md\n│       └── review.sh\n├── tools/                  # MCP-compatible tool definitions (YAML schemas)\n├── workflows/              # Multi-step procedures/playbooks\n│\n│   # ── Knowledge \u0026 Memory ────────────────────────────────\n├── knowledge/              # Reference documents the agent can consult\n├── memory/                 # Persistent cross-session memory\n│   └── runtime/            # Live agent state (dailylog.md, context.md)\n│\n│   # ── Lifecycle \u0026 Ops ───────────────────────────────────\n├── hooks/                  # Lifecycle event handlers (bootstrap.md, teardown.md)\n├── config/                 # Environment-specific overrides\n├── compliance/             # Regulatory compliance artifacts\n│\n│   # ── Composition ───────────────────────────────────────\n├── agents/                 # Sub-agent definitions (recursive structure)\n│   └── fact-checker/\n│       ├── agent.yaml\n│       ├── SOUL.md\n│       └── DUTIES.md       # This agent's role, permissions, boundaries\n├── examples/               # Calibration interactions (few-shot)\n│\n│   # ── Runtime ───────────────────────────────────────────\n└── .gitagent/              # Runtime state (gitignored)\n```\n\nOnly two files are required: **`agent.yaml`** (the manifest) and **`SOUL.md`** (the identity). Everything else is optional — add what you need, ignore the rest.\n\n## Patterns\n\nThese are the architectural patterns that emerge when you define agents as git-native file systems.\n\n### Human-in-the-Loop for RL Agents\nWhen an agent learns a new skill or writes to memory, it opens a branch + PR for human review before merging.\n\n\u003cimg src=\"patterns/human-in-the-loop.png\" alt=\"Human-in-the-Loop\" width=\"600\" /\u003e\n\n### Segregation of Duties (SOD)\nNo single agent should control a critical process end-to-end. Define roles (`maker`, `checker`, `executor`, `auditor`), a conflict matrix (which roles can't be the same agent), and handoff workflows — all in `agent.yaml` + `DUTIES.md`. The validator catches violations before deployment.\n\n```yaml\ncompliance:\n  segregation_of_duties:\n    roles:\n      - id: maker\n        description: Creates proposals\n        permissions: [create, submit]\n      - id: checker\n        description: Reviews and approves\n        permissions: [review, approve, reject]\n    conflicts:\n      - [maker, checker]         # maker cannot approve own work\n    assignments:\n      loan-originator: [maker]\n      credit-reviewer: [checker]\n    handoffs:\n      - action: credit_decision\n        required_roles: [maker, checker]\n        approval_required: true\n    enforcement: strict\n```\n\n### Live Agent Memory\nThe `memory/` folder holds a `runtime/` subfolder where agents write live knowledge — `dailylog.md`, `key-decisions.md`, and `context.md` — persisting state across sessions.\n\n\u003cimg src=\"patterns/live-agent-memory.png\" alt=\"Live Agent Memory\" width=\"600\" /\u003e\n\n### Agent Versioning\nEvery change to your agent is a git commit. Roll back broken prompts, revert bad skills, and explore past versions — full undo history for your agent.\n\n\u003cimg src=\"patterns/agent-versioning.png\" alt=\"Agent Versioning\" width=\"600\" /\u003e\n\n### Shared Context \u0026 Skills via Monorepo\nRoot-level `context.md`, `skills/`, `tools/` are automatically shared across every agent in the monorepo. No duplication, one source of truth.\n\n\u003cimg src=\"patterns/shared-context.png\" alt=\"Shared Context\" width=\"600\" /\u003e\n\n### Branch-based Deployment\nUse git branches (`dev` → `staging` → `main`) to promote agent changes through environments, just like shipping software.\n\n\u003cimg src=\"patterns/branch-deployment.png\" alt=\"Branch-based Deployment\" width=\"600\" /\u003e\n\n### Knowledge Tree\nThe `knowledge/` folder stores entity relationships as a hierarchical tree with embeddings, letting agents reason over structured data at runtime.\n\n\u003cimg src=\"patterns/knowledge-tree.png\" alt=\"Knowledge Tree\" width=\"600\" /\u003e\n\n### Agent Forking \u0026 Remixing\nFork any public agent repo, customize its `SOUL.md`, add your own skills, and PR improvements back upstream — open-source collaboration for AI agents.\n\n\u003cimg src=\"patterns/agent-forking.png\" alt=\"Agent Forking \u0026 Remixing\" width=\"600\" /\u003e\n\n### CI/CD for Agents\nRun `gitagent validate` on every push via GitHub Actions. Test agent behavior in CI, block bad merges, and auto-deploy — treat agent quality like code quality.\n\n\u003cimg src=\"patterns/ci-cd-agents.png\" alt=\"CI/CD for Agents\" width=\"600\" /\u003e\n\n### Agent Diff \u0026 Audit Trail\n`git diff` shows exactly what changed between agent versions. `git blame` traces every line to who wrote it and when — full traceability out of the box.\n\n\u003cimg src=\"patterns/agent-diff-audit.png\" alt=\"Agent Diff \u0026 Audit Trail\" width=\"600\" /\u003e\n\n### Tagged Releases\nTag stable agent versions like `v1.1.0`. Pin production to a tag, canary new versions on staging, and roll back instantly if something breaks.\n\n\u003cimg src=\"patterns/tagged-releases.png\" alt=\"Tagged Releases\" width=\"600\" /\u003e\n\n### Secret Management via .gitignore\nAgent tools that need API keys read from a local `.env` file — kept out of version control via `.gitignore`. Agent config is shareable, secrets stay local.\n\n\u003cimg src=\"patterns/secret-management.png\" alt=\"Secret Management\" width=\"600\" /\u003e\n\n### Agent Lifecycle with Hooks\nDefine `bootstrap.md` and `teardown.md` in the `hooks/` folder to control what an agent does on startup and before it stops.\n\n\u003cimg src=\"patterns/agent-automation-hooks.png\" alt=\"Agent Lifecycle Hooks\" width=\"600\" /\u003e\n\n### SkillsFlow\nDeterministic, multi-step workflows defined in `workflows/` as YAML. Chain `skill:`, `agent:`, and `tool:` steps with `depends_on` ordering, `${{ }}` template data flow, and per-step `prompt:` overrides. Every run follows the same path — no LLM discretion on execution order.\n\n```yaml\nname: code-review-flow\ndescription: Full code review pipeline\ntriggers:\n  - pull_request\n\nsteps:\n  lint:\n    skill: static-analysis\n    inputs:\n      path: ${{ trigger.changed_files }}\n\n  review:\n    agent: code-reviewer\n    depends_on: [lint]\n    prompt: |\n      Focus on security and performance.\n      Flag any use of eval() or raw SQL.\n    inputs:\n      findings: ${{ steps.lint.outputs.issues }}\n\n  test:\n    tool: bash\n    depends_on: [lint]\n    inputs:\n      command: \"npm test -- --coverage\"\n\n  report:\n    skill: review-summary\n    depends_on: [review, test]\n    conditions:\n      - ${{ steps.review.outputs.severity != 'none' }}\n    inputs:\n      review: ${{ steps.review.outputs.comments }}\n      coverage: ${{ steps.test.outputs.report }}\n\nerror_handling:\n  on_failure: notify\n  channel: \"#eng-reviews\"\n```\n\n### Porting Framework Agents to GitAgent\n\nAgents built in frameworks like NVIDIA AIQ, LangGraph, or CrewAI have their identity split across config files, Jinja2 templates, and Python code. gitagent extracts the **identity layer** — prompts, rules, roles, tool schemas — into a portable, versionable format.\n\n\u003e **What ports cleanly:** system prompts, persona definitions, hard constraints, tool schemas, role/SOD policies, model preferences.\n\u003e\n\u003e **What stays in the framework:** runtime orchestration (state machines, graph wiring), live tool execution, memory I/O, iterative loops.\n\nThis pattern is demonstrated with [NVIDIA's AIQ Deep Researcher](https://github.com/NVIDIA-AI-Blueprints/aiq) — a 3-agent hierarchy (orchestrator → planner → researcher) that produces cited research reports. The gitagent version captures the agent's identity, rules, and SOD policy so you can:\n\n- **Fork for a new domain** — edit `SOUL.md` for legal/medical/finance research without touching Python\n- **Version prompts independently** — `git diff` when the orchestrator's style regresses\n- **Validate SOD** — `gitagent validate --compliance` ensures the orchestrator can't also be the researcher\n- **Export to other runtimes** — same identity on Claude Code, OpenAI, or as a raw system prompt\n\n```\nexamples/nvidia-deep-researcher/\n├── agent.yaml                  # Manifest + SOD policy\n├── SOUL.md                     # Orchestrator identity (from orchestrator.j2)\n├── RULES.md                    # Citation rules, report constraints\n├── DUTIES.md                   # Role separation: orchestrator ↔ planner ↔ researcher\n├── agents/planner/             # Planner sub-agent (from planner.j2)\n├── agents/researcher/          # Researcher sub-agent (from researcher.j2)\n├── skills/{web,paper,knowledge}-search/\n├── tools/*.yaml                # MCP-compatible tool schemas\n└── config/                     # Model assignments per environment\n```\n\nSee [`examples/nvidia-deep-researcher/`](examples/nvidia-deep-researcher/) for the full working example.\n\n## Quick Start\n\n```bash\n# Install\nnpm i @open-gitagent/gitagent\n\n# Create a new agent\ngitagent init --template standard\n\n# Validate\ngitagent validate\n\n# View agent info\ngitagent info\n\n# Export to system prompt\ngitagent export --format system-prompt\n```\n\n## agent.yaml\n\nThe only file with a strict schema. Minimal example:\n\n```yaml\nspec_version: \"0.1.0\"\nname: my-agent\nversion: 0.1.0\ndescription: A helpful assistant agent\n```\n\nFull example with compliance:\n\n```yaml\nspec_version: \"0.1.0\"\nname: compliance-analyst\nversion: 1.0.0\ndescription: Financial compliance analysis agent\nmodel:\n  preferred: claude-opus-4-6\ncompliance:\n  risk_tier: high\n  frameworks: [finra, federal_reserve, sec]\n  supervision:\n    human_in_the_loop: always\n    kill_switch: true\n  recordkeeping:\n    audit_logging: true\n    retention_period: 7y\n    immutable: true\n  model_risk:\n    validation_cadence: quarterly\n    ongoing_monitoring: true\n  segregation_of_duties:\n    roles:\n      - id: analyst\n        permissions: [create, submit]\n      - id: reviewer\n        permissions: [review, approve, reject]\n    conflicts:\n      - [analyst, reviewer]\n    assignments:\n      compliance-analyst: [analyst]\n      fact-checker: [reviewer]\n    enforcement: strict\n```\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `gitagent init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`) |\n| `gitagent validate [--compliance]` | Validate against spec and regulatory requirements |\n| `gitagent info` | Display agent summary |\n| `gitagent export --format \u003cfmt\u003e` | Export to other formats (see adapters below) |\n| `gitagent import --from \u003cfmt\u003e \u003cpath\u003e` | Import (`claude`, `cursor`, `crewai`, `opencode`) |\n| `gitagent run \u003csource\u003e --adapter \u003ca\u003e` | Run an agent from a git repo or local directory |\n| `gitagent install` | Resolve and install git-based dependencies |\n| `gitagent audit` | Generate compliance audit report |\n| `gitagent skills \u003ccmd\u003e` | Manage skills (`search`, `install`, `list`, `info`) |\n| `gitagent lyzr \u003ccmd\u003e` | Manage Lyzr agents (`create`, `update`, `info`, `run`) |\n\n## Compliance\n\ngitagent has first-class support for financial regulatory compliance:\n\n### FINRA\n- **Rule 3110** — Supervision: human-in-the-loop, escalation triggers, kill switch\n- **Rule 4511** — Recordkeeping: immutable audit logs, retention periods, SEC 17a-4 compliance\n- **Rule 2210** — Communications: fair/balanced enforcement, no misleading statements\n- **Reg Notice 24-09** — Existing rules apply to GenAI/LLMs\n\n### Federal Reserve\n- **SR 11-7** — Model Risk Management: validation cadence, ongoing monitoring, outcomes analysis\n- **SR 23-4** — Third-Party Risk: vendor due diligence, SOC reports, subcontractor assessment\n\n### SEC / CFPB\n- **Reg S-P** — Customer privacy, PII handling\n- **CFPB Circular 2022-03** — Explainable adverse action, Less Discriminatory Alternative search\n\n### Segregation of Duties\n- **Roles \u0026 Permissions** — Define maker, checker, executor, auditor roles with controlled permissions\n- **Conflict Matrix** — Declare which role pairs cannot be held by the same agent\n- **Handoff Workflows** — Require multi-agent participation for critical actions (credit decisions, regulatory filings)\n- **Isolation** — Full state and credential segregation between roles\n- **DUTIES.md** — Root-level policy + per-agent role declarations\n- **Enforcement** — Strict (blocks deployment) or advisory (warnings only)\n\nInspired by [Salient AI](https://www.trysalient.com/)'s purpose-built agent architecture and the [FINOS AI Governance Framework](https://air-governance-framework.finos.org/mitigations/mi-22_multi-agent-isolation-and-segmentation.html).\n\nRun `gitagent audit` for a full compliance checklist against your agent configuration.\n\n## Adapters\n\nAdapters are used by both `export` and `run`. Available adapters:\n\n| Adapter | Description |\n|---------|-------------|\n| `system-prompt` | Concatenated system prompt (works with any LLM) |\n| `claude-code` | Claude Code compatible CLAUDE.md |\n| `openai` | OpenAI Agents SDK Python code |\n| `crewai` | CrewAI YAML configuration |\n| `lyzr` | Lyzr Studio agent |\n| `github` | GitHub Actions agent |\n| `git` | Git-native execution (run only) |\n| `opencode` | OpenCode instructions + config |\n| `gemini` | Google Gemini CLI (GEMINI.md + settings.json) |\n| `openclaw` | OpenClaw format |\n| `nanobot` | Nanobot format |\n| `cursor` | Cursor `.cursor/rules/*.mdc` files |\n\n```bash\n# Export to system prompt\ngitagent export --format system-prompt\n\n# Run an agent directly\ngitagent run ./my-agent --adapter lyzr\n```\n\n## Inheritance \u0026 Composition\n\n```yaml\n# Extend a parent agent\nextends: https://github.com/org/base-agent.git\n\n# Compose with dependencies\ndependencies:\n  - name: fact-checker\n    source: https://github.com/org/fact-checker.git\n    version: ^1.0.0\n    mount: agents/fact-checker\n```\n\n## Examples\n\nSee the `examples/` directory:\n\n- **`examples/minimal/`** — 2-file hello world (agent.yaml + SOUL.md)\n- **`examples/standard/`** — Code review agent with skills, tools, and rules\n- **`examples/full/`** — Production compliance agent with all directories, hooks, workflows, sub-agents, SOD with DUTIES.md, and regulatory artifacts\n- **`examples/gitagent-helper/`** — Helper agent that assists with creating gitagent definitions\n- **`examples/lyzr-agent/`** — Example Lyzr Studio integration\n\n## Specification\n\nFull specification at [`spec/SPECIFICATION.md`](spec/SPECIFICATION.md).\n\nJSON Schemas for validation at `spec/schemas/`.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=open-gitagent/gitagent\u0026type=Date)](https://star-history.com/#open-gitagent/gitagent\u0026Date)\n\n## Built with gitagent?\n\nIf you've built an agent using gitagent, we'd love to hear about it! [Open a discussion](https://github.com/open-gitagent/gitagent/discussions) or add a `gitagent` topic to your repo.\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/shreyaskapale"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fgitagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-gitagent%2Fgitagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fgitagent/lists"}