Gitagent

A universal git-native multimodal always learning AI Agent (TinyHuman)
Your agent lives inside a git repo — identity, rules, memory, tools, and skills are all version-controlled files.

Install • Quick Start • SDK • Architecture • Tools • Hooks • Skills • Plugins

Why Gitagent?

Most agent frameworks treat configuration as code scattered across your application. Gitagent flips this — your agent IS a git repository:

agent.yaml — model, tools, runtime config
SOUL.md — personality and identity
RULES.md — behavioral constraints
memory/ — git-committed memory with full history
tools/ — declarative YAML tool definitions
skills/ — composable skill modules
hooks/ — lifecycle hooks (script or programmatic)

Fork an agent. Branch a personality. git log your agent's memory. Diff its rules. This is agents as repos.

One-Command Install

Copy, paste, run. That's it — no cloning, no manual setup. The installer handles everything:

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

This will:

Install gitagent globally via npm
Walk you through API key setup (Quick or Advanced mode)
Launch the voice UI in your browser at http://localhost:3333

Requirements: Node.js 18+, npm, git

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

install.sh installs both packages by default. Set GITAGENT_SLIM=1 before the curl-bash to skip voice.

Migrating from 1.x → 2.0

Voice mode lives in @open-gitagent/voice now. The reason: as a single bundle, the package was being blocked by some supply-chain scanners that flagged its 3,800-line dist/voice/ui.html and the unused baileys dependency. Splitting voice out drops the slim-core tarball from ~180 kB to ~85 kB and removes the scanner triggers entirely.

# 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

The gitagent command and @open-gitagent/gitagent SDK exports are unchanged. gitagent --voice dynamically loads @open-gitagent/voice; without it installed, it prints a one-line install hint and exits cleanly.

Quick Start

Run your first agent in one line:

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

That's it. Gitagent auto-scaffolds everything on first run — agent.yaml, SOUL.md, memory/ — and drops you into the agent.

Local Repo Mode

Clone a GitHub repo, run an agent on it, auto-commit and push to a session branch:

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

Resume an existing session:

gitagent --repo https://github.com/org/repo --pat ghp_xxx --session gitagent/session-a1b2c3d4 "Continue"

Token can come from env instead of --pat:

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

CLI Options

Flag	Short	Description
`--dir <path>`	`-d`	Agent directory (default: cwd)
`--repo <url>`	`-r`	GitHub repo URL to clone and work on
`--pat <token>`		GitHub PAT (or set `GITHUB_TOKEN` / `GIT_TOKEN`)
`--session <branch>`		Resume an existing session branch
`--model <provider:model>`	`-m`	Override model (e.g. `anthropic:claude-sonnet-4-5-20250929`)
`--sandbox`	`-s`	Run in sandbox VM
`--prompt <text>`	`-p`	Single-shot prompt (skip REPL)
`--env <name>`	`-e`	Environment config

SDK

import{query}from"gitagent";// Simple queryforawait(constmsgofquery({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 SDKforawait(constmsgofquery({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

The SDK provides a programmatic interface to Gitagent agents. It mirrors the Claude Agent SDK pattern but runs in-process — no subprocesses, no IPC.

`query(options): Query`

Returns an AsyncGenerator<GCMessage> that streams agent events.

import{query}from"gitagent";forawait(constmsgofquery({prompt: "Refactor the auth module",dir: "/path/to/agent",model: "anthropic:claude-sonnet-4-5-20250929",})){switch(msg.type){case"delta": // streaming text chunkprocess.stdout.write(msg.content);break;case"assistant": // complete responseconsole.log(`\nTokens: ${msg.usage?.totalTokens}`);break;case"tool_use": // tool invocationconsole.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`);break;case"tool_result": // tool outputconsole.log(`Result: ${msg.content}`);break;case"system": // lifecycle events & errorsconsole.log(`[${msg.subtype}] ${msg.content}`);break;}}

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

Define custom tools the agent can call:

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

Hooks

Programmatic lifecycle hooks for gating, logging, and control:

forawait(constmsgofquery({prompt: "Deploy the service",hooks: {preToolUse: async(ctx)=>{// Block dangerous operationsif(ctx.toolName==="cli"&&ctx.args.command?.includes("rm -rf"))return{action: "block",reason: "Destructive command blocked"};// Modify argumentsif(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

Option	Type	Description
`prompt`	`string \| AsyncIterable`	User prompt or multi-turn stream
`dir`	`string`	Agent directory (default: `cwd`)
`model`	`string`	`"provider:model-id"`
`env`	`string`	Environment config (`config/<env>.yaml`)
`systemPrompt`	`string`	Override discovered system prompt
`systemPromptSuffix`	`string`	Append to discovered system prompt
`tools`	`GCToolDefinition[]`	Additional tools
`replaceBuiltinTools`	`boolean`	Skip cli/read/write/memory
`allowedTools`	`string[]`	Tool name allowlist
`disallowedTools`	`string[]`	Tool name denylist
`repo`	`LocalRepoOptions`	Clone a GitHub repo and work on a session branch
`sandbox`	`SandboxOptions \| boolean`	Run in sandbox VM (mutually exclusive with `repo`)
`hooks`	`GCHooks`	Programmatic lifecycle hooks
`maxTurns`	`number`	Max agent turns
`abortController`	`AbortController`	Cancellation signal
`constraints`	`object`	`temperature`, `maxTokens`, `topP`, `topK`

Message Types

Type	Description	Key Fields
`delta`	Streaming text/thinking chunk	`deltaType`, `content`
`assistant`	Complete LLM response	`content`, `model`, `usage`, `stopReason`
`tool_use`	Tool invocation	`toolName`, `args`, `toolCallId`
`tool_result`	Tool output	`content`, `isError`, `toolCallId`
`system`	Lifecycle events	`subtype`, `content`, `metadata`
`user`	User message (multi-turn)	`content`

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-agentversion: 1.0.0description: An agent that does thingsmodel:
preferred: "anthropic:claude-sonnet-4-5-20250929"fallback: ["openai:gpt-4o"]constraints:
temperature: 0.7max_tokens: 4096tools: [cli, read, write, memory]runtime:
max_turns: 50timeout: 120# Optionalextends: "https://github.com/org/base-agent.git"skills: [code-review, deploy]delegation:
mode: autocompliance:
risk_level: mediumhuman_in_the_loop: true

Tools

Built-in Tools

Tool	Description
`cli`	Execute shell commands
`read`	Read files with pagination
`write`	Write/create files
`memory`	Load/save git-committed memory

Declarative Tools

Define tools as YAML in tools/:

# tools/search.yamlname: searchdescription: Search the codebaseinput_schema:
properties:
query:
type: stringdescription: Search querypath:
type: stringdescription: Directory to searchrequired: [query]implementation:
script: search.shruntime: sh

The script receives args as JSON on stdin and returns output on stdout.

Hooks

Script-based hooks in hooks/hooks.yaml:

hooks:
on_session_start:
- script: validate-env.shdescription: Check environment is readypre_tool_use:
- script: audit-tools.shdescription: Log and gate tool usagepost_response:
- script: notify.shon_error:
- script: alert.sh

Hook scripts receive context as JSON on stdin and return:

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

Skills

Skills are composable instruction modules in skills/<name>/:

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

---name: code-reviewdescription: 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

Invoke via CLI: /skill:code-review Review the auth module

Plugins

Plugins are reusable extensions that can provide tools, hooks, skills, prompts, and memory layers. They follow the same git-native philosophy — a plugin is a directory with a plugin.yaml manifest.

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

Flag	Description
`--name <name>`	Custom plugin name (default: derived from source)
`--force`	Reinstall even if already present
`--no-enable`	Install without auto-enabling

Plugin Manifest (`plugin.yaml`)

id: my-plugin # Required, kebab-casename: My Pluginversion: 0.1.0description: What this plugin doesauthor: Your Namelicense: MITengine: ">=0.3.0"# Min gitagent versionprovides:
tools: true # Load tools from tools/*.yamlskills: true # Load skills from skills/prompt: prompt.md # Inject into system prompthooks:
pre_tool_use:
- script: hooks/audit.shdescription: Audit tool callsconfig:
properties:
api_key:
type: stringdescription: API keyenv: MY_API_KEY # Env var fallbacktimeout:
type: numberdefault: 30required: [api_key]entry: index.ts # Optional programmatic entry point

Plugin Config in `agent.yaml`

plugins:
my-plugin:
enabled: truesource: https://github.com/org/my-plugin.git # Auto-install on loadversion: main # Git branch/tagconfig:
api_key: "${MY_API_KEY}"# Supports env interpolationtimeout: 60

Config resolution priority: agent.yaml config > env var > manifest default.

Discovery Order

Plugins are discovered in this order (first match wins):

Local — <agent-dir>/plugins/<name>/
Global — ~/.gitagent/plugins/<name>/
Installed — <agent-dir>/.gitagent/plugins/<name>/

Programmatic Plugins

Plugins with an entry field in their manifest get a full API:

// index.tsimporttype{GitagentPluginApi}from"gitagent";exportasyncfunctionregister(api: GitagentPluginApi){// Register a toolapi.registerTool({name: "search_docs",description: "Search documentation",inputSchema: {properties: {query: {type: "string"}},required: ["query"],},handler: async(args)=>{constresults=awaitsearch(args.query);return{text: JSON.stringify(results)};},});// Register a lifecycle hookapi.registerHook("pre_tool_use",async(ctx)=>{api.logger.info(`Tool called: ${ctx.tool}`);return{action: "allow"};});// Add to system promptapi.addPrompt("Always check docs before answering questions.");// Register a memory layerapi.registerMemoryLayer({name: "docs-cache",path: "memory/docs-cache.md",description: "Cached documentation lookups",});}

Available API methods:

Method	Description
`registerTool(def)`	Register a tool the agent can call
`registerHook(event, handler)`	Register a lifecycle hook (`on_session_start`, `pre_tool_use`, `post_response`, `on_error`)
`addPrompt(text)`	Append text to the system prompt
`registerMemoryLayer(layer)`	Register a memory layer
`logger.info/warn/error(msg)`	Prefixed logging (`[plugin:id]`)
`pluginId`	Plugin identifier
`pluginDir`	Absolute path to plugin directory
`config`	Resolved config values

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

MCP (Model Context Protocol)

Gitagent is an MCP client: point it at any MCP server and that server's tools are automatically discovered and made available to the agent — no integration code to write. This unlocks the whole ecosystem of ready-made servers (filesystem, GitHub, Postgres, Slack, fetch, …).

Configure servers in `agent.yaml`

mcp_servers:
filesystem: # local server over stdio (default)command: npxargs: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]env:
LOG_LEVEL: "${MCP_LOG_LEVEL}"# ${VAR} interpolated from the environmenttimeoutMs: 30000# connect/list timeout (default 30000)analytics: # remote server over Streamable HTTPtype: httpurl: "https://mcp.example.com/mcp"headers:
Authorization: "Bearer ${ANALYTICS_TOKEN}"legacy: # legacy SSE transport (deprecated)type: sseurl: "https://old.example.com/sse"

On startup gitagent connects to each server, lists its tools, and registers them as <server>__<tool> (e.g. filesystem__read_file, analytics__query). Connections are torn down automatically when the session ends.

Field	Applies to	Description
`command` / `args` / `env` / `cwd`	stdio	How to launch a local server
`type: http \| sse` + `url` + `headers`	remote	Connect to a remote server
`timeoutMs`	both	Connect + list-tools timeout (default `30000`)

Use via the SDK

import{query}from"gitagent";forawait(constmsgofquery({prompt: "Summarize last week's signups from the database",mcpServers: {postgres: {command: "npx",args: ["-y","@modelcontextprotocol/server-postgres",process.env.DB_URL!],},},})){if(msg.type==="tool_use")console.log(`calling ${msg.toolName}`);}

SDK mcpServers are merged with any agent.yamlmcp_servers (the SDK value wins on a key collision).

Behavior & guarantees

Fail-soft: a server that can't start (or times out) is logged and skipped — other servers and built-in tools keep working.
Namespaced & sanitized: tool names are prefixed with the server name and cleaned to satisfy provider naming rules.
Pagination: servers that paginate their tool list are fully enumerated.
Cleanup: stdio servers (child processes) are shut down on every exit path (normal, /quit, Ctrl+C, error).
Lazy: if no servers are configured, the MCP SDK is never loaded.

Note: v1 supports MCP tools. Resources and prompts are not yet exposed.

Multi-Model Support

Gitagent works with any LLM provider supported by pi-ai:

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

Supported providers: anthropic, openai, google, xai, groq, mistral, and more.

Inheritance & Composition

Agents can extend base agents:

# agent.yamlextends: "https://github.com/org/base-agent.git"# Dependenciesdependencies:
- name: shared-toolssource: "https://github.com/org/shared-tools.git"version: mainmount: tools# Sub-agentsdelegation:
mode: auto

Compliance & Audit

Built-in compliance validation and audit logging:

# agent.yamlcompliance:
risk_level: highhuman_in_the_loop: truedata_classification: confidentialregulatory_frameworks: [SOC2, GDPR]recordkeeping:
audit_logging: trueretention_days: 90

Audit logs are written to .gitagent/audit.jsonl with full tool invocation traces.

Telemetry

Gitagent ships with built-in OpenTelemetry instrumentation. Set OTEL_EXPORTER_OTLP_ENDPOINT and telemetry is on; leave it unset and runtime cost is zero.

Three layers of signals:

HTTP-level — @opentelemetry/instrumentation-undici auto-patches fetch/undici, so every LLM provider call (Anthropic, OpenAI, Google, …) gets a client span with URL, status code, and timing.
gen_ai.chat spans — emitted on every assistant message_end. Carry gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.response.finish_reasons, and gitagent.cost_usd. Span/metric content never contains the prompt or completion text.
gitagent.tool.execute spans — wrap every tool call with tool.name, tool.call_id, tool.status (ok/error), and tool.error_message on failure.

A root gitagent.agent.session span opens at agent construction and closes on every exit path (success, hook-block, SIGINT, error).

CLI usage

Just set the endpoint — no --import flag, no extra install steps:

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

Telemetry is enabled automatically when the endpoint is set and disabled when it is not. To force-disable even when the endpoint is set, pass GITAGENT_OTEL_ENABLED=false.

Environment variables

Variable	Description	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP/HTTP collector base URL (e.g. `http://localhost:4318`). When set, telemetry is auto-enabled.	(unset → telemetry off)
`GITAGENT_OTEL_ENABLED`	Set to `false` to disable telemetry even when the endpoint is set	(unset = auto)
`OTEL_SERVICE_NAME`	Resource `service.name`	`gitagent`
`OTEL_SERVICE_VERSION`	Resource `service.version`	(unset)
`OTEL_EXPORTER_OTLP_HEADERS`	Comma-separated key=value pairs, no quotes (e.g. `Authorization=Bearer xyz,x-tenant=abc`)	(unset)
`OTEL_TRACES_EXPORTER`	Set to `console` to print spans to stdout — no collector needed	(unset)

SDK usage

For programmatic embedders, call initTelemetry explicitly — you control when initialisation happens:

import{initTelemetry,shutdownTelemetry,query}from"gitagent";awaitinitTelemetry({serviceName: "my-app"});forawait(constmsgofquery({prompt: "hello",model: "anthropic:claude-4-6-sonnet-latest"})){// …}awaitshutdownTelemetry();

OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are read automatically by the OTLP exporter when not supplied programmatically. Pass exporterEndpoint / headers only when you need to override env-based config in code.

Emitted spans

Name	Kind	Key attributes
`gitagent.agent.session`	INTERNAL	`gitagent.entry` (`sdk` / `cli`), `gitagent.cost_usd`, `gitagent.session.duration_ms`
`gitagent.tool.execute`	INTERNAL	`tool.name`, `tool.call_id`, `tool.status`, `tool.error_message`
`gen_ai.chat`	CLIENT	`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons`, `gitagent.cost_usd`
`HTTP …`	CLIENT	URL, status code, duration (auto from `instrumentation-undici`)

Emitted metrics

Name	Type	Description
`gitagent.tool.calls`	counter	Number of tool executions, labelled by `tool.name`
`gitagent.tool.duration_ms`	histogram	Tool execution duration
`gitagent.session.duration_ms`	histogram	Session duration
`gitagent.session.cost_usd`	counter (USD)	Cumulative session cost
`gen_ai.client.token.usage`	counter	Token usage by `gen_ai.system`, `gen_ai.request.model`, `gen_ai.token.type`
`gen_ai.client.operation.duration`	histogram	LLM call duration

Console quickstart (no collector)

Print spans directly to stdout — useful for local debugging:

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

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

❓ FAQ

General

What is Gitagent? GitAgent (formerly Gitclaw) is a git-native AI agent framework where the agent IS a git repository. Identity, rules, memory, tools, and skills are all version-controlled files, enabling "agents as repos" paradigm.

How does Gitagent differ from other agent frameworks? Unlike frameworks that scatter configuration across application code, Gitagent makes the agent itself a git repo:

Fork an agent → inherit personality, rules, tools
Branch → create alternate personality versions
git log → see agent's memory evolution
Diff → track rule changes over time

What is the "agents as repos" concept? Your agent lives in a git repository with structured files:

agent.yaml — model, tools, runtime config
SOUL.md — personality and identity
RULES.md — behavioral constraints
memory/ — git-committed memory with full history
tools/ — declarative YAML tool definitions
skills/ — composable skill modules
hooks/ — lifecycle hooks

Installation & Setup

What are the requirements? Node.js 18+ (or 20+ recommended), npm, and git. Install globally with npm install -g @open-gitagent/gitagent (slim CLI + SDK). Add @open-gitagent/voice for voice mode + the web UI.

How do I set up API keys? Run the installer for guided setup:

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

Or set manually:

export OPENAI_API_KEY="sk-..."

Which LLM providers are supported?

OpenAI (GPT-4o, GPT-4o-mini, etc.)
Anthropic (Claude models via native SDK)
Any OpenAI-compatible provider

Use --model flag to override: gitagent --model anthropic:claude-sonnet-4-5-20250929

Core Concepts

What is the SDK and how do I use it? The SDK provides programmatic access via query() function that streams agent events:

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

How do local repo mode sessions work? Clone a GitHub repo, run an agent on it, auto-commit to a session branch:

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

Resume with: gitagent --repo URL --session gitagent/session-xxx "Continue"

What hooks are available? Hooks are lifecycle scripts or programmatic handlers in hooks/ directory. They trigger on agent events like tool execution, session start/end, or memory updates.

Development

How do I create custom tools? Define tools in tools/ directory using declarative YAML format. Each tool specifies name, description, parameters, and execution logic.

How do I add skills? Create skill modules in skills/ directory. Skills are composable and can be imported from installed packages or defined locally.

What telemetry options are available? OpenTelemetry integration for observability:

Set OTEL_EXPORTER_OTLP_ENDPOINT for auto-enable
Use OTEL_TRACES_EXPORTER=console for local debugging
Jaeger quickstart with Docker

Troubleshooting

Why is my agent not responding?

Check API key is set (OPENAI_API_KEY or equivalent)
Verify network connectivity to LLM provider
Use --verbose flag for detailed logs
Check agent.yaml model configuration

How do I debug agent behavior?

Use console exporter: OTEL_TRACES_EXPORTER=console gitagent -p "test"
Check spans in Jaeger: docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one
Inspect memory/ directory for agent state

Where can I get help?

GitHub Issues: https://github.com/open-gitagent/gitagent/issues
Examples: See README SDK section and CLI options
Contributing: See CONTRIBUTING.md for guidelines

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 135 Commits
.github/workflows		.github/workflows
agents/assistant		agents/assistant
docs		docs
examples		examples
memory		memory
skills		skills
src		src
test		test
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Documentation.md		Documentation.md
GitAgent_Redesigned.pptx		GitAgent_Redesigned.pptx
LICENSE		LICENSE
README.md		README.md
RULES.md		RULES.md
SOUL.md		SOUL.md
agent.yaml		agent.yaml
gitagent-logo.png		gitagent-logo.png
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Gitagent

Why Gitagent?

One-Command Install

Or install manually:

Migrating from 1.x → 2.0

Quick Start

Local Repo Mode

CLI Options

SDK

SDK

query(options): Query

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

Hooks

QueryOptions Reference

Message Types

Architecture

Agent Manifest (agent.yaml)

Tools

Built-in Tools

Declarative Tools

Hooks

Skills

Plugins

CLI Commands

Plugin Manifest (plugin.yaml)

Plugin Config in agent.yaml

Discovery Order

Programmatic Plugins

Plugin Structure

MCP (Model Context Protocol)

Configure servers in agent.yaml

Use via the SDK

Behavior & guarantees

Multi-Model Support

Inheritance & Composition

Compliance & Audit

Telemetry

CLI usage

Environment variables

SDK usage

Emitted spans

Emitted metrics

Console quickstart (no collector)

Local Jaeger quickstart

Contributing

❓ FAQ

General

Installation & Setup

Core Concepts

Development

Troubleshooting

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`query(options): Query`

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

Agent Manifest (`agent.yaml`)

Plugin Manifest (`plugin.yaml`)

Plugin Config in `agent.yaml`

Configure servers in `agent.yaml`