Gitagent: 범용적인 깃 네이티브 멀티모달 항상 학습하는 AI 에이전트

<img src="https://raw.githubusercontent.com/open-gitagent/gitagent/HEAD/gitagent-logo.png" alt="GitAgent Logo" width="200" /> <img src="https://img.shields.io/npm/v/gitagent?style=flat-square&color=blue" alt="npm version" /> <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version" /> <img src="https://img.shields.io/github/license/open-gitagent/gitagent?style=flat-square" alt="license" /> <img src="https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript&logoColor=white" alt="typescript" /> <h1 align="center">Gitagent</h1> 범용적인 깃 네이티브 멀티모달 항상 학습하는 AI 에이전트 (TinyHuman) 사용자의 에이전트는 Git 저장소 내에 존재합니다. 정체성(identity), 규칙(rules), 메모리(memory), 도구(tools), 스킬(skills) 모두 버전 관리되는 파일입니다. <a href="#one-command-install">설치 (Install)</a> • <a href="#quick-start">빠른 시작 (Quick Start)</a> • <a href="#sdk">SDK</a> • <a href="#architecture">아키텍처 (Architecture)</a> • <a href="#tools">도구 (Tools)</a> • <a href="#hooks">훅 (Hooks)</a> • <a href="#skills">스킬 (Skills)</a> • <a href="#plugins">플러그인 (Plugins)</a>

Gitagent를 사용해야 하는 이유?

대부분의 에이전트 프레임워크는 구성을 애플리케이션 전반에 흩어져 있는 코드로 취급합니다. Gitagent는 이를 뒤집습니다 — 사용자의 에이전트는 그 자체가 Git 저장소입니다:

agent.yaml — 모델, 도구, 런타임 구성(runtime config)
SOUL.md — 개성과 정체성(personality and identity)
RULES.md — 행동 제약 조건(behavioral constraints)
memory/ — 전체 기록을 가진 Git 커밋 메모리
tools/ — 선언적 YAML 도구 정의
skills/ — 조합 가능한 스킬 모듈
hooks/ — 라이프사이클 훅 (스크립트 또는 프로그래밍 방식)

에이전트를 포크(fork)하세요. 개성을 브랜치(branch)하세요. 에이전트의 메모리를 git log로 확인하세요. 규칙을 디프(diff)하세요. 이것이 바로 **저장소로서의 에이전트 (agents as repos)**입니다.

원클릭 설치 (One-Command Install)

복사, 붙여넣기, 실행. 끝입니다 — 클론(cloning)이나 수동 설정이 필요 없습니다. 설치 프로그램이 모든 것을 처리합니다:

이 명령어는 다음 작업을 수행합니다:

npm을 통해 gitagent를 전역적으로 설치합니다.
API 키 설정 과정을 안내합니다 (Quick 또는 Advanced 모드).
브라우저에서 http://localhost:3333에 음성 UI(voice UI)를 실행합니다.

필수 요구 사항: Node.js 18 이상, npm, git

수동 설치 방법:

# Slim CLI + SDK (공급망 스캐너가 더 큰 번들을 거부하는 격리된/CI 환경에서 권장)
npm install -g @open-gitagent/gitagent
...

install.sh는 기본적으로 두 패키지 모두를 설치합니다. 음성 기능을 건너뛰려면 curl-bash 실행 전에 GITAGENT_SLIM=1을 설정하세요.

1.x → 2.0 버전 마이그레이션

음성 모드(Voice mode)는 이제 @open-gitagent/voice에 위치합니다. 그 이유는 단일 번들로 구성되었던 패키지가 3,800줄의 dist/voice/ui.html과 사용되지 않는 baileys 의존성 때문에 일부 공급망 스캐너(supply-chain scanners)에 의해 차단되고 있었기 때문입니다. 음성을 분리함으로써 slim-core tarball 크기가 약 180 kB에서 약 85 kB로 줄어들고, 스캐너가 감지하는 트리거를 완전히 제거할 수 있습니다.

# v1.x를 사용했으며 음성 기능을 사용했던 경우:
pm install -g @open-gitagent/gitagent@latest @open-gitagent/voice
...

gitagent 명령어와 @open-gitagent/gitagent SDK 내보내기(exports)는 변경되지 않았습니다. gitagent --voice는 @open-gitagent/voice를 동적으로 로드하며, 이 패키지가 설치되어 있지 않으면 한 줄짜리 설치 힌트를 출력하고 깨끗하게 종료됩니다.

빠른 시작 (Quick Start)

한 줄로 첫 번째 에이전트 실행하기:

export OPENAI_API_KEY="sk-..."
gitagent --dir ~/my-project "이 프로젝트를 설명하고 개선 사항을 제안해 줘"

끝입니다. Gitagent는 첫 실행 시 agent.yaml, SOUL.md, memory/ 등 모든 것을 자동으로 스캐폴딩(auto-scaffolds)하며, 사용자를 에이전트 환경으로 안내합니다.

로컬 레포 모드 (Local Repo Mode)

GitHub 리포지토리를 클론하고, 해당 리포에 대해 에이전트를 실행한 후, 세션 브랜치에 자동으로 커밋 및 푸시할 수 있습니다:

gitagent --repo https://github.com/org/repo --pat ghp_xxx "로그인 버그를 수정해 줘"

기존 세션을 재개하려면:

gitagent --repo https://github.com/org/repo --pat ghp_xxx --session gitagent/session-a1b2c3d4 "계속 진행해 줘"

토큰은 --pat 대신 환경 변수(env)에서 가져올 수 있습니다:

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

CLI 옵션 (CLI Options)

플래그 (Flag)	단축키 (Short)	설명 (Description)
`--dir <path>`	`-d`	에이전트 디렉토리 (기본값: 현재 작업 디렉토리, cwd)
...

SDK

import { query } from "gitagent";

// 간단한 쿼리 실행
...

SDK

SDK는 Gitagent 에이전트에 대한 프로그래밍 인터페이스를 제공합니다. 이는 Claude Agent SDK 패턴을 따르지만, **인프로세스(in-process)**로 실행됩니다—서브 프로세스나 IPC가 필요 없습니다.

`query(options): Query`

에이전트 이벤트를 스트리밍하는 AsyncGenerator<GCMessage>를 반환합니다.

import { query } from "gitagent";

for await (const msg of query({
...

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

에이전트가 호출할 수 있는 사용자 정의 도구를 정의합니다:

import { query, tool } from "gitagent";

const search = tool(
...

훅 (Hooks)

게이팅(gating), 로깅(logging), 제어(control)를 위한 프로그래밍 방식의 생명주기 훅입니다:

for await (const msg of query({
  prompt: "Deploy the service",
  hooks: {
...

QueryOptions 참조

옵션 (Option)	타입 (Type)	설명 (Description)
`prompt`	`string	AsyncIterable`
...

메시지 유형 (Message Types)

유형 (Type)	설명 (Description)	주요 필드 (Key Fields)
`delta`	스트리밍 텍스트/사고 청크 (thinking chunk)	`deltaType`, `content`
...

아키텍처 (Architecture)

my-agent/
├── agent.yaml          # 모델, 도구, 런타임 설정
├── SOUL.md             # 에이전트 정체성 및 성격
...

에이전트 매니페스트 (`agent.yaml`)

spec_version: "0.1.0"
name: my-agent
version: 1.0.0
...

도구 (Tools)

내장 도구 (Built-in Tools)

도구 (Tool)	설명 (Description)
`cli`	셸 명령어 실행
...

선언적 도구 (Declarative Tools)

tools/ 디렉토리에 YAML 형식으로 도구를 정의합니다:

# tools/search.yaml
name: search
description: 코드베이스 검색
...

스크립트는 표준 입력(stdin)에서 JSON 형태로 인수를 받고, 표준 출력(stdout)으로 결과를 반환합니다.

훅 (Hooks)

hooks/hooks.yaml에 있는 스크립트 기반 훅:

hooks:
  on_session_start:
    - script: validate-env.sh
...

훅 스크립트는 표준 입력(stdin)으로 JSON 형식의 컨텍스트를 받고 다음 중 하나를 반환합니다:

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

스킬 (Skills)

스킬은 skills/<name>/에 있는 조합 가능한 명령어 모듈입니다:

skills/
  code-review/
    SKILL.md
...

---
name: code-review
description: Review code for quality and security
...

CLI를 통해 호출: /skill:code-review Review the auth module

플러그인 (Plugins)

플러그인은 도구(tools), 훅(hooks), 스킬(skills), 프롬프트(prompts), 메모리 레이어 등을 제공할 수 있는 재사용 가능한 확장 기능입니다. 이들은 동일한 git-native 철학을 따르며, 플러그인은 plugin.yaml 매니페스트가 포함된 디렉토리입니다.

CLI 명령어

# git URL에서 설치
gitagent plugin install https://github.com/org/my-plugin.git

...

플래그	설명
`--name <name>`	사용자 정의 플러그인 이름 (기본값: 소스에서 파생)
...

플러그인 매니페스트 (`plugin.yaml`)

id: my-plugin                    # 필수, kebab-case
name: My Plugin
version: 0.1.0
...

`agent.yaml` 내 플러그인 설정

plugins:
  my-plugin:
    enabled: true
...

설정 해상도 우선순위: agent.yaml config > env var > manifest default.

검색 순서 (Discovery Order)

플러그인은 다음 순서로 검색되며, 먼저 일치하는 것이 적용됩니다:

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

프로그래밍 방식 플러그인 (Programmatic Plugins)

매니페스트에 entry 필드가 있는 플러그인은 전체 API를 얻습니다:

// index.ts
import type { GitagentPluginApi } from "gitagent";

...

사용 가능한 API 메서드:

메서드	설명
`registerTool(def)`	에이전트가 호출할 수 있는 도구 등록
...

my-plugin/
├── plugin.yaml # 매니페스트 (필수)
├── tools/ # 선언적 도구 정의
...

MCP (Model Context Protocol)

Gitagent는 MCP 클라이언트입니다. 이를 모든 MCP 서버에 연결하기만 하면, 해당 서버의 도구가 자동으로 발견되어 에이전트에서 사용 가능해집니다. 별도의 통합 코드를 작성할 필요가 없습니다. 이를 통해 파일 시스템(filesystem), GitHub, Postgres, Slack, fetch 등 준비된 모든 생태계를 활용할 수 있습니다.

`agent.yaml`에 서버 구성하기

mcp_servers:
  filesystem:                                   # stdio를 통한 로컬 서버 (기본값)
    command: npx
...

Gitagent는 시작 시 각 서버에 연결하고, 해당 서버의 도구 목록을 가져와 <서버명>__<도구명> 형식으로 등록합니다. (예: filesystem__read_file, analytics__query). 세션이 종료되면 연결은 자동으로 끊어집니다.

필드	적용 대상	설명
`command` / `args` / `env` / `cwd`	stdio	로컬 서버를 실행하는 방법
...

SDK를 통해 사용하기

import { query } from "gitagent";

for await (const msg of query({
...

SDK의 mcpServers는 agent.yaml의 mcp_servers와 병합됩니다. (키 충돌 시 SDK 값이 우선합니다.)

동작 방식 및 보장 사항

Fail-soft: 시작할 수 없거나 시간 초과가 발생한 서버는 로그로 기록되고 건너뛰어지며, 다른 서버와 내장 도구들은 계속 작동합니다.
네임스페이스 및 정제(Namespaced & sanitized): 도구 이름은 서버 이름으로 접두사가 붙고 제공자 명명 규칙을 충족하도록 정리됩니다.
페이지네이션(Pagination): 도구 목록에 페이지네이션이 적용되는 서버도 완전히 열거됩니다.
정리(Cleanup): stdio 서버(자식 프로세스)는 모든 종료 경로(정상 종료, /quit, Ctrl+C, 오류)에서 종료됩니다.
지연 로딩(Lazy): 서버가 구성되지 않은 경우, MCP SDK는 절대 로드되지 않습니다.

참고: v1은 MCP **도구(tools)**를 지원합니다. 리소스나 프롬프트는 아직 노출되지 않았습니다.

멀티 모델 지원 (Multi-Model Support)

Gitagent는 pi-ai가 지원하는 모든 LLM 제공업체와 함께 작동합니다:

Supported providers는 anthropic, openai, google, xai, groq, mistral 등을 포함하여 지원됩니다.

상속 및 구성 (Inheritance & Composition)

에이전트는 기본 에이전트(base agents)를 확장할 수 있습니다:

# agent.yaml
extends: "https://github.com/org/base-agent.git"

...

규정 준수 및 감사 (Compliance & Audit)

내장된 규정 준수 검증(compliance validation) 및 감사 로깅(audit logging) 기능:

# agent.yaml
compliance:
  risk_level: high
...

감사 로그는 전체 도구 호출 추적(full tool invocation traces)과 함께 .gitagent/audit.jsonl에 기록됩니다.

원격 측정 (Telemetry)

Gitagent는 내장된 OpenTelemetry 계측(instrumentation) 기능을 제공합니다. OTEL_EXPORTER_OTLP_ENDPOINT를 설정하면 원격 측정이 활성화되며, 이 변수를 설정하지 않으면 런타임 비용은 발생하지 않습니다.

세 가지 계층의 신호(signals)가 기록됩니다:

HTTP 레벨 — @opentelemetry/instrumentation-undici는 fetch/undici를 자동 패치하여, 모든 LLM 제공업체 호출(Anthropic, OpenAI, Google 등)에 대해 URL, 상태 코드, 타이밍이 포함된 클라이언트 스팬(client span)을 생성합니다.
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가 포함됩니다. 스팬/메트릭 내용은 프롬프트나 완료 텍스트를 절대 포함하지 않습니다.
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를 전달하세요.

환경 변수

Variable	Description	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP/HTTP 컬렉터 기본 URL (예: `http://localhost:4318`). 설정하면 텔레메트리(telemetry)가 자동 활성화됩니다.	(설정 안 함 → 텔레메트리 비활성화)
...

SDK 사용법

프로그램적으로 임베드하는 경우, initTelemetry를 명시적으로 호출해야 합니다. 초기화 시점을 사용자가 제어할 수 있습니다:

import { initTelemetry, shutdownTelemetry, query } from "gitagent";

await initTelemetry({ serviceName: "my-app" });
...

Gitagent: 범용적인 깃 네이티브 멀티모달 항상 학습하는 AI 에이전트

요약

핵심 포인트

Gitagent를 사용해야 하는 이유?

원클릭 설치 (One-Command Install)

수동 설치 방법:

1.x → 2.0 버전 마이그레이션

빠른 시작 (Quick Start)

로컬 레포 모드 (Local Repo Mode)

CLI 옵션 (CLI Options)

SDK

SDK

query(options): Query

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

훅 (Hooks)

QueryOptions 참조

메시지 유형 (Message Types)

아키텍처 (Architecture)

에이전트 매니페스트 (agent.yaml)

도구 (Tools)

내장 도구 (Built-in Tools)

선언적 도구 (Declarative Tools)

훅 (Hooks)

스킬 (Skills)

플러그인 (Plugins)

CLI 명령어

플러그인 매니페스트 (plugin.yaml)

agent.yaml 내 플러그인 설정

검색 순서 (Discovery Order)

프로그래밍 방식 플러그인 (Programmatic Plugins)

MCP (Model Context Protocol)

agent.yaml에 서버 구성하기

SDK를 통해 사용하기

동작 방식 및 보장 사항

멀티 모델 지원 (Multi-Model Support)

상속 및 구성 (Inheritance & Composition)

규정 준수 및 감사 (Compliance & Audit)

원격 측정 (Telemetry)

CLI 사용법

환경 변수

SDK 사용법

댓글

Gitagent를 사용해야 하는 이유?

원클릭 설치 (One-Command Install)

수동 설치 방법:

1.x → 2.0 버전 마이그레이션

빠른 시작 (Quick Start)

로컬 레포 모드 (Local Repo Mode)

CLI 옵션 (CLI Options)

SDK

SDK

query(options): Query

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

훅 (Hooks)

QueryOptions 참조

메시지 유형 (Message Types)

아키텍처 (Architecture)

에이전트 매니페스트 (agent.yaml)

도구 (Tools)

내장 도구 (Built-in Tools)

선언적 도구 (Declarative Tools)

훅 (Hooks)

스킬 (Skills)

플러그인 (Plugins)

CLI 명령어

플러그인 매니페스트 (plugin.yaml)

agent.yaml 내 플러그인 설정

검색 순서 (Discovery Order)

프로그래밍 방식 플러그인 (Programmatic Plugins)

MCP (Model Context Protocol)

agent.yaml에 서버 구성하기

SDK를 통해 사용하기

동작 방식 및 보장 사항

멀티 모델 지원 (Multi-Model Support)

상속 및 구성 (Inheritance & Composition)

규정 준수 및 감사 (Compliance & Audit)

원격 측정 (Telemetry)

CLI 사용법

환경 변수

SDK 사용법

`query(options): Query`

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

에이전트 매니페스트 (`agent.yaml`)

플러그인 매니페스트 (`plugin.yaml`)

`agent.yaml` 내 플러그인 설정

`agent.yaml`에 서버 구성하기

`query(options): Query`

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

에이전트 매니페스트 (`agent.yaml`)

플러그인 매니페스트 (`plugin.yaml`)

`agent.yaml` 내 플러그인 설정

`agent.yaml`에 서버 구성하기