Dependencies

dependencies: - name: shared-tools source: "https://github.com/org/shared-tools.git" version: main mount: tools

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:

npm install -g @open-gitagent/gitagent

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

Installation & Setup

What are the requirements? Node.js 18+ (or 20+ recommended), npm, and git. Install globally with npm install -g @open-gitagent/gitagent.

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")

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

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.

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.

SDK usage

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

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();

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.

Console quickstart (no collector)

Print spans directly to stdout — useful for local debugging:

OTEL_TRACES_EXPORTER=console gitagent -p "test"

Local Jaeger quickstart

```bash docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "test"

CLI Options

`query(options): Query`

Returns an AsyncGenerator<GCMessage> that streams agent events.

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;
  }
}

QueryOptions Reference

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

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

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

Environment variables

SDK

npm install gitagent

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

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

CLI Commands

```bash

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.

List all discovered plugins

gitagent plugin list

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

Programmatic Plugins

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

// 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",
  });
}

Available API methods:

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

❓ FAQ

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