SkillAgentSearch skills...

Gitclaw

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.

GenerateConvertImprove

Install / Use

/learn @open-gitagent/Gitclaw
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Claude Desktop

README

<p align="center"> <img src="./gitclaw-logo.png" alt="GitClaw Logo" width="200" /> </p> <p align="center"> <img src="https://img.shields.io/npm/v/gitclaw?style=flat-square&color=blue" alt="npm version" /> <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version" /> <img src="https://img.shields.io/github/license/open-gitagent/gitclaw?style=flat-square" alt="license" /> <img src="https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript&logoColor=white" alt="typescript" /> </p> <h1 align="center">Gitclaw</h1> <p align="center"> <strong>A universal git-native multimodal always learning AI Agent (TinyHuman)</strong><br/> Your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files. </p> <p align="center"> <a href="#one-command-install">Install</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#sdk">SDK</a> &bull; <a href="#architecture">Architecture</a> &bull; <a href="#tools">Tools</a> &bull; <a href="#hooks">Hooks</a> &bull; <a href="#skills">Skills</a> &bull; <a href="#plugins">Plugins</a> </p>

Why Gitclaw?

Most agent frameworks treat configuration as code scattered across your application. Gitclaw flips this — your agent IS a git repository:

  • agent.yaml — model, tools, runtime config
  • SOUL.md — personality and identity
  • RULES.md — behavioral constraints
  • memory/ — git-committed memory with full history
  • tools/ — declarative YAML tool definitions
  • skills/ — composable skill modules
  • hooks/ — lifecycle hooks (script or programmatic)

Fork an agent. Branch a personality. git log your agent's memory. Diff its rules. This is agents as repos.

One-Command Install

Copy, paste, run. That's it — no cloning, no manual setup. The installer handles everything:

bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitclaw/main/install.sh?$(date +%s)")

This will:

  • Install gitclaw globally via npm
  • Walk you through API key setup (Quick or Advanced mode)
  • Launch the voice UI in your browser at http://localhost:3333

Requirements: Node.js 18+, npm, git

Or install manually:

npm install -g gitclaw

Quick Start

Run your first agent in one line:

export OPENAI_API_KEY="sk-..."
gitclaw --dir ~/my-project "Explain this project and suggest improvements"

That's it. Gitclaw auto-scaffolds everything on first run — agent.yaml, SOUL.md, memory/ — and drops you into the agent.

Local Repo Mode

Clone a GitHub repo, run an agent on it, auto-commit and push to a session branch:

gitclaw --repo https://github.com/org/repo --pat ghp_xxx "Fix the login bug"

Resume an existing session:

gitclaw --repo https://github.com/org/repo --pat ghp_xxx --session gitclaw/session-a1b2c3d4 "Continue"

Token can come from env instead of --pat:

export GITHUB_TOKEN=ghp_xxx
gitclaw --repo https://github.com/org/repo "Add unit tests"

CLI Options

| Flag | Short | Description | |---|---|---| | --dir <path> | -d | Agent directory (default: cwd) | | --repo <url> | -r | GitHub repo URL to clone and work on | | --pat <token> | | GitHub PAT (or set GITHUB_TOKEN / GIT_TOKEN) | | --session <branch> | | Resume an existing session branch | | --model <provider:model> | -m | Override model (e.g. anthropic:claude-sonnet-4-5-20250929) | | --sandbox | -s | Run in sandbox VM | | --prompt <text> | -p | Single-shot prompt (skip REPL) | | --env <name> | -e | Environment config |

SDK

npm install gitclaw

import { query } from "gitclaw";

// Simple query
for await (const msg of query({
  prompt: "List all TypeScript files and summarize them",
  dir: "./my-agent",
  model: "openai:gpt-4o-mini",
})) {
  if (msg.type === "delta") process.stdout.write(msg.content);
  if (msg.type === "assistant") console.log("\n\nDone.");
}

// Local repo mode via SDK
for await (const msg of query({
  prompt: "Fix the login bug",
  model: "openai:gpt-4o-mini",
  repo: {
    url: "https://github.com/org/repo",
    token: process.env.GITHUB_TOKEN!,
  },
})) {
  if (msg.type === "delta") process.stdout.write(msg.content);
}

SDK

The SDK provides a programmatic interface to Gitclaw agents. It mirrors the Claude Agent SDK pattern but runs in-process — no subprocesses, no IPC.

query(options): Query

Returns an AsyncGenerator<GCMessage> that streams agent events.

import { query } from "gitclaw";

for await (const msg of query({
  prompt: "Refactor the auth module",
  dir: "/path/to/agent",
  model: "anthropic:claude-sonnet-4-5-20250929",
})) {
  switch (msg.type) {
    case "delta":       // streaming text chunk
      process.stdout.write(msg.content);
      break;
    case "assistant":   // complete response
      console.log(`\nTokens: ${msg.usage?.totalTokens}`);
      break;
    case "tool_use":    // tool invocation
      console.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`);
      break;
    case "tool_result": // tool output
      console.log(`Result: ${msg.content}`);
      break;
    case "system":      // lifecycle events & errors
      console.log(`[${msg.subtype}] ${msg.content}`);
      break;
  }
}

tool(name, description, schema, handler): GCToolDefinition

Define custom tools the agent can call:

import { query, tool } from "gitclaw";

const search = tool(
  "search_docs",
  "Search the documentation",
  {
    properties: {
      query: { type: "string", description: "Search query" },
      limit: { type: "number", description: "Max results" },
    },
    required: ["query"],
  },
  async (args) => {
    const results = await mySearchEngine(args.query, args.limit ?? 10);
    return { text: JSON.stringify(results), details: { count: results.length } };
  },
);

for await (const msg of query({
  prompt: "Find docs about authentication",
  tools: [search],
})) {
  // agent can now call search_docs
}

Hooks

Programmatic lifecycle hooks for gating, logging, and control:

for await (const msg of query({
  prompt: "Deploy the service",
  hooks: {
    preToolUse: async (ctx) => {
      // Block dangerous operations
      if (ctx.toolName === "cli" && ctx.args.command?.includes("rm -rf"))
        return { action: "block", reason: "Destructive command blocked" };

      // Modify arguments
      if (ctx.toolName === "write" && !ctx.args.path.startsWith("/safe/"))
        return { action: "modify", args: { ...ctx.args, path: `/safe/${ctx.args.path}` } };

      return { action: "allow" };
    },
    onError: async (ctx) => {
      console.error(`Agent error: ${ctx.error}`);
    },
  },
})) {
  // ...
}

QueryOptions Reference

| Option | Type | Description | |---|---|---| | prompt | string \| AsyncIterable | User prompt or multi-turn stream | | dir | string | Agent directory (default: cwd) | | model | string | "provider:model-id" | | env | string | Environment config (config/<env>.yaml) | | systemPrompt | string | Override discovered system prompt | | systemPromptSuffix | string | Append to discovered system prompt | | tools | GCToolDefinition[] | Additional tools | | replaceBuiltinTools | boolean | Skip cli/read/write/memory | | allowedTools | string[] | Tool name allowlist | | disallowedTools | string[] | Tool name denylist | | repo | LocalRepoOptions | Clone a GitHub repo and work on a session branch | | sandbox | SandboxOptions \| boolean | Run in sandbox VM (mutually exclusive with repo) | | hooks | GCHooks | Programmatic lifecycle hooks | | maxTurns | number | Max agent turns | | abortController | AbortController | Cancellation signal | | constraints | object | temperature, maxTokens, topP, topK |

Message Types

| Type | Description | Key Fields | |---|---|---| | delta | Streaming text/thinking chunk | deltaType, content | | assistant | Complete LLM response | content, model, usage, stopReason | | tool_use | Tool invocation | toolName, args, toolCallId | | tool_result | Tool output | content, isError, toolCallId | | system | Lifecycle events | subtype, content, metadata | | user | User message (multi-turn) | content |

Architecture

my-agent/
├── agent.yaml          # Model, tools, runtime config
├── SOUL.md             # Agent identity & personality
├── RULES.md            # Behavioral rules & constraints
├── DUTIES.md           # Role-specific responsibilities
├── memory/
│   └── MEMORY.md       # Git-committed agent memory
├── tools/
│   └── *.yaml          # Declarative tool definitions
├── skills/
│   └── <name>/
│       ├── SKILL.md    # Skill instructions (YAML frontmatter)
│       └── scripts/    # Skill scripts
├── workflows/
│   └── *.yaml|*.md     # Multi-step workflow definitions
├── agents/
│   └── <name>/         # Sub-agent definitions
├── plugins/
│   └── <name>/         # Local plugins (plugin.yaml + tools/hooks/skills)
├── hooks/
│   └── hooks.yaml      # Lifecycle hook scripts
├── knowledge/
│   └── index.yaml      # Knowledge base entries
├── config/
│   ├── default.yaml    # Default environment config
│   └── <env>.yaml      # Environment overrides
├── examples/
│   └── *.md            # Few-shot examples
└── compliance/
    └── *.yaml          # Compliance & audit config

Agent Manifest (agent.yaml)

spec_version: "0.1.0"
name: my-agent
version: 1.0.0
description: An agent that does things

model:
  preferred: "anthropic:claude-sonnet-4-5-20250929"
  fallback: ["openai:gpt-4o"]
  constraints:
    temperature: 0.7
    max_tokens: 4096

tools: [cli, read, write, memory]

runtime:
  max_turns: 50
  timeout: 120

# Optional
extends: "https://gi

open-gitagent

View profile

View on GitHub
GitHub Stars192
CategoryDevelopment
Updated7h ago
Forks35
open-gitagent/gitclaw

Languages

TypeScript

Security Score

100/100

Audited on Apr 3, 2026

No findings