### Getting Started with GitAgent

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Installation, initialization, validation, and execution commands for local agent development.

```bash
npm install -g @shreyaskapale/gitagent
    
# Scaffold an agent
gitagent init --template standard
    
# Validate it
gitagent validate
    
# Export to your framework
gitagent export --format claude-code
    
# Run it
gitagent run . -a claude
```

--------------------------------

### Clone and Run gitagent Landing Page

Source: https://github.com/open-gitagent/landing/blob/main/README.md

Clone the repository, install dependencies, and start the development server for the gitagent landing page. Requires Node.js and npm.

```sh
git clone https://github.com/open-gitagent/landing.git
cd landing
npm i
npm run dev
```

--------------------------------

### Install and Initialize GitAgent CLI

Source: https://context7.com/open-gitagent/landing/llms.txt

Install the GitAgent CLI globally using npm. Then, initialize a new agent repository using different templates like minimal, standard, or full.

```bash
npm install -g gitagent
```

```bash
gitagent init --template minimal    # 2 files: agent.yaml + SOUL.md
gitagent init --template standard   # skills + tools directories
gitagent init --template full       # compliance + hooks + memory + skillflows
```

--------------------------------

### Example GitAgent Project Structure

Source: https://context7.com/open-gitagent/landing/llms.txt

This illustrates the typical file and directory structure for a standard GitAgent repository, including configuration, identity, skills, tools, and more.

```bash
# Example output structure (standard template):
# my-agent/
# 	├── agent.yaml        # Core configuration
# 	├── SOUL.md           # Agent identity and personality
# 	├── RULES.md          # Behavioral rules
# 	├── AGENTS.md         # Sub-agent definitions
# 	├── INSTRUCTIONS.md   # Task instructions
# 	├── scheduler.yml     # Scheduled tasks
# 	├── skills/           # Capability modules
# 	│   └── code-review/
# 	│       └── SKILL.md
# 	├── tools/            # Tool definitions
# 	│   └── search.yaml
# 	├── knowledge/        # Knowledge base
# 	│   └── index.yaml
# 	├── memory/           # Agent memory
# 	│   ├── MEMORY.md
# 	│   └── runtime/
# 	│       ├── dailylog.md
# 	│       ├── key-decisions.md
# 	│       └── context.md
# 	├── hooks/            # Lifecycle hooks
# 	│   ├── hooks.yaml
# 	│   ├── bootstrap.md
# 	│   └── teardown.md
# 	├── skillflows/       # Multi-step workflows
# 	│   └── code-review-flow.yaml
# 	└── compliance/       # Governance artifacts
# 	    └── regulatory-map.yaml
```

--------------------------------

### Install GitAgent CLI

Source: https://github.com/open-gitagent/landing/blob/main/blog-12-git-native-patterns.html

Install the GitAgent command-line interface globally using npm. This command is used to manage and interact with git-native AI agents.

```bash
npm install -g @shreyaskapale/gitagent
```

--------------------------------

### GitAgent CLI Workflow

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

A typical workflow using the GitAgent CLI, including installation, scaffolding, validation, export, and running an agent.

```bash
npm install -g @shreyaskapale/gitagent

# Scaffold an agent
gitagent init --template standard

# Validate it
gitagent validate

# Export to your framework
gitagent export --format claude-code

# Run it
gitagent run . -a claude
```

--------------------------------

### Manage Agent Skills

Source: https://context7.com/open-gitagent/landing/llms.txt

Commands to search, install, list, and inspect reusable skill modules from registries.

```bash
gitagent skills search "code review"

gitagent skills install code-review --global

gitagent skills install code-review

gitagent skills list

gitagent skills info code-review
```

--------------------------------

### Monorepo Directory Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Example of a shared context and skills structure within a GitAgent monorepo.

```text
my-org-agents/
├── context.md              # Shared across all agents
├── skills/
│   └── code-review/        # Any agent can use this
├── agents/
│   ├── frontend-agent/     # Inherits root context + skills
│   └── backend-agent/      # Same shared foundation
```

--------------------------------

### Import Agent Configuration

Source: https://context7.com/open-gitagent/landing/llms.txt

Convert existing agent configurations from external frameworks into the GitAgent format.

```bash
# Import from Claude Code (CLAUDE.md)
gitagent import --from claude ./CLAUDE.md
```

--------------------------------

### Execute Agent with Framework Adapters

Source: https://context7.com/open-gitagent/landing/llms.txt

Run agents using various runtime adapters, each requiring specific environment variables or CLI tools.

```bash
# Claude Code adapter (interactive or one-shot)
# Requires: Claude Code CLI
# Features: Append system prompt, Sub-agents, Hook mapping, Permission modes
gitagent run -a claude -d ./my-agent

# OpenAI Agents SDK (one-shot)
# Requires: OPENAI_API_KEY, Python 3
# Features: Auto-generated Python code, Tool function stubs, Type mappings
gitagent run -a openai -d ./my-agent -p "Review this code"

# CrewAI adapter (one-shot)
# Requires: CrewAI CLI
# Features: YAML config export, Role/goal extraction, Sub-agent mapping
gitagent run -a crewai -d ./my-agent -p "Analyze the architecture"

# OpenClaw adapter (one-shot)
# Requires: ANTHROPIC_API_KEY, OpenClaw CLI
# Features: Auto-provision auth, Workspace generation, HITL → thinking=high
gitagent run -a openclaw -d ./my-agent -p "Help me debug"

# Nanobot adapter (interactive or one-shot)
# Requires: ANTHROPIC_API_KEY, Nanobot CLI
# Features: Auto-provision auth, Config + system prompt, Environment variables
gitagent run -a nanobot -d ./my-agent

# Lyzr Studio adapter (one-shot)
# Requires: LYZR_API_KEY
# Features: REST API deployment, Agent ID persistence, Provider auto-mapping
gitagent lyzr run -r "https://github.com/org/agent" -p "Hello"

# GitHub Models adapter (one-shot with streaming)
# Requires: GITHUB_TOKEN (models:read scope)
# Features: Model namespace mapping, Streaming responses, Multi-provider support
gitagent run -a github -d ./my-agent -p "Summarize this file"

# Git auto-detect adapter
# Detects adapter from: .gitagent_adapter file, model hints, or file patterns
gitagent run -a git -r "https://github.com/org/agent"
```

--------------------------------

### Build and Preview gitagent Landing Page

Source: https://github.com/open-gitagent/landing/blob/main/README.md

Build the production-ready version of the gitagent landing page and preview it. Requires Node.js and npm.

```sh
npm run build
npm run preview
```

--------------------------------

### Branch-based Deployment Flow

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Standard promotion path for agent changes across environments.

```text
feature/new-skill → dev → staging → main
```

--------------------------------

### Import Agent Definitions from System Prompt

Source: https://context7.com/open-gitagent/landing/llms.txt

Use this command to import agent definitions from a raw system prompt file. Provide the path to the Markdown file containing the prompt.

```bash
gitagent import --from system-prompt ./prompt.md
```

--------------------------------

### Define Multi-Step Workflows with YAML

Source: https://context7.com/open-gitagent/landing/llms.txt

Configure deterministic workflows in skillflows/ to chain skills, agents, and tools.

```yaml
# skillflows/code-review-flow.yaml
name: code-review-flow
description: Full code review pipeline
triggers:
  - pull_request

steps:
  lint:
    skill: static-analysis
    inputs:
      path: ${{ trigger.changed_files }}

  review:
    agent: code-reviewer
    depends_on: [lint]
    prompt: |
      Focus on security and performance.
      Flag any use of eval() or raw SQL.
    inputs:
      findings: ${{ steps.lint.outputs.issues }}

  test:
    tool: bash
    depends_on: [lint]
    inputs:
      command: "npm test -- --coverage"

  report:
    skill: review-summary
    depends_on: [review, test]
    conditions:
      - ${{ steps.review.outputs.severity != 'none' }}
    inputs:
      review: ${{ steps.review.outputs.comments }}
      coverage: ${{ steps.test.outputs.report }}

error_handling:
  on_failure: notify
  channel: "#eng-reviews"
```

--------------------------------

### Agent Learning Workflow via Pull Request

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Illustrates the Git workflow for an agent to propose changes to its memory. This involves creating a branch, committing changes, and opening a pull request for human review.

```bash
agent updates memory/key-decisions.md
  → git checkout -b agent/update-memory
  → git commit + push
  → gh pr create
  → human reviews and merges
```

--------------------------------

### Exporting Agent Configurations

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Commands to export agent configurations into various framework-specific formats.

```bash
gitagent export --format claude-code    # → CLAUDE.md
gitagent export --format crewai         # → crew.yaml
gitagent export --format openai         # → Python module
gitagent export --format system-prompt  # → Universal markdown
```

--------------------------------

### Display Agent Information

Source: https://context7.com/open-gitagent/landing/llms.txt

Retrieve metadata, configuration, and capability summaries for a specific agent.

```bash
# Display agent information
gitagent info
```

--------------------------------

### Export Agent to Frameworks

Source: https://context7.com/open-gitagent/landing/llms.txt

Commands to convert agent definitions into formats compatible with specific AI frameworks and runtimes.

```bash
gitagent export -f claude-code -o ./output

gitagent export -f openai -o ./output

gitagent export -f crewai -o ./output

gitagent export -f openclaw -o ./output

gitagent export -f nanobot -o ./output

gitagent export -f lyzr -o ./output

gitagent export -f github -o ./output

gitagent export -f system-prompt -o ./output
```

--------------------------------

### Run Agents from Git Repositories

Source: https://context7.com/open-gitagent/landing/llms.txt

Commands to execute agents from remote repositories or local directories using various adapters and configurations.

```bash
gitagent run -r "https://github.com/shreyas-lyzr/architect" -a claude

gitagent run -r "https://github.com/org/agent" -b develop -a claude

gitagent run -r "https://github.com/org/agent" -a openai -p "Review this PR"

gitagent run -r "https://github.com/org/agent" -a nanobot --refresh

gitagent run -r "https://github.com/org/agent" -a git

gitagent run -d ./my-agent -a claude

gitagent run -d ./my-agent -a github -p "Hello, who are you?"

gitagent lyzr run -r "https://github.com/org/agent" -p "Analyze this code"
```

--------------------------------

### GitAgent Core Configuration (agent.yaml)

Source: https://context7.com/open-gitagent/landing/llms.txt

Defines the agent's metadata, model preferences, capabilities, and runtime settings. Ensure model constraints and HITL settings are configured as needed.

```yaml
# agent.yaml - Core agent configuration
spec_version: "0.1.0"
name: code-review-agent
version: 1.0.0
description: Automated code review agent
author: gitagent-examples
license: MIT

model:
  preferred: claude-sonnet-4-5-20250929
  fallback:
    - claude-haiku-4-5-20251001
  constraints:
    temperature: 0.2
    max_tokens: 4096

skills:
  - code-review
  - static-analysis

tools:
  - lint-check
  - complexity-analysis
  - bash

runtime:
  max_turns: 20
  timeout: 120

# Optional: Human-in-the-loop configuration
hitl:
  enabled: true
  approval_required: ["deploy", "delete"]

# Optional: Compliance settings
compliance:
  risk_tier: standard
  frameworks:
    - FINRA
    - SEC
```

--------------------------------

### Import Agent Definitions from Cursor

Source: https://context7.com/open-gitagent/landing/llms.txt

Use this command to import agent definitions from Cursor rules. Ensure the path to the rules is correctly specified.

```bash
gitagent import --from cursor ./.cursorrules
```

--------------------------------

### Agent Lifecycle Hooks

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Define custom logic for agent initialization and shutdown using files in the hooks directory. This avoids complex event bus or pub/sub mechanisms.

```bash
hooks/
├── bootstrap.md    # Runs at agent startup
└── teardown.md     # Runs before shutdown
```

--------------------------------

### Agent Forking and Customization

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Commands for forking, modifying, and contributing back to existing agents.

```bash
# Fork a public agent
gh repo fork open-gitagent/code-reviewer

# Customize its identity
vim SOUL.md

# Add your own skills
cp -r my-skills/ skills/

# PR improvements back upstream
gh pr create --repo open-gitagent/code-reviewer
```

--------------------------------

### Tagging Agent Releases

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Use git tags to version your agent releases. This allows for precise pinning of production environments and facilitates canary deployments and rollbacks.

```bash
git tag -a v1.1.0 -m "Added financial analysis skill"
git push origin v1.1.0
```

--------------------------------

### Live Agent Memory Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

Directory layout for persistent agent memory using Markdown files.

```text
memory/
├── MEMORY.md          # Current working state
├── runtime/
│   ├── dailylog.md    # What happened today
│   └── context.md     # Execution context
```

--------------------------------

### Run Compliance Audit

Source: https://context7.com/open-gitagent/landing/llms.txt

Execute a compliance check against regulatory frameworks like FINRA and SEC.

```bash
# Run compliance audit
gitagent audit
```

--------------------------------

### GitAgent Project Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

This outlines the standard directory structure for a GitAgent project. Only agent.yaml and SOUL.md are mandatory.

```yaml
my-agent/
├── agent.yaml     # Manifest — name, version, model, skills
├── SOUL.md        # Identity and personality
├── RULES.md       # Hard constraints
├── AGENTS.md      # Framework-agnostic fallback (Copilot, Cursor, OpenClaw)
├── DUTIES.md      # Segregation of duties policy and role boundaries
├── skills/        # Reusable capabilities
├── tools/         # Tool definitions
├── knowledge/     # Reference documents
├── memory/        # Persistent state
├── hooks/         # Lifecycle handlers
└── workflows/     # Multi-step procedures
```

--------------------------------

### Running Agents from Remote Repositories

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Execute an agent directly from a remote git URL.

```bash
# Run any agent from a git URL
gitagent run -r "https://github.com/you/your-agent" -a claude
```

--------------------------------

### Validate Agent Configuration

Source: https://context7.com/open-gitagent/landing/llms.txt

Commands to verify agent configuration files against schema specifications and run compliance audits.

```bash
gitagent validate

gitagent validate --compliance
```

--------------------------------

### Viewing Agent History with Git Log

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Demonstrates how to view the commit history for a specific agent file like SOUL.md using `git log`. This provides a chronological record of changes to the agent's identity, rules, or skills.

```bash
git log --oneline SOUL.md
# a1b2c3d Make agent more concise in responses
# d4e5f6a Add domain expertise in financial analysis
# 7g8h9i0 Initial agent identity
```

--------------------------------

### Agent Manifest Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

A standard directory structure for agent repositories, including manifest files for identity, rules, framework-agnostic definitions, duties, skills, tools, and knowledge.

```directory
my-agent/
├── agent.yaml     # Manifest — name, version, model, skills
├── SOUL.md        # Identity and personality
├── RULES.md       # Hard constraints
├── AGENTS.md      # Framework-agnostic fallback (Copilot, Cursor, OpenClaw)
├── DUTIES.md      # Segregation of duties policy and role boundaries
├── skills/        # Reusable capabilities
├── tools/         # Tool definitions
├── knowledge/     # Reference documents
```

--------------------------------

### CI/CD Validation Workflow

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

GitHub Actions configuration to validate agent behavior on push.

```yaml
# .github/workflows/validate.yml
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @shreyaskapale/gitagent
      - run: gitagent validate
```

--------------------------------

### Knowledge Tree Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Hierarchical organization of reference documents for agent reasoning.

```text
knowledge/
├── products/
│   ├── pricing.md
│   └── features.md
├── policies/
│   └── compliance.md
└── README.md
```

--------------------------------

### Import Agent Definitions from CrewAI

Source: https://context7.com/open-gitagent/landing/llms.txt

Use this command to import agent definitions from a CrewAI configuration file. Specify the path to the CrewAI YAML file.

```bash
gitagent import --from crewai ./crew.yaml
```

--------------------------------

### Agent Memory Structure

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Shows the directory structure for agent memory, including the main working state and runtime logs. This memory is stored as markdown files, enabling Git diffing and versioning.

```bash
memory/
    ├── MEMORY.md          # Current working state
    ├── runtime/
    │   ├── dailylog.md    # What happened today
    │   └── context.md     # Execution context
```

--------------------------------

### Agent Lifecycle Git Commands

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Standard Git commands used to track agent execution states during the bootstrap, execute, checkpoint, and teardown phases.

```bash
git commit -m "Session start: begin onboarding"
git commit -m "memory: added customer escalation policy"
git commit -m "checkpoint: routine state capture"
git commit -m "teardown: session end"
git push origin runtime/2024-04-26/abc123
```

--------------------------------

### View All Git History

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

Use `git log --all --oneline` to view a concise, one-line history of all changes across all branches. This provides a tamper-evident audit trail.

```bash
git log --all --oneline
```

--------------------------------

### GitAgent Skill Definition (SKILL.md)

Source: https://context7.com/open-gitagent/landing/llms.txt

Defines a reusable capability module for specific agent tasks. Ensure metadata like name, description, and compatibility are correctly set.

```markdown
---
name: code-review
description: Thorough code reviews for quality and security
license: MIT
compatibility: ">=0.1.0"
allowed-tools: Read Edit Grep Glob Bash
metadata:
  author: "Jane Doe"
  version: "1.0.0"
  category: "developer-tools"
---

# Code Review
```

--------------------------------

### Agent Audit and History Commands

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Git commands to inspect agent changes and audit history.

```bash
# What changed in the last release?
git diff v1.0.0..v1.1.0

# Who changed the agent's rules and when?
git blame RULES.md

# Full history of every change
git log --all --oneline
```

--------------------------------

### Reference Agent Commit

Source: https://github.com/open-gitagent/landing/blob/main/blog-12-git-native-patterns.html

Identify and pin a specific agent state using a commit hash.

```text
a5f3c2d
```

--------------------------------

### Fix SQL Injection in Python

Source: https://context7.com/open-gitagent/landing/llms.txt

Demonstrates replacing a vulnerable f-string query with a parameterized query to prevent SQL injection.

```python
def get_user(id):
    return db.query(f"SELECT * FROM users WHERE id = {id}")
```

```python
def get_user(id):
    return db.query("SELECT * FROM users WHERE id = ?", [id])
```

--------------------------------

### View Agent Execution History

Source: https://github.com/open-gitagent/landing/blob/main/blog-12-git-native-patterns.md

Displays the linear commit history of a specific agent runtime branch to audit actions and state changes.

```bash
$ git log --oneline runtime/2024-04-26/abc123
f8a1b2c teardown: session end
d3e4f5a checkpoint: routine state capture
b7c8d9e memory: added customer escalation policy
a1b2c3d Session start: begin onboarding
```

--------------------------------

### Auditing Agent Changes with Git Diff and Blame

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

These git commands are used for auditing agent changes. `git diff` shows differences between versions, while `git blame` identifies who last modified each line of a file and when.

```git
# What changed in the last release?
git diff v1.0.0..v1.1.0
```

```git
# Who changed the agent's rules and when?
git blame RULES.md
```

--------------------------------

### Segregation of Duties (SOD) Configuration

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Configure Segregation of Duties policies within the agent manifest to enforce role-based access control and prevent conflicts, especially in regulated environments. This policy is enforced by the `gitagent validate --compliance` command.

```yaml
compliance:
  segregation_of_duties:
    roles:
      - id: maker
        permissions: [create, submit]
      - id: checker
        permissions: [review, approve, reject]
    conflicts:
      - [maker, checker]   # maker cannot approve own work
    handoffs:
      - action: credit_decision
        required_roles: [maker, checker]
        approval_required: true
    enforcement: strict
```

--------------------------------

### Validate Compliance Rules

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.md

Run `gitagent validate --compliance` to check for Segregation of Duties violations before deployment. This command enforces the defined policy as a version-controlled artifact.

```bash
gitagent validate --compliance
```

--------------------------------

### GitAgent Identity and Personality (SOUL.md)

Source: https://context7.com/open-gitagent/landing/llms.txt

Defines the agent's core identity, communication style, values, and domain expertise. Clearly state boundaries and escalation procedures.

```markdown
# Soul

## Core Identity
I am a code review specialist. I analyze code changes for correctness,
security vulnerabilities, performance issues, and adherence to best practices.

## Communication Style
Direct and constructive. I provide specific, actionable feedback with code
examples. I explain the "why" behind my recommendations.

## Values & Principles
- Security first — always flag vulnerabilities
- Clarity over cleverness — readable code beats clever code
- Constructive feedback — explain *why*, not just *what*
- Thoroughness — catch issues before they reach production

## Domain Expertise
- Software engineering best practices
- OWASP Top 10 security vulnerabilities
- Performance optimization patterns
- Code style and naming conventions
- Error handling and edge cases

## Boundaries
- I do not execute code directly
- I do not access external systems without explicit permission
- I escalate decisions that require human judgment
```

--------------------------------

### Ignoring Secrets with .gitignore

Source: https://github.com/open-gitagent/landing/blob/main/blog-filesystem-convergence.html

Manage secrets locally by adding sensitive files like .env to your .gitignore. This ensures API keys and other credentials are not committed to the repository.

```gitignore
# .gitignore
.env
.gitagent/
```

--------------------------------

### Rollback Agent State

Source: https://github.com/open-gitagent/landing/blob/main/blog-12-git-native-patterns.html

Revert an agent's configuration or state to a previous version using standard git commands.

```bash
git checkout HEAD~1 -- SOUL.md
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.