{"id":46700187,"url":"https://github.com/open-gitagent/gitclaw","last_synced_at":"2026-03-15T03:02:01.929Z","repository":{"id":342100241,"uuid":"1172540122","full_name":"open-gitagent/gitclaw","owner":"open-gitagent","description":"A universal git-native AI agent framework. Your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files.","archived":false,"fork":false,"pushed_at":"2026-03-10T09:12:37.000Z","size":3294,"stargazers_count":75,"open_issues_count":3,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T12:59:45.130Z","etag":null,"topics":["ai-agents","anthropic","assistant","llm","openclaw","personal"],"latest_commit_sha":null,"homepage":"","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":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2026-03-04T12:30:03.000Z","updated_at":"2026-03-10T12:54:33.000Z","dependencies_parsed_at":"2026-03-11T08:00:41.092Z","dependency_job_id":null,"html_url":"https://github.com/open-gitagent/gitclaw","commit_stats":null,"previous_names":["open-gitagent/gitclaw"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/open-gitagent/gitclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-gitagent","download_url":"https://codeload.github.com/open-gitagent/gitclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2Fgitclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30375452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"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":["ai-agents","anthropic","assistant","llm","openclaw","personal"],"created_at":"2026-03-09T06:34:35.260Z","updated_at":"2026-03-15T03:02:01.914Z","avatar_url":"https://github.com/open-gitagent.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./gitclaw-logo.png\" alt=\"GitClaw Logo\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/gitclaw?style=flat-square\u0026color=blue\" alt=\"npm version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square\" alt=\"node version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/open-gitagent/gitclaw?style=flat-square\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"typescript\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eGitclaw\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA universal git-native multimodal always learning AI Agent (TinyHuman)\u003c/strong\u003e\u003cbr/\u003e\n  Your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#one-command-install\"\u003eInstall\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#sdk\"\u003eSDK\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#tools\"\u003eTools\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#hooks\"\u003eHooks\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#skills\"\u003eSkills\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why Gitclaw?\n\nMost agent frameworks treat configuration as code scattered across your application. Gitclaw flips this — **your agent IS a git repository**:\n\n- **`agent.yaml`** — model, tools, runtime config\n- **`SOUL.md`** — personality and identity\n- **`RULES.md`** — behavioral constraints\n- **`memory/`** — git-committed memory with full history\n- **`tools/`** — declarative YAML tool definitions\n- **`skills/`** — composable skill modules\n- **`hooks/`** — lifecycle hooks (script or programmatic)\n\nFork an agent. Branch a personality. `git log` your agent's memory. Diff its rules. This is **agents as repos**.\n\n## One-Command Install\n\nCopy, paste, run. That's it — no cloning, no manual setup. The installer handles everything:\n\n```bash\nbash \u003c(curl -fsSL \"https://raw.githubusercontent.com/open-gitagent/gitclaw/main/install.sh?$(date +%s)\")\n```\n\nThis will:\n- Install gitclaw globally via npm\n- Walk you through API key setup (Quick or Advanced mode)\n- Launch the voice UI in your browser at `http://localhost:3333`\n\n\u003e **Requirements:** Node.js 18+, npm, git\n\n### Or install manually:\n\n```bash\nnpm install -g gitclaw\n```\n\n## Quick Start\n\n**Run your first agent in one line:**\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\ngitclaw --dir ~/my-project \"Explain this project and suggest improvements\"\n```\n\nThat's it. Gitclaw auto-scaffolds everything on first run — `agent.yaml`, `SOUL.md`, `memory/` — and drops you into the agent.\n\n### Local Repo Mode\n\nClone a GitHub repo, run an agent on it, auto-commit and push to a session branch:\n\n```bash\ngitclaw --repo https://github.com/org/repo --pat ghp_xxx \"Fix the login bug\"\n```\n\nResume an existing session:\n\n```bash\ngitclaw --repo https://github.com/org/repo --pat ghp_xxx --session gitclaw/session-a1b2c3d4 \"Continue\"\n```\n\nToken can come from env instead of `--pat`:\n\n```bash\nexport GITHUB_TOKEN=ghp_xxx\ngitclaw --repo https://github.com/org/repo \"Add unit tests\"\n```\n\n### CLI Options\n\n| Flag | Short | Description |\n|---|---|---|\n| `--dir \u003cpath\u003e` | `-d` | Agent directory (default: cwd) |\n| `--repo \u003curl\u003e` | `-r` | GitHub repo URL to clone and work on |\n| `--pat \u003ctoken\u003e` | | GitHub PAT (or set `GITHUB_TOKEN` / `GIT_TOKEN`) |\n| `--session \u003cbranch\u003e` | | Resume an existing session branch |\n| `--model \u003cprovider:model\u003e` | `-m` | Override model (e.g. `anthropic:claude-sonnet-4-5-20250929`) |\n| `--sandbox` | `-s` | Run in sandbox VM |\n| `--prompt \u003ctext\u003e` | `-p` | Single-shot prompt (skip REPL) |\n| `--env \u003cname\u003e` | `-e` | Environment config |\n\n### SDK\n\n```bash\nnpm install gitclaw\n```\n\n```typescript\nimport { query } from \"gitclaw\";\n\n// Simple query\nfor await (const msg of query({\n  prompt: \"List all TypeScript files and summarize them\",\n  dir: \"./my-agent\",\n  model: \"openai:gpt-4o-mini\",\n})) {\n  if (msg.type === \"delta\") process.stdout.write(msg.content);\n  if (msg.type === \"assistant\") console.log(\"\\n\\nDone.\");\n}\n\n// Local repo mode via SDK\nfor await (const msg of query({\n  prompt: \"Fix the login bug\",\n  model: \"openai:gpt-4o-mini\",\n  repo: {\n    url: \"https://github.com/org/repo\",\n    token: process.env.GITHUB_TOKEN!,\n  },\n})) {\n  if (msg.type === \"delta\") process.stdout.write(msg.content);\n}\n```\n\n## SDK\n\nThe SDK provides a programmatic interface to Gitclaw agents. It mirrors the [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk) pattern but runs **in-process** — no subprocesses, no IPC.\n\n### `query(options): Query`\n\nReturns an `AsyncGenerator\u003cGCMessage\u003e` that streams agent events.\n\n```typescript\nimport { query } from \"gitclaw\";\n\nfor await (const msg of query({\n  prompt: \"Refactor the auth module\",\n  dir: \"/path/to/agent\",\n  model: \"anthropic:claude-sonnet-4-5-20250929\",\n})) {\n  switch (msg.type) {\n    case \"delta\":       // streaming text chunk\n      process.stdout.write(msg.content);\n      break;\n    case \"assistant\":   // complete response\n      console.log(`\\nTokens: ${msg.usage?.totalTokens}`);\n      break;\n    case \"tool_use\":    // tool invocation\n      console.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`);\n      break;\n    case \"tool_result\": // tool output\n      console.log(`Result: ${msg.content}`);\n      break;\n    case \"system\":      // lifecycle events \u0026 errors\n      console.log(`[${msg.subtype}] ${msg.content}`);\n      break;\n  }\n}\n```\n\n### `tool(name, description, schema, handler): GCToolDefinition`\n\nDefine custom tools the agent can call:\n\n```typescript\nimport { query, tool } from \"gitclaw\";\n\nconst search = tool(\n  \"search_docs\",\n  \"Search the documentation\",\n  {\n    properties: {\n      query: { type: \"string\", description: \"Search query\" },\n      limit: { type: \"number\", description: \"Max results\" },\n    },\n    required: [\"query\"],\n  },\n  async (args) =\u003e {\n    const results = await mySearchEngine(args.query, args.limit ?? 10);\n    return { text: JSON.stringify(results), details: { count: results.length } };\n  },\n);\n\nfor await (const msg of query({\n  prompt: \"Find docs about authentication\",\n  tools: [search],\n})) {\n  // agent can now call search_docs\n}\n```\n\n### Hooks\n\nProgrammatic lifecycle hooks for gating, logging, and control:\n\n```typescript\nfor await (const msg of query({\n  prompt: \"Deploy the service\",\n  hooks: {\n    preToolUse: async (ctx) =\u003e {\n      // Block dangerous operations\n      if (ctx.toolName === \"cli\" \u0026\u0026 ctx.args.command?.includes(\"rm -rf\"))\n        return { action: \"block\", reason: \"Destructive command blocked\" };\n\n      // Modify arguments\n      if (ctx.toolName === \"write\" \u0026\u0026 !ctx.args.path.startsWith(\"/safe/\"))\n        return { action: \"modify\", args: { ...ctx.args, path: `/safe/${ctx.args.path}` } };\n\n      return { action: \"allow\" };\n    },\n    onError: async (ctx) =\u003e {\n      console.error(`Agent error: ${ctx.error}`);\n    },\n  },\n})) {\n  // ...\n}\n```\n\n### QueryOptions Reference\n\n| Option | Type | Description |\n|---|---|---|\n| `prompt` | `string \\| AsyncIterable` | User prompt or multi-turn stream |\n| `dir` | `string` | Agent directory (default: `cwd`) |\n| `model` | `string` | `\"provider:model-id\"` |\n| `env` | `string` | Environment config (`config/\u003cenv\u003e.yaml`) |\n| `systemPrompt` | `string` | Override discovered system prompt |\n| `systemPromptSuffix` | `string` | Append to discovered system prompt |\n| `tools` | `GCToolDefinition[]` | Additional tools |\n| `replaceBuiltinTools` | `boolean` | Skip cli/read/write/memory |\n| `allowedTools` | `string[]` | Tool name allowlist |\n| `disallowedTools` | `string[]` | Tool name denylist |\n| `repo` | `LocalRepoOptions` | Clone a GitHub repo and work on a session branch |\n| `sandbox` | `SandboxOptions \\| boolean` | Run in sandbox VM (mutually exclusive with `repo`) |\n| `hooks` | `GCHooks` | Programmatic lifecycle hooks |\n| `maxTurns` | `number` | Max agent turns |\n| `abortController` | `AbortController` | Cancellation signal |\n| `constraints` | `object` | `temperature`, `maxTokens`, `topP`, `topK` |\n\n### Message Types\n\n| Type | Description | Key Fields |\n|---|---|---|\n| `delta` | Streaming text/thinking chunk | `deltaType`, `content` |\n| `assistant` | Complete LLM response | `content`, `model`, `usage`, `stopReason` |\n| `tool_use` | Tool invocation | `toolName`, `args`, `toolCallId` |\n| `tool_result` | Tool output | `content`, `isError`, `toolCallId` |\n| `system` | Lifecycle events | `subtype`, `content`, `metadata` |\n| `user` | User message (multi-turn) | `content` |\n\n## Architecture\n\n```\nmy-agent/\n├── agent.yaml          # Model, tools, runtime config\n├── SOUL.md             # Agent identity \u0026 personality\n├── RULES.md            # Behavioral rules \u0026 constraints\n├── DUTIES.md           # Role-specific responsibilities\n├── memory/\n│   └── MEMORY.md       # Git-committed agent memory\n├── tools/\n│   └── *.yaml          # Declarative tool definitions\n├── skills/\n│   └── \u003cname\u003e/\n│       ├── SKILL.md    # Skill instructions (YAML frontmatter)\n│       └── scripts/    # Skill scripts\n├── workflows/\n│   └── *.yaml|*.md     # Multi-step workflow definitions\n├── agents/\n│   └── \u003cname\u003e/         # Sub-agent definitions\n├── hooks/\n│   └── hooks.yaml      # Lifecycle hook scripts\n├── knowledge/\n│   └── index.yaml      # Knowledge base entries\n├── config/\n│   ├── default.yaml    # Default environment config\n│   └── \u003cenv\u003e.yaml      # Environment overrides\n├── examples/\n│   └── *.md            # Few-shot examples\n└── compliance/\n    └── *.yaml          # Compliance \u0026 audit config\n```\n\n### Agent Manifest (`agent.yaml`)\n\n```yaml\nspec_version: \"0.1.0\"\nname: my-agent\nversion: 1.0.0\ndescription: An agent that does things\n\nmodel:\n  preferred: \"anthropic:claude-sonnet-4-5-20250929\"\n  fallback: [\"openai:gpt-4o\"]\n  constraints:\n    temperature: 0.7\n    max_tokens: 4096\n\ntools: [cli, read, write, memory]\n\nruntime:\n  max_turns: 50\n  timeout: 120\n\n# Optional\nextends: \"https://github.com/org/base-agent.git\"\nskills: [code-review, deploy]\ndelegation:\n  mode: auto\ncompliance:\n  risk_level: medium\n  human_in_the_loop: true\n```\n\n## Tools\n\n### Built-in Tools\n\n| Tool | Description |\n|---|---|\n| `cli` | Execute shell commands |\n| `read` | Read files with pagination |\n| `write` | Write/create files |\n| `memory` | Load/save git-committed memory |\n\n### Declarative Tools\n\nDefine tools as YAML in `tools/`:\n\n```yaml\n# tools/search.yaml\nname: search\ndescription: Search the codebase\ninput_schema:\n  properties:\n    query:\n      type: string\n      description: Search query\n    path:\n      type: string\n      description: Directory to search\n  required: [query]\nimplementation:\n  script: search.sh\n  runtime: sh\n```\n\nThe script receives args as JSON on stdin and returns output on stdout.\n\n## Hooks\n\nScript-based hooks in `hooks/hooks.yaml`:\n\n```yaml\nhooks:\n  on_session_start:\n    - script: validate-env.sh\n      description: Check environment is ready\n  pre_tool_use:\n    - script: audit-tools.sh\n      description: Log and gate tool usage\n  post_response:\n    - script: notify.sh\n  on_error:\n    - script: alert.sh\n```\n\nHook scripts receive context as JSON on stdin and return:\n\n```json\n{ \"action\": \"allow\" }\n{ \"action\": \"block\", \"reason\": \"Not permitted\" }\n{ \"action\": \"modify\", \"args\": { \"modified\": \"args\" } }\n```\n\n## Skills\n\nSkills are composable instruction modules in `skills/\u003cname\u003e/`:\n\n```\nskills/\n  code-review/\n    SKILL.md\n    scripts/\n      lint.sh\n```\n\n```markdown\n---\nname: code-review\ndescription: Review code for quality and security\n---\n\n# Code Review\n\nWhen reviewing code:\n1. Check for security vulnerabilities\n2. Verify error handling\n3. Run the lint script for style checks\n```\n\nInvoke via CLI: `/skill:code-review Review the auth module`\n\n## Multi-Model Support\n\nGitclaw works with any LLM provider supported by [pi-ai](https://github.com/nicepkg/pi-ai):\n\n```yaml\n# agent.yaml\nmodel:\n  preferred: \"anthropic:claude-sonnet-4-5-20250929\"\n  fallback:\n    - \"openai:gpt-4o\"\n    - \"google:gemini-2.0-flash\"\n```\n\nSupported providers: `anthropic`, `openai`, `google`, `xai`, `groq`, `mistral`, and more.\n\n## Inheritance \u0026 Composition\n\nAgents can extend base agents:\n\n```yaml\n# agent.yaml\nextends: \"https://github.com/org/base-agent.git\"\n\n# Dependencies\ndependencies:\n  - name: shared-tools\n    source: \"https://github.com/org/shared-tools.git\"\n    version: main\n    mount: tools\n\n# Sub-agents\ndelegation:\n  mode: auto\n```\n\n## Compliance \u0026 Audit\n\nBuilt-in compliance validation and audit logging:\n\n```yaml\n# agent.yaml\ncompliance:\n  risk_level: high\n  human_in_the_loop: true\n  data_classification: confidential\n  regulatory_frameworks: [SOC2, GDPR]\n  recordkeeping:\n    audit_logging: true\n    retention_days: 90\n```\n\nAudit logs are written to `.gitagent/audit.jsonl` with full tool invocation traces.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fgitclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-gitagent%2Fgitclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fgitclaw/lists"}