Gitagent
A git-native AI agent framework where your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files.
- Source repo
- open-gitagent/gitagent
- Stars
- ★ 719
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Rust
- FA score
- 44/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer runs
gitagent --dir ~/my-project "Explain this project and suggest improvements"to get analysis on a local codebase. - Not a fit if
- Users unwilling to install a Node.js 18+ and git runtime
- Teams needing MCP resources and prompts; v1 exposes tools only
- Source review
- 44/100 · Major gaps
What does this agent do, and when should you use it?
Gitagent (formerly Gitclaw) is a git-native AI agent framework for Node.js that turns an agent's entire configuration into a Git repository: agent.yaml defines models and tools, SOUL.md defines personality, RULES.md defines behavioral constraints, memory/ stores versioned memory, tools/ defines declarative YAML tools, skills/ provides composable skill modules, and hooks/ manages lifecycle scripts. Agents run via a CLI or an in-process TypeScript SDK, with a 'Local Repo Mode' that clones a GitHub repo, works on a session branch, and auto-commits changes. It supports MCP as a client, multi-model backends (OpenAI, Anthropic, Google, etc.), a plugin system for installing extensions from Git URLs, and built-in OpenTelemetry telemetry. The 'agents as repos' model enables forking, branching, git log for memory history, and diffing rules.
Gitagent executes operations by reading configuration files (agent.yaml, SOUL.md, RULES.md, etc.) to compose system prompts; using built-in tools (cli, read, write, memory) to run shell commands, read/write files, and commit memory; running declarative tools (e.g., tools/search.yaml scripts) and skills; invoking lifecycle hooks (pre_tool_use, on_error) for gating and audit; connecting to MCP servers (filesystem, GitHub, Postgres) and registering their tools as <server>__<tool>; in Local Repo Mode, cloning a repository, executing changes, and auto-committing to a session branch; and via the SDK's query() function, streaming messages (delta, assistant, tool_use, etc.). Output includes agent responses, tool results, audit logs, and telemetry.
- A developer runs
gitagent --dir ~/my-project "Explain this project and suggest improvements"to get analysis on a local codebase. - A team uses
gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the login bug"to have the agent fix issues in a cloned repo and commit to a session branch. - An organization that wants reuse of a consistent agent personality can use the
extendsfield to inherit a base agent, customizing skills and tools in derived agents. - A security-conscious engineer sets hooks to intercept dangerous commands like
rm -rfor force argument modifications before tool execution. - A developer needs to interact with external services; they configure MCP servers in agent.yaml or SDK so the agent automatically uses tools like Postgres or GitHub.
- An engineering team enabling telemetry sets OTEL_EXPORTER_OTLP_ENDPOINT to observe token usage, cost, and tool performance.
How do you install or deploy this agent?
Requirements: Node.js 18+ (20+ recommended), npm, and git. One-command install: run bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh?$(date +%s)") — it globally installs npm packages, guides API key setup, and launches the voice UI at localhost:3333. Manual install of slim CLI and SDK: npm install -g @open-gitagent/gitagent. For voice and web UI, also run npm install -g @open-gitagent/voice. Set GITAGENT_SLIM=1 to skip voice for sandboxed environments.
How do you use this agent?
First set an API key, e.g., export OPENAI_API_KEY="sk-...". Then run gitagent --dir ~/my-project "Explain this project". On first run it auto-scaffolds agent.yaml, SOUL.md, and memory/. To operate on a remote repo, use --repo <URL> with --pat or GITHUB_TOKEN; resume with --session. For programmatic use, import { query } from "gitagent" and iterate over the async generator with options like prompt, dir, model. Voice mode is activated with gitagent --voice after installing the voice package. Models are configured in agent.yaml and can be overridden with --model or environment settings.
What are this agent's strengths and limitations?
- Git-native design: configuration and memory are version-controlled, enabling forking, branching, and git log for memory history.
- Multi-model support via pi-ai: Anthropic, OpenAI, Google, xAI, Groq, Mistral, with fallback models.
- Built-in MCP client connects to many existing servers without integration code, reducing development overhead.
- TypeScript SDK with streaming query, custom tool definitions, and programmatic plugin API for embedding into applications.
- Compliance and audit features (risk levels, human-in-the-loop, audit logging) suit enterprise deployment.
- Requires a Node.js and Git runtime, global package installation, and API key configuration.
- Voice and web UI are in a separate package (@open-gitagent/voice) that must be installed additionally; it may be blocked by supply-chain scanners.
- MCP support is limited to tools; resources and prompts are not yet exposed.
- Multi-model support depends on the pi-ai library, adding an external dependency.
- Upgrading from 1.x to 2.0 requires manually splitting voice packages, as documented.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Gitagent This agent | 44 · Major gaps | CLIFree + model costs | ★ 719 | 2mo ago | Rust | OpenAI API · Claude API |
| Adaline Gateway | 69 · Some gaps | Library / SDKFree + model costs | ★ 607 | 2mo ago | TypeScript | OpenAI API · Claude API |
| Cersei — Rust SDK for Coding Agents | 60 · Some gaps | Library / SDKFree + model costs | ★ 461 | 2mo ago | Rust | OpenAI API · Claude API |
| TypedAI | 40 · Major gaps | CLIFree + model costs | ★ 1.2k | 10mo ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows permission control mechanisms (e.g., allowedTools/disallowedTools, preToolUse hooks can block/modify tool calls), but no explicit default least-privilege policy; user confirmation exists (human_in_the_loop config, hooks can block) but not enforced by default; data flow transparency partial: audit logs and telemetry exist, but data flow to user not explained; sensitive data handling: supports env var interpolation, but no encryption or redaction specified; dependency security: uses npm packages, supply-chain scanner considerations (splitting voice package), but no vulnerability scanning evidence; external effects: sandbox option and hooks can restrict, but cli execution allowed by default; rollback: git-native support, but no explicit rollback tool; source attribution: plugins have author field, but unverified.
Self-consistency: docs and code structure consistent, tests cover key security fixes (e.g., G1, G25), but not all features; dependency availability: many dependencies, but no lock file or integrity checks; failure messages: error handling exists (e.g., fail-soft MCP), but no user-friendly error examples.
Audience and scenarios: targets developers, provides CLI, SDK, plugins, diverse scenarios; capability boundaries: tool allow/deny lists, but no default boundaries; trigger precision: hooks and skills, but no detailed trigger conditions; environment fit: multi-model, multi-platform, but OS compatibility not specified.
Information architecture: clear docs, architecture diagram; install notes: one-command and manual install, but no uninstall; naming stability: version 2.2.0, but no naming conventions; examples and FAQ: many examples, no FAQ; known limitations: MCP only tools, but other limitations not listed; license: MIT, clear; versioning/changelog: version number, no CHANGELOG; maintenance responsibility: author field, but no maintenance commitment.
Output usability: streaming and structured messages, easy integration; marginal value: git-native concept innovative, but actual value unverified; cost-benefit: cost tracking, but no performance benchmarks.
Claim traceability: most README features have code/test support, but some claims (e.g., 'always learning') unverified; cross-source corroboration: single source, no external validation; fact-inference separation: not clearly distinguished.
- Publisher identity unverified; use with caution.
- CLI execution allowed by default, potential security risk; consider configuring hooks or sandbox.
- Many dependencies without lock file; supply chain risk.
- Some promotional claims (e.g., 'always learning') lack evidence.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.2.0 v2.2.0 — ira: Rust engine + Lyzr Edgespace desktop app
Release notes excerpt
ira — the gitagent engine, ported to Rust This release adds rust/gitagent-rs: a Rust rewrite of the gitagent engine (ira) and a complete local-first desktop product built on it (Lyzr Edgespace). Engine - pi core: agent loop, provider fallback + auto-continue on truncation, streaming channel splitter for reasoning models - SDK: agent loader (argv-only git, injection-safe), four builtin tools + memory/pdf, docx/pdf text extraction, PDF writer, hooks, sessions, eval harness Desktop app (Lyzr Edgespace) …View on GitHub ↗ -
v2.1.0 v2.1.0 — MCP client support
Release notes excerpt
First release with Model Context Protocol (MCP) client support — connect gitagent to local and remote MCP servers and expose their tools to the agent. ✨ New MCP client (#59) - New mcpServers option on query() (and mcp_servers in agent.yaml). - Transports: stdio (local child process) and http / sse (remote). - Discovered tools are namespaced <server>__<tool> and merged into the agent's tool set. - Clean, idempotent teardown of every server on all exit paths (success, hook-block, abort, error). - Adds dependency @modelcontextprotocol/sdk. ```ts …View on GitHub ↗ -
v1.4.3 v1.4.3 — Auto-recover Realtime session expiry
Release notes excerpt
What's New Fixes the \"Your session hit the maximum duration of 60 minutes\" failure in voice mode — previously, once OpenAI terminated the Realtime session, every subsequent message returned \"server had an error while processing your request\" and the agent was stuck until restart. Proactive refresh …View on GitHub ↗
FAQ
What runtime does Gitagent require?
How do I configure API keys?
export OPENAI_API_KEY="sk-...". You can specify multiple models in agent.yaml and override with the --model flag.What if an MCP server fails to connect?
How do I enable voice and the web UI?
gitagent --voice. Without it, the CLI prints an install hint and exits cleanly.