# Gitagent: a git-native AI agent framework where the agent is the repository

> Gitagent stores an agent's identity, rules, memory, tools and skills as versioned files inside a git repo. Here is how the layout works, how to install it, and where the design stops being the right choice.

**open-gitagent/gitagent** — 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.

- Repository: https://github.com/open-gitagent/gitagent
- Stars: 711 · Forks: 135
- Language: Rust
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/open-gitagent-gitagent

## The problem Gitagent solves: agent state that nobody can review

Most agent setups keep their interesting parts in places that do not diff well. A system prompt sits in a database row. Memory accumulates in a vector store. Tool definitions live in application code that ships on a different schedule from the prompt. When the agent starts behaving oddly, there is no single artifact to inspect, and no way to answer the question of what changed between last Tuesday and today.

Gitagent's answer is to make the agent a git repository. The README lists the pieces: agent.yaml for model and runtime configuration, SOUL.md for personality and identity, RULES.md for behavioral constraints, memory/ for committed memory with full history, tools/ for declarative YAML tool definitions, skills/ for composable modules, and hooks/ for lifecycle hooks. The repository root mirrors that claim: agent.yaml, SOUL.md, RULES.md, memory/, skills/ and rust/ are all top-level entries.

The audience is narrow and specific. This is for engineers who are comfortable with git plumbing and who want reviewable agent behavior. It is not aimed at someone who wants to configure an agent through a web form. The project's own framing is blunt about the trade-off: fork an agent, branch a personality, run git log over the agent's memory. That is a workflow for people who already live in a terminal.

## How the repository layout drives the runtime

The data flow follows the directory structure. On first run the CLI auto-scaffolds agent.yaml, SOUL.md and memory/, according to the README, which means an empty directory is a valid starting point and the agent writes its own skeleton. From then on, configuration is read from files rather than passed as flags, with flags available as overrides.

Two runtime surfaces exist. The CLI runs an agent against a local directory with --dir, or clones a remote repository with --repo and a token, works on it, and commits to a session branch. The SDK exposes the same engine in-process. The README states that the SDK mirrors the Claude Agent SDK pattern but runs in-process, with no subprocesses and no IPC. That distinction matters for embedding: an in-process generator is easier to wrap in an existing Node service than a spawned CLI.

The SDK returns an AsyncGenerator of messages, and the documented message types are delta for streaming text, assistant for a completed response with token usage, tool_use and tool_result for tool invocations, and system for lifecycle events and errors. That is a small vocabulary, and it is the whole contract for consuming an agent run programmatically.

The project is written in Rust, and the repository has a rust/ directory alongside src/. The v2.2.0 release note describes a Rust engine plus a Lyzr Edgespace desktop app. The README's install path, however, is entirely npm-based, so the practical entry point for most readers is the Node package, not the Rust tree.

## Installing Gitagent and running a first prompt

The README offers a one-command installer that pulls install.sh from the repository's main branch, installs the CLI globally through npm, walks through API key setup, and launches a voice UI in the browser at http://localhost:3333. It requires Node.js 18+, npm and git. Note the version mismatch worth checking before you commit: the README badge and installer say Node.js 18+, while package.json declares engines.node as >=20. Trust the stricter one.

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

If you would rather not pipe a remote script into bash, the README documents a manual path with two packages. The slim package carries the CLI and SDK; the voice package adds voice mode and the web UI.

```bash
npm install -g @open-gitagent/gitagent
npm install -g @open-gitagent/voice
```

The README notes that install.sh installs both by default, and that setting GITAGENT_SLIM=1 before the curl command skips voice. The stated reason for the split is supply-chain scanners: as a single bundle the package tripped scanners over a 3,800-line dist/voice/ui.html and an unused baileys dependency, and the split dropped the core tarball from roughly 180 kB to roughly 85 kB.

For a first real run, export a provider key and point the CLI at a directory. The README's example uses an OpenAI key and a one-line prompt. The agent scaffolds its files on first run and answers in the terminal.

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

If you want the agent to work on a hosted repository instead, the local repo mode clones a URL, requires a personal access token, and commits to a session branch that you can resume later. The token can come from --pat or from GITHUB_TOKEN or GIT_TOKEN in the environment.

```bash
gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the login bug"
gitagent --repo https://github.com/org/repo --pat ghp_xxx --session gitagent/session-a1b2c3d4 "Continue"
```

The session branch name in the README follows the pattern gitagent/session- followed by an identifier, which is what you pass back to --session. Model selection uses a provider:model string, with anthropic:claude-sonnet-4-5-20250929 given as the documented example.

## The SDK is the part worth embedding, and the part with the least documentation

The SDK exports query and tool. query takes a prompt, a dir, a model, and optionally a repo object with a url and token, and yields messages you switch on by type. The README shows a loop that writes delta content to stdout and prints token usage when the assistant message arrives.

```typescript
import { query } from "gitagent";

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.");
}
```

The tool helper takes a name, a description, a schema built with properties and required, and an async handler. The README's example defines a search_docs tool with a query string and a numeric limit. The schema style is the one used by @sinclair/typebox, which appears in the dependency list.

What the README does not cover is the operational side of embedding: there is no documented cancellation path for a running query, no stated behavior for a tool handler that throws, and no description of how concurrent query calls against the same agent directory interact. For a framework whose selling point is that state lives in files, the question of what two simultaneous writers do to memory/ is the one I would want answered before putting this behind a web endpoint. The README is silent on it.

## Where Gitagent is the wrong tool

The git-native model has a cost that the README does not dwell on. Every memory write is a file write inside a working tree. If your agent runs in a container with a read-only filesystem, or in a serverless function without a persistent volume, the core premise does not hold. You can still use the SDK in-process, but the memory and identity files need somewhere durable to live, and that somewhere has to be a git repository for the diff-and-revert workflow to mean anything.

The local repo mode adds a second constraint. It clones a remote repository and commits to a session branch, which means the agent needs a token with write access to that repository. The README documents --pat, GITHUB_TOKEN and GIT_TOKEN as token sources. It does not document a dry-run mode, a way to preview the diff before committing, or a rollback command. If you want to inspect the agent's changes before they land on a branch, the README does not tell you how.

The dependency list is also heavier than the description suggests. Alongside the model and MCP packages, package.json pulls in a full OpenTelemetry stack: the API, OTLP HTTP exporters for metrics and traces, instrumentation, SDK node, SDK metrics and semantic conventions. If you are embedding the SDK in a small service, that is a lot of transitive surface for a component you may not have asked for. The README does not explain what is traced or where the exporters send data by default.

Finally, the voice UI at http://localhost:3333 is launched by the installer, and the README's migration notes say gitagent --voice dynamically loads @open-gitagent/voice. Without that package installed, the README says the command prints a one-line install hint and exits cleanly. That is a reasonable failure mode, but it does mean the headline install experience and the slim install experience differ in what actually works.

## Gitagent against the Claude Agent SDK approach

The README explicitly positions the SDK as mirroring the Claude Agent SDK pattern, so that is the honest comparison. The Claude Agent SDK, as described in the README's own reference, is a pattern where the agent runs as a subprocess and the host communicates with it over IPC. Gitagent's stated difference is that it runs in-process, with no subprocesses and no IPC.

The practical consequence is about where state and configuration live. In a subprocess model, the host application owns the agent's configuration and passes it in. In Gitagent, the agent directory owns it: agent.yaml, SOUL.md, RULES.md and the rest are read from disk. That is the whole argument for the project, and it is a real one if your team already reviews changes through pull requests. It is a liability if your configuration is generated dynamically per request, because you are now writing files and committing them to express something that used to be a function argument.

The second difference is language and packaging. Gitagent ships as an npm package with a Node 20+ engine requirement and a CLI binary named gitagent. The in-process design means you cannot point it at a different runtime the way you might with a subprocess-based agent that speaks a protocol over stdio. The v2.1.0 release added MCP client support through @modelcontextprotocol/sdk, so external tool servers are reachable, but the agent host itself is a Node process.

## Maintenance, licensing and what a v1 to v2 upgrade costs

The repository is not archived, and the last push was on 2026-08-20, which is recent enough that the project is being worked on rather than parked. The release history shows v2.2.0 on 2026-08-20, v2.1.0 with MCP client support on 2026-08-09, and v1.4.3 on 2026-04-22. The gap between April and August covers the 1.x to 2.0 restructuring described in the README's migration section.

That migration is the concrete upgrade cost. Voice mode moved out of the main package into @open-gitagent/voice. The README states that the gitagent command and the @open-gitagent/gitagent SDK exports are unchanged, so SDK consumers should not need to touch imports. Voice users need a second global install. The reason given is supply-chain scanning, not architecture, which suggests the split was driven by distribution constraints rather than a redesign of the runtime.

The licence is MIT, declared both in the README badge and in package.json. MIT is permissive: it allows commercial use, modification and redistribution, and it requires that the copyright notice and licence text be preserved. It provides no patent grant and no warranty. That is a summary of what the licence text says, not legal advice; if your organisation has a policy on dependency licences, route the question to whoever owns that policy.

The dependency surface is the ongoing cost to watch. The package pins a range of @mariozechner/pi-agent-core and pi-ai at ^0.70.2, the MCP SDK at ^1.29.0, and the OpenTelemetry packages at their various carets. Caret ranges mean a fresh install can pull newer minor versions than the ones the maintainers last built against.

## Conclusion

Adopt Gitagent if you already think in branches and diffs and you want an agent whose rules and memory you can review, revert and fork like any other code. Skip it if you need a hosted control plane, a non-Node runtime, or an agent that must run without a git working tree. Before committing, run the CLI against a throwaway directory and read the files it scaffolds, then confirm the model provider you intend to use is reachable from your environment, because the README documents provider-prefixed model strings but not a fallback path when one is unavailable.

## FAQ

### What is Gitagent?

Gitagent is a git-native AI agent framework where the agent lives inside a git repository. Its identity, rules, memory, tools and skills are version-controlled files such as agent.yaml, SOUL.md, RULES.md and the memory/ directory.

### How do I install Gitagent?

The README gives a one-command installer that curls install.sh from the main branch, installs the CLI globally via npm, walks through API key setup and launches a voice UI at http://localhost:3333. Alternatively you can install the packages manually with npm install -g @open-gitagent/gitagent and npm install -g @open-gitagent/voice.

### Does Gitagent work with VS Code?

The README does not document a VS Code extension or editor integration. The documented surfaces are the gitagent CLI, the @open-gitagent/gitagent SDK, and the web UI that the installer launches at http://localhost:3333.

### Which AI models can Gitagent use?

Models are selected with a provider:model string, and the README gives anthropic:claude-sonnet-4-5-20250929 and openai:gpt-4o-mini as examples. The first-run example exports OPENAI_API_KEY before invoking the CLI.

### What happened to voice mode in Gitagent 2.0?

Voice mode moved into a separate package, @open-gitagent/voice, because the combined bundle was being flagged by supply-chain scanners over a large dist/voice/ui.html file and an unused baileys dependency. The README says the gitagent command and the SDK exports are unchanged.

## Sources

- [Issues](https://github.com/open-gitagent/gitagent/issues)
- [License: MIT](https://github.com/open-gitagent/gitagent/blob/main/LICENSE)
- [open-gitagent/gitagent on GitHub](https://github.com/open-gitagent/gitagent)
- [README](https://github.com/open-gitagent/gitagent/blob/main/README.md)
- [Releases](https://github.com/open-gitagent/gitagent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/open-gitagent-gitagent