Gitagent

Универсальный агент, нативный для git, мультимодальный, постоянно обучающийся ИИ-агент (TinyHuman)
Ваш агент живёт внутри git-репозитория — личность, правила, память, инструменты и навыки представляют собой файлы, находящиеся под версионным контролем.

Установить • Быстрый старт • SDK • Архитектура • Инструменты • Крючки • Навыки • Плагины

---

Почему Gitagent?

Большинство фреймворков агентов рассматривают конфигурацию как код, разбросанный по вашему приложению. Gitagent переворачивает это — ваш агент ЯВЛЯЕТСЯ git-репозиторием:

• agent.yaml — модель, инструменты, конфигурация выполнения
• SOUL.md — личность и идентичность
• RULES.md — поведенческие ограничения
• memory/ — память, зафиксированная в git с полной историей
• tools/ — декларативные определения инструментов в YAML
• skills/ — компонуемые модули навыков
• hooks/ — хуки жизненного цикла (скрипт или программные)

Сделайте форк агента. Создайте ветку личности. Просмотрите git log памяти агента. Сравните его правила. Это агенты как репозитории.

Однокомандная установка

Скопируйте, вставьте, запустите. Больше ничего не нужно — нет клонирования, нет ручной настройки. Установщик делает всё:

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

Это сделает: - Установить gitagent глобально через npm - Провести вас через настройку API-ключа (быстрый или продвинутый режим) - Запустить голосовой интерфейс в вашем браузере по адресу http://localhost:3333

Требования: Node.js 18+, npm, git

Или установить вручную:

# 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 по умолчанию устанавливает оба пакета. Установите GITAGENT_SLIM=1 перед выполнением curl-bash, чтобы пропустить голосовой режим.

Миграция с 1.x → 2.0

Режим голоса теперь находится в пакете @open-gitagent/voice. Причина: как единый бандл, пакет блокировался некоторыми сканерами цепочки поставок, которые помечали его файл dist/voice/ui.html длиной 3800 строк и неиспользуемую зависимость baileys. Выделение голоса в отдельный пакет уменьшает размер slim-core tarball с ~180 КБ до ~85 КБ и полностью убирает триггеры сканеров.

# 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

Команда gitagent и экспорты SDK @open-gitagent/gitagent остались неизменными. gitagent --voice динамически загружает @open-gitagent/voice; если он не установлен, выводится однострочная подсказка по установке и процесс завершается чисто.

Быстрый старт

Запустите своего первого агента в одной строке:

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

Всё. Gitagent при первом запуске автоматически создаёт необходимые файлы — agent.yaml, SOUL.md, memory/ — и помещает вас в агента.

Режим локального репозитория

Клонируйте репозиторий GitHub, запустите на нём агента, автоматически делайте коммит иpush в ветку сессии:

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"

Токен можно взять из переменной окружения вместо указания --pat:

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

Параметры CLI

Флаг	Сокращение	Описание
--dir <path>	-d	Указывает каталог агента (по умолчанию: текущий каталог)
--repo <url>	-r	URL репозитория GitHub для клонирования и работы
--pat <token>		Личный токен доступа GitHub (или установите переменные GITHUB_TOKEN / GIT_TOKEN)
--session <branch>		Возобновить существующую ветку сессии
--model <provider:model>	-m	Переопределить модель (например, anthropic:claude-sonnet-4-5-20250929)
--sandbox	-s	Запустить в изолированной виртуальной машине (песочнице)
--prompt <text>	-p	Одноразовый запрос (пропустить REPL)
--env <name>	-e	Конфигурация окружения

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

SDK предоставляет программный интерфейс для взаимодействия с агентами Gitagent. Он повторяет паттерн Claude Agent SDK, но выполняется внутри процесса — без подпроцессов и межпроцессного взаимодействия.

query(options): Query

Возвращает AsyncGenerator<GCMessage>, который потоково передаёт события агента.

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
}

Крючки

Программные хуки жизненного цикла для контроля, журналирования и управления:

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

Опция	Тип	Описание
prompt	string \| AsyncIterable	Запрос пользователя или потоковый многоходовой запрос
dir	string	Каталог агента (по умолчанию: cwd)
model	string	Строка формата provider:model-id
env	string	Конфигурация окружения (config/<env>.yaml)
systemPrompt	string	Переопределить обнаруженный системный промпт
systemPromptSuffix	string	Добавить к обнаруженному системному промпту
tools	GCToolDefinition[]	Дополнительные инструменты
replaceBuiltinTools	boolean	Пропустить встроенные инструменты cli/read/write/memory
allowedTools	string[]	Список разрешённых имён инструментов
disallowedTools	string[]	Список запрещённых имён инструментов
repo	LocalRepoOptions	Клонировать репозиторий GitHub и работать в ветке сессии
sandbox	SandboxOptions \| boolean	Запуск в изолированной виртуальной машине (песочнице) (исключает использование repo)
hooks	GCHooks	Программные хуки жизненного цикла
maxTurns	number	Максимальное количество ходов агента
abortController	AbortController	Сигнал отмены
constraints	object	Объект с ограничениями: temperature, maxTokens, topP, topK

Типы сообщений

Тип	Описание	Ключевые поля
delta	Потоковый фрагмент текста/размышлений	deltaType, content
assistant	Полный ответ LLM	content, model, usage, stopReason
tool_use	Вызов инструмента	toolName, args, toolCallId
tool_result	Вывод инструмента	content, isError, toolCallId
system	События жизненного цикла	subtype, content, metadata
user	Сообщение пользователя (многократный)	content

Архитектура

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

Инструменты

Встроенные инструменты

Инструмент	Описание
cli	Выполнить команды оболочки
read	Чтение файлов с постраничным выводом
write	Запись/создание файлов
memory	Загрузка/сохранение памяти, зафиксированной в git

Декларативные инструменты

Определяйте инструменты как YAML в 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

Скрипт получает аргусы в виде JSON на стандартный ввод и возвращает вывод на стандартный вывод.

Хуки

Скриптовые хуки в hooks/hooks.yaml:

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

Скрипты хуков получают контекст в виде JSON на стандартный ввод и возвращают:

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

Навыки

Навыки представляют собой компонуемые модули инструкций в skills/<name>/:

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

Вызовите через CLI: /skill:code-review Review the auth module

Плагины

Плагины представляют собой повторно используемые расширения, которые могут предоставлять инструменты, хуки, навыки, подсказки и слои памяти. Они следуют той же философии git-native — плагин представляет собой каталог с манифестом plugin.yaml.

Команды CLI

# 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

Флаг	Описание
--name <name>	Пользовательское имя плагина (по умолчанию: получено из источника)
--force	Переустановить даже если уже присутствует
--no-enable	Установить без автоматического включения

Манифест плагина (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

Конфигурация плагина в 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

Приоритет разрешения конфигурации: agent.yaml config > env var > manifest default.

Порядок обнаружения

Плагины обнаруживаются в следующем порядке (первое совпадение выигрывает):

1. Локальный — <agent-dir>/plugins/<name>/
2. Глобальный — ~/.gitagent/plugins/<name>/
3. Установленный — <agent-dir>/.gitagent/plugins/<name>/

Программные плагины

Плагины с полем entry в их манифесте получают полный 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",
  });
}

Доступные методы API:

Метод	Описание
registerTool(def)	Зарегистрировать инструмент, который может вызывать агент
registerHook(event, handler)	Зарегистрировать хук жизненного цикла (on_session_start, pre_tool_use, post_response, on_error)
addPrompt(text)	Добавить текст в системный подсказ
registerMemoryLayer(layer)	Зарегистрировать слой памяти
logger.info/warn/error(msg)	Префиксированное ведение журнала ([plugin:id])
pluginId	Идентификатор плагина
pluginDir	Абсолютный путь к каталогу плагина
config	Разрешённые значения конфигурации

Структура плагина

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 (Протокол контекста модели)

Gitagent является клиентом MCP: укажите на любой MCP сервер, и инструменты этого сервера будут автоматически обнаружены и сделаны доступными для агента — не нужно писать код интеграции. Это открывает всю экосистему готовых серверов (файловая система, GitHub, Postgres, Slack, fetch, …).

Настройка серверов в agent.yaml

mcp_servers:
  filesystem:                                   # local server over stdio (default)
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
    env:
      LOG_LEVEL: "${MCP_LOG_LEVEL}"             # ${VAR} interpolated from the environment
    timeoutMs: 30000                            # connect/list timeout (default 30000)

  analytics:                                    # remote server over Streamable HTTP
    type: http
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ${ANALYTICS_TOKEN}"

  legacy:                                       # legacy SSE transport (deprecated)
    type: sse
    url: "https://old.example.com/sse"

При запуске gitagent подключается к каждому серверу, перечисляет его инструменты и регистрирует их как <server>__<tool> (например, filesystem__read_file, analytics__query). Соединения автоматически разрываются при завершении сессии.

Поле	Применяется к	Описание
command / args / env / cwd	stdio	Как запустить локальный сервер
type: http \| sse + url + headers	remote	Подключиться к удалённому серверу
timeoutMs	both	Таймаут подключения и получения списка инструментов (по умолчанию 30000)

Использование через SDK

import { query } from "gitagent";

for await (const msg of query({
  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 объединяются с любыми mcp_servers из agent.yaml (значение SDK переопределяет при конфликте ключей).

Поведение и гарантии

• Fail-soft: сервер, который не может запуститься (или превысил таймаут), записывается в лог и пропускается — остальные серверы и встроенные инструменты продолжают работать.
• Namespaced & sanitized: имена инструментов префиксируются именем сервера и очищаются для удовлетворения правил именования провайдера.
• Pagination: серверы, которые постранично выводят список инструментов, полностью перечисляются.
• Cleanup: серверы stdio (дочерние процессы) завершаются при любом пути выхода (обычный, /quit, Ctrl+C, ошибка).
• Lazy: если серверы не настроены, SDK MCP никогда не загружается.

---

Примечание: v1 поддерживает MCP инструменты. Ресурсы и подсказки пока не доступны.

Поддержка нескольких моделей

Gitagent работает с любым провайдером LLM, поддерживаемым pi-ai:

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

Поддерживаемые провайдеры: anthropic, openai, google, xai, groq, mistral и другие.

Наследование и композиция

Агенты могут расширять базовых агентов:

# 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

Соблюдение требований и аудит

Встроенная проверка соответствия и ведение аудитных журналов:

# 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

Аудитные журналы записываются в .gitagent/audit.jsonl с полными трассами вызовов инструментов.

Телеметрия

Gitagent поставляется с встроенной телеметрией OpenTelemetry. Установите OTEL_EXPORTER_OTLP_ENDPOINT, и телеметрия будет включена; оставьте его неустановленным, и стоимость выполнения будет равна нулю.

Три уровня сигналов:

1. Уровень HTTP — @opentelemetry/instrumentation-undici автоматически патчит fetch/undici, поэтому каждый вызов провайдера LLM (Anthropic, OpenAI, Google, …) получает клиентский спан с URL, кодом состояния и временем.
2. Спаны gen_ai.chat — выдаются на каждом конце сообщения помощника message_end. Переносит 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. Содержимое спана/метрики никогда не содержит текст подсказки или завершения.
3. Спаны gitagent.tool.execute — оборачивают каждый вызов инструмента с tool.name, tool.call_id, tool.status (ok/error) и tool.error_message при сбое.

Корневой спан gitagent.agent.session открывается при создании агента и закрывается на каждом пути выхода (успех, блокировка хука, SIGINT, ошибка).

Использование CLI

Просто установите конечную точку — без флага --import, без дополнительных шагов установки:

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

Телеметрия включается автоматически, когда конечная точка установлена, и отключается, когда она не установлена. Чтобы принудительно отключить даже при установленной конечной точке, передайте GITAGENT_OTEL_ENABLED=false.

Переменные среды

Переменная	Описание	Значение по умолчанию
OTEL_EXPORTER_OTLP_ENDPOINT	Базовый URL коллектора OTLP/HTTP (например, http://localhost:4318). Когда он установлен, телеметрия включается автоматически.	(неустановлено → телеметрия отключена)
GITAGENT_OTEL_ENABLED	Установите значение false, чтобы отключить телеметрию даже при установленной конечной точке	(неустановлено = автоматически)
OTEL_SERVICE_NAME	Имя ресурса service.name	gitagent
OTEL_SERVICE_VERSION	Версия ресурса service.version	(неустановлено)
OTEL_EXPORTER_OTLP_HEADERS	Пара ключ=значение, разделенная запятыми, без кавычек (например, Authorization=Bearer xyz,x-tenant=abc)	(неустановлено)
OTEL_TRACES_EXPORTER	Установите значение console, чтобы распечатать спаны в stdout — нет необходимости в коллекторе	(неустановлено)

Использование SDK

Для программных встроек вызовите initTelemetry явно — вы контролируете, когда происходит инициализация:

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 и OTEL_EXPORTER_OTLP_HEADERS читаются автоматически экспортером OTLP, когда они не передаются программно. Передайте exporterEndpoint / headers только тогда, когда вам нужно переопределить конфигурацию, основанную на переменных среды, в коде.

Выдаваемые спаны

Имя	Тип	Ключевые атрибуты
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, код состояния, продолжительность (автоматически из instrumentation-undici)

Выдаваемые метрики

Имя	Тип	Описание
gitagent.tool.calls	counter	Количество вызовов инструментов, помеченных именем инструмента
gitagent.tool.duration_ms	histogram	Продолжительность выполнения инструмента
gitagent.session.duration_ms	histogram	Продолжительность сессии
gitagent.session.cost_usd	counter (USD)	Кумулятивная стоимость сессии
gen_ai.client.token.usage	counter	Использование токенов по gen_ai.system, gen_ai.request.model, gen_ai.token.type
gen_ai.client.operation.duration	histogram	Продолжительность вызова LLM

Быстрый старт консоли (без коллектора)

Напечатайте спаны直接 в stdout — полезно для локальной отладки:

OTEL_TRACES_EXPORTER=console gitagent -p "test"

Быстрый старт локального Jaeger

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.md для получения рекомендаций.

❓ ЧаВо

---

Общее

Что такое Gitagent? GitAgent (ранее Gitclaw) - это фреймворк агента ИИ, родной для git, где агент ЯВЛЯЕТСЯ git-репозиторием. Идентичность, правила, память, инструменты и навыки - все это файлы, находящиеся под версионным контролем, что позволяет реализовать парадигму "агенты как репозитории".

В чем отличие Gitagent от других фреймворков агентов? В отличие от фреймворков, которые разбрасывают конфигурацию по коду приложения, Gitagent делает сам агент git-репозиторием: - Создайте fork агента → унаследуйте личность, правила, инструменты - Создайте ветку → создайте альтернативные версии личности - git log → просмотрите эволюцию памяти агента - Diff → отслеживайте изменения правил во времени

Что такое концепция "агенты как репозитории"? Ваш агент живет в git-репозитории со структурированными файлами: - agent.yaml — модель, инструменты, конфигурация среды выполнения - SOUL.md — личность и идентичность - RULES.md — ограничения поведения - memory/ — память, зафиксированная в git с полной историей - tools/ — декларативные определения инструментов в формате YAML - skills/ — модули навыков, которые можно составлять - hooks/ — хуки жизненного цикла

Установка и настройка

Какие требования? Node.js 18+ (или 20+ рекомендуется), npm и git. Установите глобально с помощью npm install -g @open-gitagent/gitagent (слим CLI + SDK). Добавьте @open-gitagent/voice для режима голоса + веб-интерфейса.

Как настроить ключи API? Запустите установщик для пошаговой настройки:

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

Или настройте вручную:

export OPENAI_API_KEY="sk-..."

Какие провайдеры LLM поддерживаются? - OpenAI (GPT-4o, GPT-4o-mini и т. д.) - Anthropic (модели Claude через родной SDK) - Любой провайдер, совместимый с OpenAI

Используйте флаг --model, чтобы переопределить: gitagent --model anthropic:claude-sonnet-4-5-20250929

Основные концепции

Что такое SDK и как его использовать? SDK предоставляет программный доступ через функцию query(), которая передает события агента:

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

Как работают сессии в локальном режиме репозитория? Клонируйте репозиторий GitHub, запустите агент на нем, автоматически зафиксируйте в ветку сессии:

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

Возобновите с помощью: gitagent --repo URL --session gitagent/session-xxx "Продолжить"

Какие хуки доступны? Хуки - это скрипты жизненного цикла или программные обработчики в директории hooks/. Они срабатывают на событиях агента, таких как выполнение инструментов, начало/окончание сессии или обновления памяти.

Разработка

Как создать пользовательские инструменты? Определите инструменты в директории tools/ с помощью декларативного формата YAML. Каждый инструмент указывает имя, описание, параметры и логiku выполнения.

Как добавить навыки? Создайте модули навыков в директории skills/. Навыки можно составлять и импортировать из установленных пакетов или определять локально.

Какие варианты телеметрии доступны? Интеграция с OpenTelemetry для наблюдаемости: - Установите OTEL_EXPORTER_OTLP_ENDPOINT для автоматического включения - Используйте OTEL_TRACES_EXPORTER=console для локальной отладки - Быстрый старт с Jaeger и Docker

Устранение неполадок

Почему мой агент не реагирует? - Проверьте, установлен ли ключ API (OPENAI_API_KEY или эквивалент) - Убедитесь в сетевом подключении к провайдеру LLM - Используйте флаг --verbose для подробных журналов - Проверьте конфигурацию модели в agent.yaml

Как отладить поведение агента? - Используйте экспортер консоли: OTEL_TRACES_EXPORTER=console gitagent -p "test" - Проверьте спаны в Jaeger: docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one - Осмотрите директорию memory/ для состояния агента

Где можно получить помощь? - Вопросы на GitHub: https://github.com/open-gitagent/gitagent/issues - Примеры: см. раздел SDK в README и варианты CLI - Вклад: см. CONTRIBUTING.md для руководства

Лицензия

Этот проект лицензирован под MIT License.