Gitagent

Why Gitagent?

One-Command Install

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

Or install manually:

# Slim CLI + SDK (recommended in sandboxed/CI environments where supply-chain
# scanners reject larger bundles)
npm install -g @open-gitagent/gitagent
# Add voice mode + web UI (the same web UI install.sh launches at :3333)
npm install -g @open-gitagent/voice

Migrating from 1.x → 2.0

# If you were on v1.x and used voice:
npm install -g @open-gitagent/gitagent@latest @open-gitagent/voice
# If you only use the SDK / non-voice CLI:
npm install -g @open-gitagent/gitagent@latest

Quick Start

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

Local Repo Mode

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"

export GITHUB_TOKEN=ghp_xxx
gitagent --repo https://github.com/org/repo "Add unit tests"

CLI Options

SDK

import { query } from "gitagent";
// Simple query
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.");
}
// Local repo mode via SDK
for await (const msg of query({
 prompt: "Fix the login bug",
 model: "openai:gpt-4o-mini",
 repo: {
 url: "https://github.com/org/repo",
 token: process.env.GITHUB_TOKEN!,
 },
})) {
 if (msg.type === "delta") process.stdout.write(msg.content);
}

SDK

query(options): Query

import { query } from "gitagent";
for await (const msg of query({
 prompt: "Refactor the auth module",
 dir: "/path/to/agent",
 model: "anthropic:claude-sonnet-4-5-20250929",
})) {
 switch (msg.type) {
 case "delta": // streaming text chunk
 process.stdout.write(msg.content);
 break;
 case "assistant": // complete response
 console.log(`\nTokens: ${msg.usage?.totalTokens}`);
 break;
 case "tool_use": // tool invocation
 console.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`);
 break;
 case "tool_result": // tool output
 console.log(`Result: ${msg.content}`);
 break;
 case "system": // lifecycle events & errors
 console.log(`[${msg.subtype}] ${msg.content}`);
 break;
 }
}

tool(name, description, schema, handler): GCToolDefinition

import { query, tool } from "gitagent";
const search = tool(
 "search_docs",
 "Search the documentation",
 {
 properties: {
 query: { type: "string", description: "Search query" },
 limit: { type: "number", description: "Max results" },
 },
 required: ["query"],
 },
 async (args) => {
 const results = await mySearchEngine(args.query, args.limit ?? 10);
 return { text: JSON.stringify(results), details: { count: results.length } };
 },
);
for await (const msg of query({
 prompt: "Find docs about authentication",
 tools: [search],
})) {
 // agent can now call search_docs
}

Hooks

for await (const msg of query({
 prompt: "Deploy the service",
 hooks: {
 preToolUse: async (ctx) => {
 // Block dangerous operations
 if (ctx.toolName === "cli" && ctx.args.command?.includes("rm -rf"))
 return { action: "block", reason: "Destructive command blocked" };
 // Modify arguments
 if (ctx.toolName === "write" && !ctx.args.path.startsWith("/safe/"))
 return { action: "modify", args: { ...ctx.args, path: `/safe/${ctx.args.path}` } };
 return { action: "allow" };
 },
 onError: async (ctx) => {
 console.error(`Agent error: ${ctx.error}`);
 },
 },
})) {
 // ...
}

QueryOptions Reference

Message Types

Architecture

my-agent/
├── agent.yaml # Model, tools, runtime config
├── SOUL.md # Agent identity & personality
├── RULES.md # Behavioral rules & constraints
├── DUTIES.md # Role-specific responsibilities
├── memory/
│ └── MEMORY.md # Git-committed agent memory
├── tools/
│ └── *.yaml # Declarative tool definitions
├── skills/
│ └── <name>/
│ ├── SKILL.md # Skill instructions (YAML frontmatter)
│ └── scripts/ # Skill scripts
├── workflows/
│ └── *.yaml|*.md # Multi-step workflow definitions
├── agents/
│ └── <name>/ # Sub-agent definitions
├── plugins/
│ └── <name>/ # Local plugins (plugin.yaml + tools/hooks/skills)
├── hooks/
│ └── hooks.yaml # Lifecycle hook scripts
├── knowledge/
│ └── index.yaml # Knowledge base entries
├── config/
│ ├── default.yaml # Default environment config
│ └── <env>.yaml # Environment overrides
├── examples/
│ └── *.md # Few-shot examples
└── compliance/
 └── *.yaml # Compliance & audit config

Agent Manifest (agent.yaml)

spec_version: "0.1.0"
name: my-agent
version: 1.0.0
description: An agent that does things
model:
 preferred: "anthropic:claude-sonnet-4-5-20250929"
 fallback: ["openai:gpt-4o"]
 constraints:
 temperature: 0.7
 max_tokens: 4096
tools: [cli, read, write, memory]
runtime:
 max_turns: 50
 timeout: 120
# Optional
extends: "https://github.com/org/base-agent.git"
skills: [code-review, deploy]
delegation:
 mode: auto
compliance:
 risk_level: medium
 human_in_the_loop: true

Tools

Built-in Tools

Declarative Tools

# tools/search.yaml
name: search
description: Search the codebase
input_schema:
 properties:
 query:
 type: string
 description: Search query
 path:
 type: string
 description: Directory to search
 required: [query]
implementation:
 script: search.sh
 runtime: sh

Hooks

hooks:
 on_session_start:
 - script: validate-env.sh
 description: Check environment is ready
 pre_tool_use:
 - script: audit-tools.sh
 description: Log and gate tool usage
 post_response:
 - script: notify.sh
 on_error:
 - script: alert.sh

{ "action": "allow" }
{ "action": "block", "reason": "Not permitted" }
{ "action": "modify", "args": { "modified": "args" } }

Skills

skills/
 code-review/
 SKILL.md
 scripts/
 lint.sh

---
name: code-review
description: Review code for quality and security
---
# Code Review
When reviewing code:
1. Check for security vulnerabilities
2. Verify error handling
3. Run the lint script for style checks

Plugins

CLI Commands

# Install from git URL
gitagent plugin install https://github.com/org/my-plugin.git
# Install from local path
gitagent plugin install ./path/to/plugin
# Install with options
gitagent plugin install <source> --name custom-name --force --no-enable
# List all discovered plugins
gitagent plugin list
# Enable / disable
gitagent plugin enable my-plugin
gitagent plugin disable my-plugin
# Remove
gitagent plugin remove my-plugin
# Scaffold a new plugin
gitagent plugin init my-plugin

Plugin Manifest (plugin.yaml)

id: my-plugin # Required, kebab-case
name: My Plugin
version: 0.1.0
description: What this plugin does
author: Your Name
license: MIT
engine: ">=0.3.0" # Min gitagent version
provides:
 tools: true # Load tools from tools/*.yaml
 skills: true # Load skills from skills/
 prompt: prompt.md # Inject into system prompt
 hooks:
 pre_tool_use:
 - script: hooks/audit.sh
 description: Audit tool calls
config:
 properties:
 api_key:
 type: string
 description: API key
 env: MY_API_KEY # Env var fallback
 timeout:
 type: number
 default: 30
 required: [api_key]
entry: index.ts # Optional programmatic entry point

Plugin Config in agent.yaml

plugins:
 my-plugin:
 enabled: true
 source: https://github.com/org/my-plugin.git # Auto-install on load
 version: main # Git branch/tag
 config:
 api_key: "${MY_API_KEY}" # Supports env interpolation
 timeout: 60

Discovery Order

Programmatic Plugins

// index.ts
import type { GitagentPluginApi } from "gitagent";
export async function register(api: GitagentPluginApi) {
 // Register a tool
 api.registerTool({
 name: "search_docs",
 description: "Search documentation",
 inputSchema: {
 properties: { query: { type: "string" } },
 required: ["query"],
 },
 handler: async (args) => {
 const results = await search(args.query);
 return { text: JSON.stringify(results) };
 },
 });
 // Register a lifecycle hook
 api.registerHook("pre_tool_use", async (ctx) => {
 api.logger.info(`Tool called: ${ctx.tool}`);
 return { action: "allow" };
 });
 // Add to system prompt
 api.addPrompt("Always check docs before answering questions.");
 // Register a memory layer
 api.registerMemoryLayer({
 name: "docs-cache",
 path: "memory/docs-cache.md",
 description: "Cached documentation lookups",
 });
}

Plugin Structure

my-plugin/
├── plugin.yaml # Manifest (required)
├── tools/ # Declarative tool definitions
│ └── *.yaml
├── hooks/ # Hook scripts
├── skills/ # Skill modules
├── prompt.md # System prompt addition
└── index.ts # Programmatic entry point

Multi-Model Support

# agent.yaml
model:
 preferred: "anthropic:claude-sonnet-4-5-20250929"
 fallback:
 - "openai:gpt-4o"
 - "google:gemini-2.0-flash"

Inheritance & Composition

# agent.yaml
extends: "https://github.com/org/base-agent.git"
# Dependencies
dependencies:
 - name: shared-tools
 source: "https://github.com/org/shared-tools.git"
 version: main
 mount: tools
# Sub-agents
delegation:
 mode: auto

Compliance & Audit

# agent.yaml
compliance:
 risk_level: high
 human_in_the_loop: true
 data_classification: confidential
 regulatory_frameworks: [SOC2, GDPR]
 recordkeeping:
 audit_logging: true
 retention_days: 90

Telemetry

CLI usage

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "your prompt"

Environment variables

SDK usage

import { initTelemetry, shutdownTelemetry, query } from "gitagent";
await initTelemetry({ serviceName: "my-app" });
for await (const msg of query({ prompt: "hello", model: "anthropic:claude-4-6-sonnet-latest" })) {
 // ...
}
await shutdownTelemetry();

Emitted spans

Emitted metrics

Console quickstart (no collector)

OTEL_TRACES_EXPORTER=console gitagent -p "test"

Local Jaeger quickstart

docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "test"
# Open http://localhost:16686 → service "gitagent"

Contributing

❓ FAQ

General

Installation & Setup

bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh")

export OPENAI_API_KEY="sk-..."

Core Concepts

import { query } from "gitagent";
for await (const msg of query({ prompt: "hello", model: "openai:gpt-4o-mini" })) {
 if (msg.type === "delta") process.stdout.write(msg.content);
}

gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the bug"

Development

Troubleshooting

License