GitClaw: Your AI Agent Lives in a Git Repo

By Prahlad Menon 4 min read

There’s a pattern emerging in how people build serious AI agents. Not the tutorial kind — the kind that run for weeks, remember things, have consistent personalities, and don’t suddenly forget who they are after a restart.

The pattern looks like this: put everything in files. Put those files in Git.

Identity in a SOUL.md. Behavioral rules in RULES.md. Memory as committed markdown in a memory/ folder. Skills as composable modules. The entire agent as a repository with a full history you can audit, branch, and roll back.

We’ve been running this architecture ourselves for months. GitClaw just packaged it as a framework.

The Problem With How Most Agents Store State

Ask most agent frameworks where they keep memory and you’ll get one of three answers: a vector database, a JSON blob in app state, or “it doesn’t, really.”

This works for demos. It breaks down in production:

  • No history. You can’t see how an agent’s memory evolved. If it starts behaving oddly, you can’t diff its state from last week.
  • No portability. Memory is trapped in whatever database the framework uses. Moving agents between environments is painful.
  • No collaboration. If you want to build on someone else’s agent — give it different rules, extend its skills — there’s no standard mechanism. You fork the code, not the agent.

Git solves all three. History is the whole point of Git. Portability is git clone. Collaboration is git fork.

GitClaw applies this to agents.

What a GitClaw Agent Looks Like

An agent is just a directory with a specific structure:

my-agent/
├── agent.yaml        # model, tools, runtime config
├── SOUL.md           # personality and identity  
├── RULES.md          # behavioral constraints
├── memory/           # committed memory — full git history
├── tools/            # declarative YAML tool definitions
├── skills/           # composable skill modules
└── hooks/            # lifecycle hooks

That’s it. No database. No proprietary state format. Every piece of the agent is a file you can open in a text editor, commit to a repo, and push to GitHub.

The implications follow naturally:

git log memory/          # Full history of everything the agent has learned
git diff RULES.md        # See exactly how behavioral constraints changed
git branch experimental  # Try a personality variant without touching main
git revert abc1234       # Roll back to before a bad memory was committed

An agent with a regression? git bisect. Two agents you want to merge? git merge. A great agent config you want to share? Push it to GitHub and let people git clone.

Getting Started

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

On first run, GitClaw auto-scaffolds the entire structure — agent.yaml, SOUL.md, memory/ — and starts an interactive session. The agent’s memory and config are committed to git as it runs.

Working on a GitHub repo directly:

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

GitClaw clones the repo, runs the agent against it, and commits work to a session branch (gitclaw/session-a1b2c3d4). You review the branch and merge if it looks good.

Resuming a session:

gitclaw --repo https://github.com/org/repo \
  --session gitclaw/session-a1b2c3d4 \
  "Continue where we left off"

Because everything is in Git, sessions are resumable from any machine.

The SDK

For programmatic use, GitClaw exposes a streaming TypeScript SDK that mirrors the Claude Agent SDK pattern:

import { query } from "gitclaw";

for await (const msg of query({
  prompt: "Refactor the auth module",
  dir: "./my-agent",
  model: "anthropic:claude-sonnet-4-5-20250929",
})) {
  if (msg.type === "delta") process.stdout.write(msg.content);
  if (msg.type === "tool_use") console.log(`Tool: ${msg.toolName}`);
}

It supports custom tools, hooks for intercepting and blocking tool calls, model switching per-query, and multi-turn streaming.

Hooks are particularly useful for safety:

preToolUse: async (ctx) => {
  if (ctx.toolName === "cli" && ctx.args.command?.includes("rm -rf"))
    return { action: "block", reason: "Destructive command blocked" };
  return { action: "allow" };
}

Git Is Eating the AI Stack

We’ve been writing about this trend lately.

GitButler rebuilt Git’s interface for human developers — virtual branches, visual commit management, unlimited undo. AgentHub rebuilt Git’s collaboration model for agent swarms — a DAG instead of a linear history, a message board for coordination.

GitClaw completes the picture at the identity layer: the agent itself as a versioned artifact, with all the reproducibility and collaboration properties that implies.

Three different projects, three different problems, one unifying insight: Git is the right primitive for managing things that change over time and need to be shared. Code figured this out 20 years ago. Agents are figuring it out now.

The Honest Assessment

GitClaw is early. The GitHub repo is relatively new and the ecosystem around it is thin. There’s no built-in skills marketplace yet, no managed hosting, no GUI. It’s a clean architecture and a functional CLI/SDK — not a polished product.

But the core idea is sound, and more importantly, it’s proven. The git-as-agent-state pattern works. Anyone who’s built a long-running agent the right way has converged on something like this independently.

GitClaw just makes it the default.

Try It

npm install -g gitclaw
gitclaw --dir . "What's in this repo?"

Watch the memory/ folder in your git log afterward. That’s your agent remembering things, in plain text, with full history.