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.
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.
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.
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 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.
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.