Gitagent: an AI agent whose identity, memory and rules are files in a git repository
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.
At a glance
- What is it?
- Gitagent stores an agent's personality, constraints, memory and tools as version-controlled files rather than application code. The idea is sound and the CLI is small, but the packaging split between the CLI and voice, and the thinness of the published documentation, are the things to weigh before adopting it.
- Who is it for?
- Adopt Gitagent if you want an agent definition that can be reviewed, diffed and forked like any other repository, and if you are comfortable reading the source for behaviour the README does not spell out. Do not adopt it if you need a stable long-term API surface, an audit trail of what the agent did outside git commits, or a runtime other than Node.js, because the install path assumes npm and the SDK is documented only by example.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Gitagent addresses: agent configuration scattered outside version control
Most agent frameworks keep the interesting parts of an agent in application code. The system prompt is a string constant. The tool list is built at startup. Memory is a database row or a JSON blob written by the process. Gitagent takes the opposite position: the agent is a directory, and that directory is a git repository. The README states it plainly, that your agent IS a git repository, and lists the pieces: agent.yaml for model and runtime config, SOUL.md for personality and identity, RULES.md for behavioural constraints, memory/ for committed memory, tools/ for declarative YAML tool definitions, skills/ for composable modules, and hooks/ for lifecycle hooks. The audience is people who already think in commits and branches and want the same affordances for an agent. Fork an agent. Branch a personality. Run git log over its memory. Diff its rules between two versions. That is the whole pitch, and it is a coherent one. It is not aimed at teams who want a hosted agent builder with a visual editor, and it is not aimed at people who consider a prompt a deployment artifact rather than a source file.
How the pieces fit: a file-backed agent directory plus a streaming query loop
The architecture visible in the README is a directory convention on one side and a streaming interface on the other. On disk, the agent is the file set above. At runtime, the SDK exposes a query function that returns an AsyncGenerator of messages. The README shows the message types explicitly: delta for a streaming text chunk, assistant for a complete response carrying a usage object with totalTokens, tool_use for an invocation with toolName and args, tool_result for output, and system for lifecycle events and errors. That is the data flow. A caller iterates the generator, writes deltas as they arrive, and reacts to tool events as they are emitted. The README notes that the SDK mirrors the Claude Agent SDK pattern but runs in-process, with no subprocesses and no IPC. That single design choice explains most of the rest: an in-process agent can read and write the agent directory directly, so memory and rules are just files on the same filesystem, and there is no serialisation boundary to design around. Tool definitions come in two forms, declarative YAML under tools/ and programmatic definitions via the tool helper, which takes a name, a description, a JSON-schema-shaped object with properties and required, and an async handler. Recent releases add MCP client support in v2.1.0, so the tool surface is not limited to what you write yourself. The release history also names a Rust engine in v2.2.0 alongside a desktop app, which sits oddly next to a README whose badges advertise Node 20 and TypeScript 5.7. The README does not explain the relationship between the two, and I cannot confirm from the supplied material which one executes when you run the CLI.
Getting it running: the installer, the two packages, and the flags that matter
The fastest path in the README is a curl-to-bash installer that pipes a timestamped URL from raw.githubusercontent.com into bash. It installs the CLI globally via npm, walks through API key setup, and launches a voice UI at http://localhost:3333. The stated requirements are Node.js 18 or later, npm, and git, though the badge in the same README says node >=20. Treat that discrepancy as a documentation bug rather than a hard constraint, and check the package metadata if you are pinning a runtime. Manual installation uses two packages. The slim CLI and SDK is @open-gitagent/gitagent, and voice mode plus the web UI is @open-gitagent/voice. The installer pulls both by default; setting GITAGENT_SLIM=1 before running the curl command skips voice. The README recommends the slim package in sandboxed or CI environments where supply-chain scanners reject larger bundles. A first run needs nothing more than an API key and a directory. Export OPENAI_API_KEY and run gitagent --dir ~/my-project with a prompt in quotes, and the README says Gitagent auto-scaffolds agent.yaml, SOUL.md and memory/ on first run. The CLI flags are conventional: --dir for the agent directory, --repo for a GitHub URL to clone and work on, --pat for a token with GITHUB_TOKEN and GIT_TOKEN as environment alternatives, --session to resume a session branch, --model as provider:model, --sandbox for a sandbox VM, --prompt for a single-shot invocation that skips the REPL, and --env for an environment config. The repo mode commits to a session branch, and the README's resume example uses a branch name of the form gitagent/session-a1b2c3d4.
The voice split, the supply-chain scanner story, and what it costs you
The 1.x to 2.0 migration is the most concrete engineering decision documented in the README, and it is worth reading as a case study rather than a changelog entry. Voice mode moved out of the main package because a single bundle was being blocked by supply-chain scanners. The README attributes this to a 3,800-line dist/voice/ui.html and an unused baileys dependency. Splitting voice out is stated to drop the slim-core tarball from roughly 180 kB to roughly 85 kB and to remove the scanner triggers. Whether that trade is right depends on your environment. If you run in CI or behind a scanner that rejects the larger bundle, the split is the difference between installing and not installing, and the slim package is the one you want. If you use voice, you now install two packages and keep them in step, and the README documents the failure mode: gitagent --voice dynamically loads @open-gitagent/voice, and without it installed the command prints a one-line install hint and exits cleanly. That is a good failure mode, but it is still a second dependency to track. The SDK exports and the gitagent command are stated to be unchanged across the split, which limits the migration work to the install command.
Where Gitagent is the wrong tool
The git-native model has a cost that the README does not discuss. Memory that lives in commits means every memory write is a commit, and a long-running agent that learns continuously will produce a commit history that grows with its activity. The README says memory/ is git-committed with full history and suggests git log as a way to inspect it. That is genuinely useful for review and rollback, and it is also a lot of small commits unless the implementation batches them. I cannot confirm from the supplied material whether it does. A second limitation is the runtime. Everything documented here assumes Node.js and npm: the installer, both packages, the SDK import, the query loop. The v2.2.0 release note mentions a Rust engine, but the README's install instructions do not describe a Rust build, a cargo command, or a binary distribution. If you are not on Node, the documented path does not cover you. A third case is the one where you want an agent whose behaviour is stable and inspectable without reading source. The README documents the shape of query and tool, and it shows one partial tool definition that is truncated mid-signature. It does not document the contents of agent.yaml, the format of a YAML tool file, the schema of a hook, or how skills compose. Those are the parts you would need to write an agent against, and they are not in the material I have.
Compared with wiring an agent directly into your application
The obvious alternative is not another agent framework. It is the thing most teams already do: call a model provider's SDK from your own service, keep the prompt in a config file or a database, and store conversation state wherever the rest of your application state lives. The difference in approach is where the boundary sits. In the application-integrated approach, the agent is a feature of your program, and its state is subject to your existing backup, migration and access-control rules. In Gitagent, the agent is a repository, and its state is subject to git's rules: branches, diffs, merge conflicts, and a remote. That second model gives you review workflows for free. A proposed change to RULES.md arrives as a pull request. A regression in behaviour can be bisected against memory commits. It also imports git's problems. Two people editing SOUL.md on separate branches produce a merge conflict in a personality. A memory directory under active write is not a great fit for a shared remote. The Claude Agent SDK is named in the README as the pattern the query interface mirrors, and it is the closest reference point for the streaming shape, but the README's own framing is that Gitagent differs by running in-process and by treating the repository as the unit of configuration rather than the process invocation.
Licence, maintenance and what to check before you depend on it
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the most permissive common option and it means you can vendor the code or ship it inside a product. It says nothing about the model providers you connect to, whose own terms govern your usage, and it says nothing about the dependencies pulled in by npm install, which are not MIT by default. I am not giving legal advice here; if the licence interacts with your distribution model, read the LICENSE file in the repository and the licences of the transitive dependencies yourself. On maintenance, the release cadence visible in the supplied material is uneven. v1.4.3 landed in April 2026, v2.1.0 in August 2026 with MCP client support, and v2.2.0 in August 2026 with the Rust engine and a desktop app. The jump from 1.4.3 to 2.1.0 crosses a major version, and the README documents that migration explicitly, which suggests the maintainers do write migration notes. What the material does not show is a deprecation policy, a support window, or a changelog beyond the release titles. For an agent definition that lives in your repository, an upgrade means re-testing behaviour, not just resolving a version conflict, because agent.yaml, RULES.md and the tool schemas are all inputs to what the agent does. Pin the version. Read the release note before moving, and check whether the Rust engine mentioned in v2.2.0 changes which code path your agent.yaml is parsed by.
Editorial conclusion
Adopt Gitagent if you want an agent definition that can be reviewed, diffed and forked like any other repository, and if you are comfortable reading the source for behaviour the README does not spell out. Do not adopt it if you need a stable long-term API surface, an audit trail of what the agent did outside git commits, or a runtime other than Node.js, because the install path assumes npm and the SDK is documented only by example. Before committing, verify three things against the actual repository: which package version you are installing, whether the Rust engine described in the v2.2.0 release note is what runs when you type gitagent, and what the memory and hooks directories contain after a first run, since the README describes their purpose but not their format.
Community notes