agent-brain

agent-remote-brain

CLI 에이전트(Claude Code / Codex)가 주인공인 프로젝트/티켓/태스크 추적 시스템.

터미널에서 에이전트와 대화하며 기획·구현·버그픽스를 하면 —

• 훅이 결정적으로 기록한다: git commit이 곧 태스크가 된다(자동 생성·done·코드/테스트 링크). feature 브랜치면 티켓조차 자동 생성된다. 기록 없이 턴을 끝내면 Stop 훅이 차단한다. "모델이 기억해서 저장"이 아니라 어차피 하는 행동의 부작용으로 기록되는 게 핵심.
• 결정은 RAG로 기억된다: remember로 저장된 결정이 세션 부팅 시·프롬프트마다 자동 주입된다.
• 웹 보드/지도는 읽기 전용 거울이다: 같은 Postgres를 1.5초 폴링으로 비추기만 한다. 쓰기는 항상 에이전트 경유.

설계 문서: docs/plans/260702-MCP-brain-plan.md(왜) → docs/plans/260702-MCP-brain-impl-plan.md(어떻게) 스펙: docs/specs/260702-system-spec.md · 버그 로그: docs/bugs/ · 초기 구상: docs/braindumps/

0. Quick start (Claude Code 플러그인 — 명령 3개)

claude plugin marketplace add ~/agent-remote-brain   # GitHub에 올리면 URL로
claude plugin install agent-brain@agent-brain
# 새 claude 세션에서:
/agent-brain:setup      # python env · DB(docker) · 설정파일 · 진단 원커맨드

끝. 이후 아무 레포에서 claude를 열고 "카드 입력 폼 만들자"라고 말하면 에이전트가 티켓 생성→브랜치 분기→구현→커밋까지 알아서 하고, 보드(localhost:3000)에 실시간으로 차오른다. git 명령을 직접 칠 필요가 없다.

1. 아키텍처

┌──────── 에이전트 CLI (Claude Code / Codex) ─ 호스트 ────────┐
│  대화 + 코드 편집 + git  (= 실행 엔진 그 자체)                │
└───────┬──────────────────────────────┬─────────────────────┘
        │ MCP 도구 17종 (stdio)          │ 라이프사이클 훅
        ▼                              ▼
┌────────────────┐          ┌──────────────────────────────────┐
│ mcp_server      │          │ bin/brain-launcher.sh → brain CLI │
│ (FastMCP)       │          │  SessionStart→부팅 컨텍스트 주입    │
│                 │          │  UserPromptSubmit→snapshot+recall  │
│                 │          │  PostToolUse(commit)→자동 기록      │
│                 │          │  Stop→check-sync (미기록 차단)      │
└───────┬─────────┘          └───────────────┬──────────────────┘
        │        같은 DATABASE_URL 공유        │
        ▼                                    ▼
┌──────────────────────────────────────────────┐   docker compose (name: agent-brain)
│  Postgres + pgvector (단일 진실 원본)           │ ◀─ db  :5432 (POSTGRES_PORT)
│  nodes/edges 그래프 + 원문 text + 벡터 인덱스    │
└───────────────────┬──────────────────────────┘
        읽기 전용     ▼               (단방향 md export → Obsidian, BRAIN_WIKI_ROOT)
   read_api :8000  ◀── ETag 폴링 ──  웹 뷰어 :3000 (지도+칸반+diff, 쓰기 0)

• db·read_api·뷰어는 컨테이너, MCP·brain CLI·훅은 호스트(에이전트 CLI와 당신의 git 체크아웃이 호스트에 있으므로).
• 모든 프로세스는 같은 DATABASE_URL을 공유해야 한다(단일 원본). 설정 우선순위: 셸 env > ~/.config/agent-brain/env > (editable 설치 시) 리포 .env > 기본값(in-memory SQLite).

2. 앵커 규칙 — 커밋이 어떻게 티켓/태스크가 되나

Ground rule: 1 프로젝트 = 1 세션, 세션은 프로젝트 루트에서 연다. cwd가 모든 앵커의 뿌리다 — SessionStart 부팅 주입, recall/snapshot 스코프, ensure_project 기본 감지가 전부 세션 위치를 따른다. 예외: 프로젝트 생성/부트스트랩은 어디서든 ensure_project(path=…) 명시로 가능하고, 세션 중 다른 레포로 cd하면 훅 앵커도 따라간다(의도 없인 하지 말 것).

상황	동작
feature 브랜치 + 티켓 존재 (data.branch 일치)	커밋 → 그 티켓의 태스크로 기록 (in_progress 태스크가 있으면 거기에, 없으면 커밋 제목으로 새 태스크)
feature 브랜치 + 티켓 없음	브랜치명으로 티켓 자동 생성 후 기록 (선언 의식 불필요)
set_active_ticket 지정됨	브랜치 무관 최우선 앵커 — main에서도 그 티켓으로 기록
main/master/detached + 지정 없음	의도적 무티켓 지대 — pending_commits로 쌓고 경고. 티켓이 생기면 다음 커밋 때 pending까지 자동 회수

1 태스크 = 1 커밋 컨벤션. 재적용은 멱등(같은 커밋 훅 2회 = 기록 1회).

3. 슬래시 커맨드 (플러그인)

커맨드	역할
/agent-brain:setup	원커맨드 셋업: launcher provision(venv) + docker compose up db + ~/.config/agent-brain/env 생성 + alembic + 중복 MCP 제거 + doctor 진단
/agent-brain:pipeline <braindump>	기획 파이프라인: ①결정 루프(질문→"해결된 고민(무엇을/왜)+미해결" 정리→remember, 미해결 0까지 반복, rough-{n}.md 저장) ②아키텍처+사용자 이점(합리화 금지) ③상세 기획 승인 시 기능=티켓·스텝=태스크 자동 분해
/agent-brain:drive [ticket]	Auto-drive: 백로그 상위부터 브랜치→태스크별 구현→검증→커밋→상태 즉시 갱신. 정지 조건: 막힘(blocked+사유)/사람 판단 필요(review)/같은 태스크 2회 실패/사용자 개입. 티켓 완료는 review에 두고 머지는 사람이 결정

project-tracker 스킬이 상시 규칙(recall 먼저, remember 기록, git 분기는 에이전트가)을 가이드하고, 지키지 못해도 훅이 결정적으로 잡는다.

4. 리포 구조