open-gitagent / gitclaw

Gitclaw A universal git-native multimodal always learning AI Agent (TinyHuman) Your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files. Install • Quick Start • SDK • Architecture • Tools • Hooks • Skills --- Why Gitclaw? Most agent frameworks treat configuration as code scattered across your application. Gitclaw flips this — **your agent IS a git repository**: • ** ** — model, tools, runtime config • ** ** — personality and identity • ** ** — behavioral constraints • ** ** — git-committed memory with full history • ** ** — declarative YAML tool definitions • ** ** — composable skill modules • ** ** — lifecycle hooks (script or programmatic) Fork an agent. Branch a personality. 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: 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 > **Requirements:** Node.js 18+, npm, git Or install manually: Quick Start **Run your first agent in one line:** That's it. Gitclaw auto-scaffolds everything on first run — , , — 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: Resume an existing session: Token can come from env instead of : CLI Options | Flag | Short | Description | |---|---|---| | | | Agent directory (default: cwd) | | | | GitHub repo URL to clone and work on | | | | GitHub PAT (or set / ) | | | | Resume an existing session branch | | | | Override model (e.g. ) | | | | Run in sandbox VM | | | | Single-shot prompt (skip REPL) | | | | Environment config | SDK 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. Returns an that streams agent events. Define custom tools the agent can call: Hooks Programmatic lifecycle hooks for gating, logging, and control: QueryOptions Reference | Option | Type | Description | |---|---|---| | | | User prompt or multi-turn stream | | | | Agent directory (default: ) | | | | | | | | Environment config ( ) | | | | Override discovered system prompt | | | | Append to discovered system prompt | | | | Additional tools | | | | Skip cli/read/write/memory | | | | Tool name allowlist | | | | Tool name denylist | | | | Clone a GitHub repo and work on a session branch | | | | Run in sandbox VM (mutually exclusive with ) | | | | Programmatic lifecycle hooks | | | | Max agent turns | | | | Cancellation signal | | | | , , , | Message Types | Type | Description | Key Fields | |---|---|---| | | Streaming text/thinking chunk | , | | | Complete LLM response | , , , | | | Tool invocation | , , | | | Tool output | , , | | | Lifecycle events | , , | | | User message (multi-turn) | | Architecture Agent Manifest ( ) Tools Built-in Tools | Tool | Description | |---|---| | | Execute shell commands | | | Read files with pagination | | | Write/create files | | | Load/save git-committed memory | Declarative Tools Define tools as YAML in : The script receives args as JSON on stdin and returns output on stdout. Hooks Script-based hooks in : Hook scripts receive context as JSON on stdin and return: Skills Skills are composable instruction modules in : Invoke via CLI: Multi-Model Support Gitclaw works with any LLM provider supported by pi-ai: Supported providers: , , , , , , and more. Inheritance & Composition Agents can extend base agents: Compliance & Audit Built-in compliance validation and audit logging: Audit logs are written to with full tool invocation traces. Contributing Contributions are welcome! Please see CONTRIBUTING.md for guidelines. License This project is licensed under the MIT License.