pit · pithub

AI가 같은 실수를 두 번 하지 않게 하는 교정 메모리. pit은 오픈소스 — 회사 서버에서. pithub는 그것을 2분 만에 켜고 팀이 같은 판단 원장을 읽는 곳.

claude.ai · Claude Code · Codex에 MCP 커넥터 하나를 붙이면, 당신이 AI의 제안을 거부하고 고치고 방향을 정한 순간이 기록됩니다. 다음 세션의 AI는 제안하기 전에 그 기록을 찾아봅니다. 대화 원문은 서버로 가지 않습니다 — 결정 한 건의 요약과 당신의 말 한 줄만 갑니다.

사용자 ──(제안을 거부/수정/선택)──▶ 세션의 AI ──record_decision──▶ pithub 원장 (본인만)
다음 세션의 AI ──search_my_decisions──▶ "지난주에 같은 방식을 재보고 폐기하셨습니다"

왜

• AI가 제안하고 사람이 "ㅇㅇ"으로 넘긴 결정이 코드와 문서에 쌓이는데, "왜 이렇게 했지?"에 아무도 답하지 못한다.

• 같은 교정을 세션마다, 도구마다 반복한다. Claude의 메모리는 Codex를 모르고, Codex는 Claude를 모른다.

• CLAUDE.md · AGENTS.md는 손으로 관리하는 결정 원장이고, 늘 낡아 있다.

Related MCP server: CONTINUITY

원칙

1. 원문은 나가지 않는다. 결정의 요약과 인용문만 저장한다. 수신 시점에 시크릿·개인정보를 가린다.

2. 회사 밖으로 나가지 않는다. 공개 기능이 없다. 팀 저장소에서 기록된 판단은 3일 뒤 팀에 보이고, 그 전에 본인이 뺄 수 있다.

3. 기록에 드는 노력은 0. 확인은 쓰는 순간(열람·팀 공유 전)에만, 품질은 주간 표본으로 잰다.

4. 내 것은 지우면 정말 사라진다. 팀에 보인 판단은 회사의 기록 — 퇴사해도 남고 팀 소유자만 지운다.

5. 트윈은 묻는 사람이 볼 수 있는 결정만큼만 안다. 경계는 프롬프트가 아니라 행 접근 권한(RLS)이다.

구성

호스팅된 pithub 쓰기

팀 관리자: 웹에서 팀을 만들고, 초대 링크를 팀 채널에 붙인다. 팀원: 링크를 누르고 GitHub로 로그인한다(바로 팀원) → 쓰는 도구에 주소 하나를 붙인다 → 평소처럼 일한다.

주소는 하나다. 팀이 하나뿐인 사람은 서버가 그 팀으로 기록한다(여러 팀이면 팀 주소 …/t/<팀>/mcp). 기록은 3일 뒤 팀에 보이고, 그 전에 정리함에서 뺄 수 있다.

직접 돌리기 (셀프호스트)

필요한 것: Python 3.11+ · uv · Postgres(Supabase 권장) · GitHub OAuth App · HTTPS 주소(claude.ai 커넥터 요건).

git clone https://github.com/playidea-lab/pit.git && cd pit
uv sync --extra server

# 1. DB — Supabase 프로젝트를 만들고 마이그레이션 적용
cd pithub/supabase && supabase link --project-ref <ref> && supabase db push && cd ../..

# 2. MCP 서버 — 환경변수로만 설정한다 (코드에 주소·비밀 없음)
export PITHUB_GITHUB_CLIENT_ID=… PITHUB_GITHUB_CLIENT_SECRET=…   # OAuth App, 콜백 https://<서버>/auth/callback
export PITHUB_MCP_BASE_URL=https://<서버> PITHUB_JWT_SIGNING_KEY=$(openssl rand -hex 32)
export PITHUB_SUPABASE_URL=https://<ref>.supabase.co PITHUB_SUPABASE_SERVICE_KEY=…
export PITHUB_OAUTH_STORAGE_DIR=/data/oauth PITHUB_OAUTH_STORAGE_KEY=<Fernet 키>   # 재배포해도 로그인 유지
uv run python -m pit.server            # 또는 Dockerfile · fly.toml

# 3. 웹
cd pithub/web && cp .env.example .env.local   # Supabase URL·anon 키·MCP 주소
npm ci && npm run build && npm start

Supabase Auth의 GitHub provider에 같은 OAuth App을 넣고, OAuth App에 Supabase 콜백 URL을 추가한다.

로그인 방식 (PITHUB_AUTH)

• github (기본): 서버가 GitHub OAuth를 중계한다. GitHub 계정만.

• supabase (권장): Supabase Auth의 OAuth 2.1 서버가 AI 도구 로그인을 맡고, 서버는 토큰만 검증한다. GitHub와 이메일(매직 링크) 모두. Supabase 대시보드에서 Authentication → OAuth Server 켜기 · Allow Dynamic OAuth Apps 켜기 · Authorization path /oauth/consent · Site URL = 웹 주소 · Providers → Email 켜기. 서버는 Supabase 없이도 뜨지만 그때는 기록 도구가 "저장소 준비 중"을 돌려준다.

로컬 CLI pit (선택, 개발자용)

원문 보존과 감사를 원하는 사람만. Claude Code 세션 원문을 개인 보관함(~/.pit)에 지워지지 않게 복사하고, 원문에서 추출한 결정과 MCP가 기록한 결정을 대조해 기록 누락률·판정 일치율을 잰다.

uv tool install git+https://github.com/playidea-lab/pit.git
PITHUB_URL=https://<서버> pit setup     # 보관함 초기화, 첫 sync, 커넥터 명령 안내
pit login                               # 웹 설정에서 발급한 토큰
pit pull && pit audit mcp               # MCP 기록 감사

watcher/ (작업 실행 쪽)

결정이 "무엇을 하기로 했나"라면 watcher 는 "그걸 어떻게 실행했나"를 본다. 사내 GitLab·GitHub 커밋과 에이전트 활동(Claude Code·Codex 텔레메트리, 요약만)을 사람·일감 단위로 모아 대표에게 일일·월간 보고를 보내고, 에이전트가 report_start/report_commit 으로 남긴 작업 보고를 독립 근거로 검증한다. 별도 패키지 — 자세한 건 watcher/README.md.

개발

uv sync --extra server
uv run ruff check pit tests && uv run pytest -q          # 단위 (200+)
docker run -d --name db -e POSTGRES_PASSWORD=x -p 55432:5432 postgres:17
PITHUB_TEST_DATABASE_URL=postgresql://postgres:x@127.0.0.1:55432/postgres uv run pytest -m integration   # RLS
cd pithub/web && npm ci && npm run lint && npm run build

테스트는 합성 데이터만 쓴다. 실제 세션 기록을 테스트에 넣지 않는다.

배포

main 에 push 하면 CI가 시험을 통과한 뒤 바뀐 부분만 운영에 올린다 (.github/workflows/ci.yml 의 deploy). 순서는 DB 마이그레이션 → MCP 서버 → 웹. 그래서 마이그레이션은 옛 서버와 함께 돌아도 깨지지 않게(확장만) 쓴다. 열·테이블을 지우는 마이그레이션은 첫 줄을 -- deploy: after-server 로 시작해 서버 배포 뒤로 미룬다.

필요한 설정: 저장소 Secrets FLY_API_TOKEN · SUPABASE_DB_PASSWORD, Variables SUPABASE_PROJECT_REF · SUPABASE_POOLER_HOST · SUPABASE_ANON_KEY(공개값) · PITHUB_MCP_URL. 계정 전체 권한인 Supabase 액세스 토큰은 쓰지 않는다 — 마이그레이션은 DB 비밀번호로 세션 풀러에 직접 붙는다. 없으면 배포 단계는 경고만 남기고 건너뛴다.

기여할 자리

• 소스 어댑터 — Codex, Gemini, Cursor 세션 기록 파서. pit/vault/sources.py의 SourceAdapter와 pit/transcripts/events.py의 EVENT_BUILDERS에 등록하면 보관·추출·감사가 그대로 돈다.

• 검색 순위·원칙 압축 — docs/PIT_KNOWLEDGE_DESIGN.md의 단계별 착수 조건을 따른다.

라이선스

AGPL-3.0-or-later. 이 코드로 호스팅 서비스를 제공하면 그 변경도 공개해야 합니다.