siropkin/budi

AI 코딩 에이전트(AI coding agents)를 위한 로컬 우선 비용 분석 도구. Claude Code, Cursor, Codex, Copilot CLI, 그리고 Copilot Chat (VS Code) 전반에서 토큰과 비용이 어디에 사용되는지 확인하세요 — 레포지토리(repo), 브랜치(branch), 티켓(ticket), 파일(file) 단위로 상세히 분류됩니다.

brew install siropkin/budi/budi && budi init

기본적으로 모든 데이터는 사용자의 로컬 머신에 유지됩니다. 선택 사항인 클라우드 동기화(cloud sync)를 통해 집계된 일일 메트릭(daily metrics)을 클라우드 대시보드로 전송할 수 있지만 — 프롬프트(prompts), 코드(code), 응답(responses)은 절대 머신을 떠나지 않습니다.

클라우드 대시보드 스크린샷

개요 (Overview) — 프로젝트 및 팀 전반의 비용 가시성 확보

레포지토리 및 티켓 (Repos & Tickets) — 프로젝트, 브랜치, 티켓별 비용 상세 내역

세션 (Sessions) — 사용자의 머신 및 팀 전반의 최근 세션

모든 AI 코딩 에이전트 추적 — Claude Code, Cursor, Codex CLI, Copilot CLI, Copilot Chat (VS Code)를 한곳에서 관리
메시지당 비용 및 토큰 — 단순 세션 합계가 아닌, 모든 API 호출을 개별적으로 할당
레포지토리, 브랜치 및 티켓별 상세 분류 — 어떤 프로젝트, PR 브랜치 또는 티켓이 비용을 유발하는지 파악
세션 상태 (Session health) — 컨텍스트 비대화(context bloat), 캐시 저하(cache degradation), 비용 가속화를 감지하고 실행 가능한 팁 제공
라이브 상태 표시줄 (Live status line) — Claude Code, Cursor, VS Code에서 최근 1일 / 7일 / 30일간의 지출액을 표시 (VS Code는 Copilot Chat 및 감지된 기타 제공업체를 합산하여 표시)
클라우드 대시보드 — app.getbudi.dev에서 이용 가능하며, 개인 개발자 및 팀을 지원합니다. 선택적 동기화는 집계된 메트릭만 전송하며, 프롬프트와 코드는 절대 머신을 떠나지 않습니다.
~6 MB Rust 바이너리, 설정 불필요, 최소한의 리소스 점유

budi ← 현재 위치 |
Core Rust 데몬(daemon) 및 CLI |
budi-cloud |
app.getbudi.dev의 클라우드 대시보드 및 수집 API — 개인 개발자 및 팀용 |
budi-cursor |
VS Code / Cursor 상태 표시줄 확장 프로그램 |
budi-jetbrains |
JetBrains IDE 상태 표시줄 플러그인 (Kotlin) — Marketplace 등록됨 |
homebrew-budi |
brew install siropkin/budi/budi를 위한 Homebrew tap |
getbudi.dev |
웹사이트 및 문서 |

에이전트 (Agent)	상태 (Status)	방식 (How)
Claude Code	지원됨 (Supported)	실시간 JSONL 트랜스크립트 테일링 (Live JSONL transcript tailing)
Codex CLI	지원됨 (Supported)	실시간 트랜스크립트 테일링 (Live transcript tailing)
Cursor	지원됨 (Supported)	실시간 테일링 (Live tailing) + 사용량 API 조정 (Usage API reconciliation)
Copilot CLI	지원됨 (Supported)	실시간 트랜스크립트 테일링 (Live transcript tailing)
Copilot Chat (VS Code / Cursor)	지원됨 (Supported)	실시간 JSON/JSONL 테일링 (Live JSON/JSONL tailing) + GitHub 결제 API 조정 (GitHub Billing API reconciliation) (ADR-0092)
Copilot Chat (JetBrains)	지원됨 (Supported) (메타데이터 + 결제 API)	~/.config/github-copilot/<ide-slug>/ 경로 아래의 세션 수준 탐색 (Session-level discovery) (ADR-0093) + 턴당 비용에 대한 GitHub 결제 API 조정 (GitHub Billing API reconciliation)
Gemini CLI	보류됨 (Deferred)	#294에서 추적 중

모든 에이전트는 budi db import를 통한 일회성 과거 데이터 가져오기 (one-time historical import)도 지원합니다.

.

Homebrew (macOS / Linux) — 권장

brew install siropkin/budi/budi && budi init

Shell script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.ps1 | iex

또는 귀하의 AI 코딩 에이전트에 다음을 붙여넣으세요: https://github.com/siropkin/budi 에서 README의 설치 지침을 따라 budi를 설치하십시오.

소스 빌드, Windows 참고 사항, 버전 고정 (Version pinning)

소스에서 빌드 (From source) — Rust 툴체인 (Rust toolchain) 필요

git clone https://github.com/siropkin/budi.git && cd budi && ./scripts/install.sh

Windows 소스 빌드 (PowerShell):

git clone https://github.com/siropkin/budi.git
cd budi
cargo build --release --locked
...

바이너리는 %LOCALAPPDATA%\budi\bin에 설치됩니다.

.
설치 후 터미널을 재시작하십시오.

버전 고정 (Version pinning): curl 명령 실행 전에 VERSION=v8.2.1을 설정하거나, PowerShell에서는 $env:VERSION="v8.2.1"을 설정하십시오.

PATH에 한 번만 설치하십시오. Homebrew와 ~/.local/bin을 혼용하지 마십시오. budi와 budi-daemon 버전이 일치하지 않으면 데몬 재시작이 실패합니다. budi init은 중복이 감지되면 경고를 표시합니다.

# 1. 설치 및 초기화 (데몬 시작, 상태 표시줄 설치, 에이전트 감지)
brew install siropkin/budi/budi && budi init
# 2. 에이전트를 정상적으로 사용 — budi가 트랜스크립트(transcripts)를 자동으로 테일링(tails)합니다
...

budi init

데몬(daemon)을 시작하고, 플랫폼 자동 시작 서비스(autostart service)를 설치하며, Claude Code 상태 표시줄(status line)과 Cursor 확장 프로그램(extension)을 연결합니다. 셸 프로필(shell profiles)이나 에디터 설정(editor settings)을 패치하지는 않습니다. 엔드 투 엔드(end-to-end) 상태를 확인하려면 언제든지 budi doctor를 실행하세요.

budi status # 데몬 상태 + 오늘의 비용
budi stats # 비용 및 토큰 요약
budi stats projects # 비용 기준 순위가 매겨진 레포지토리(repos)
...

데이터 명령은 스크립팅을 위해 --period today|week|month|all (또는 7d, 2w, 1m과 같은 상대적 값) 및 --format json을 허용합니다. 전체 CLI 레퍼런스는 아래를 참조하세요.

budi init은 Claude Code와 Cursor에 실시간 비용 표시를 자동으로 연결합니다 (--no-integrations를 전달하여 건너뛸 수 있습니다).

budi · $1.24 1d · $8.50 7d · $32.10 30d

Windows에서는 자정에 달력 기준으로 초기화되지 않는 이동 평균(rolling) 1d / 7d / 30d를 보여줍니다. ~/.config/budi/statusline.toml을 통해 사용자 정의할 수 있습니다:

slots = ["1d", "7d", "30d"] # 기본 quiet 프리셋
# slots = ["session", "message"] # 세션 + 마지막 메시지 비용
# slots = ["session", "message", "1d"] # 세션 + 메시지 + 이동 평균 1d

사용 가능한 슬롯(slots): 1d, 7d, 30d, session, message, branch, project, provider.

budi init은 또한 ~/.claude/skills/budi/SKILL.md에 아주 작은 Claude Code 스킬(skill)을 생성합니다. Claude Code 내부에서 /budi를 입력하면 전역적인 "최신" 세션이 아닌, 이 프로젝트의 현재 세션에 대한 실시간 활력 지표(vitals) — 컨텍스트 팽창(context bloat), 캐시 히트율(cache hit rate), 재시도 루프(retry loops), 비용 가속(cost acceleration) — 를 확인할 수 있습니다. 이 스킬은 여러 프로젝트에 걸쳐 여러 Claude Code 창이 열려 있는 경우에도 올바른 세션을 찾아내는데, 이는 세션 확인(resolution)이 전역적인 최신성(global recency)이 아닌 현재 작업 디렉토리(current working directory)로 범위가 지정(scoped)되기 때문입니다. 터미널에서의 동일한 명령어는 budi sessions current입니다. budi init에 --no-integrations를 전달할 수 있습니다.

거부하려면, 또는 나중에 설치하려면 budi integrations install --with claude-code-budi-skill을 사용하세요.

기본적으로 비활성화되어 있습니다. 두 개의 명령어로 설정을 완료하세요:

budi cloud init --api-key budi_your_key_here # app.getbudi.dev → Settings에서 키를 가져오세요
budi init # 설정을 적용하기 위해 데몬 (daemon) 재시작
budi cloud status # 확인: state: ready

사전 집계된 일일 롤업 (daily rollups)만 동기화됩니다 — 프롬프트 (prompts), 코드 (code), 응답 (responses)은 절대 사용자의 기기를 떠나지 않습니다. 자세한 내용은 개인정보 보호 (Privacy) 섹션을 참조하세요.

Budi는 로컬 우선 (local-first) 방식입니다. 모든 데이터는 ~/.local/share/budi/ (Unix) 또는 %LOCALAPPDATA%\budi (Windows)에 저장됩니다. 데몬 (daemon)은 에이전트 (agent)가 이미 디스크에 기록하고 있는 트랜스크립트 (transcript) 파일을 읽어 타임스탬프 (timestamps), 토큰 수 (token counts), 모델 이름 (model names), 비용 (costs), 속성 태그 (attribution tags)와 같은 파생된 분석 데이터를 저장합니다. 프롬프트, 코드, 응답은 절대 저장되거나 전송되지 않습니다.

클라우드 동기화 (Cloud sync, 선택 사항)는 수치적 집계 데이터 — 토큰 수, 비용, 모델 이름, 해시된 리포지토리 ID (hashed repo IDs), 브랜치 이름 (branch names), 티켓 ID (ticket IDs) — 만 전송합니다. 원시 페이로드 (Raw payloads), 파일 내용, 이메일 주소는 모든 동기화 페이로드에서 구조적으로 제외됩니다. 전체 개인정보 보호 계약에 대해서는 ADR-0083을 참조하세요.

설정 후 데이터 확인:

budi status — 데몬 (daemon) 상태 확인
budi doctor — 트랜스크립트 (transcript) 가시성 확인

• 에이전트 (agent)에 프롬프트를 보낸 후 budi stats를 확인하세요.
• 과거 데이터의 경우:
  budi db import

데몬 (daemon)이 시작되지 않을 때:

lsof -i :7878 # 포트가 사용 중인지 확인
pkill -f "budi-daemon" # 오래된 프로세스 종료
budi init # 재시작

Windows: Get-NetTCPConnection -LocalPort 7878 -State Listen / taskkill /IM budi-daemon.exe /F

Claude Code에서 상태 라인 (Status line)이 표시되지 않을 때:

budi integrations list
budi integrations install --with claude-code-statusline
# 그 다음 Claude Code 재시작

Cursor 확장 프로그램이 오프라인이거나 반응이 없을 때:
budi doctor를 실행한 다음, Cursor에서 Budi: Refresh Status를 실행하세요. Cursor 채팅을 한 번 열어 로컬 세션 (local session) 파일이 생성되도록 한 뒤, budi status를 다시 확인하세요.

재부팅 후 데몬 (daemon)이 유지되지 않을 때: budi autostart status — 설치되어 있지 않다면 budi autostart install을 실행하세요.

budi uninstall # 데몬(daemon) 중지, autostart, 상태 표시줄(status line), 설정 및 데이터 제거
budi uninstall --keep-data # 분석 데이터베이스(analytics database) 보존

바이너리(binaries)를 별도로 제거하기:

brew uninstall budi # Homebrew
rm ~/.local/bin/budi ~/.local/bin/budi-daemon # 쉘 스크립트(shell script) 설치
# Windows: irm https://raw.githubusercontent.com/siropkin/budi/main/scripts/uninstall-standalone.ps1 | iex

저장소(Repository) 안내는 각 대상(audience)에 맞춰 네 개의 최상위 파일로 나뉘어 있습니다:

README.md

— 최종 사용자(end-user) 설치, 사용법 및 데몬(daemon) API 표면(API surface) (현재 위치).

CONTRIBUTING.md

— 로컬 품질 검사(local quality checks), 공급망 정책(supply-chain policy), PR 워크플로(PR workflow).

SOUL.md

— 표준 아키텍처(canonical architecture), 데이터 흐름(data flow), 속성 계약(attribution contract), 릴리스 흐름(release flow) 및 AI 에이전트(AI-agent) 가이드.

AGENTS.md

/CLAUDE.md

— AI 도구(AI tooling)를 SOUL.md로 리다이렉트(redirect)하는 얇은 호환성 포인터(compatibility pointers).

ADR(Architecture Decision Records)은 docs/adr/에 있습니다.

CI(Continuous Integration)가 모든 PR에서 실행하는 6가지 검사(issue #808):

cargo fmt --all -- --check # 포맷팅 (formatting)
cargo clippy --workspace --all-targets --locked -- -D warnings # 린트 (lints)
cargo test --workspace --locked # 테스트 (tests)
...

지원 도구의 1회성 설치:

rustup toolchain install nightly # cargo-udeps 용
cargo install cargo-udeps cargo-machete cargo-deny --locked

전체 CLI 레퍼런스 (Full CLI reference)

실행 및 온보딩 (Launch and onboarding):

budi init # 데몬 시작 + autostart 설치 + 감지된 에이전트 표시
budi db import # 과거 트랜스크립트(transcripts) 1회성 가져오기 (에이전트별 진행 상황 표시)
budi db import --format json # 에이전트별 파일/메시지 세부 내역을 포함한 JSON 출력 (스크립팅 용)

모니터링 및 분석 (Monitoring and analytics):

budi status # 빠른 개요: 데몬 및 오늘의 비용
budi stats # 비용 세부 내역을 포함한 사용 요약
budi stats models # 모델 사용 세부 내역
...

진단 및 유지보수 (Diagnostics and maintenance):

budi doctor # 상태 확인: 데몬, 테일러(tailer), 스키마(schema), 트랜스크립트 가시성
budi doctor --deep # 전체 SQLite integrity_check 실행 (더 느림)
budi doctor --format json # 스크립팅을 위한 JSON 출력
...

데이터 뷰 (Data views)는 --period today|week|month|all (또는 7d, 2w, 1m과 같은 상대적 값) 및 스크립팅을 위한 --format json을 허용합니다. 사이드 이펙트가 발생하는 명령 (init, update, uninstall, db check, cloud init, integrations install)은 --format json을 지원하지 않습니다.

budi 비교

비교 항목	budi	ccusage	Claude /cost
멀티 에이전트 지원 (Multi-agent support)	지원 (Claude Code, Codex CLI, Cursor, Copilot CLI, Copilot Chat)	Claude Code만 지원	Claude Code만 지원
실시간 로컬 트랜스크립트 테일링 (Live local transcript tailing)	지원	미지원	미지원
비용 이력 (Cost history)	메시지별 + 일간	세션별	현재 세션만
클라우드 대시보드 (Cloud dashboard)	지원 (app.getbudi.dev)	미지원	미지원
상태 라인 + 세션 상태 (Status line + session health)	지원 (실행 가능한 팁 포함)	미지원	미지원
비용 귀속 (Cost attribution) (branch/ticket/file)	지원	미지원	미지원
개인정보 보호 (Privacy)	로컬 우선, 선택적 클라우드 동기화 (집계 데이터만)	로컬	내장형
설정 (Setup)	budi init	npx ccusage	내장형
구축 언어 (Built with)	Rust	TypeScript	—

아키텍처 (Architecture)

┌──────────┐ HTTP ┌──────────────┐ SQLite ┌──────────┐
│ budi CLI │ ──────────▶ │ budi-daemon │ ───────────▶ │ budi.db │
└──────────┘ │ (port 7878) │ └──────────┘
...

경량 Rust 데몬 (port 7878)이 단일 SQLite 데이터베이스를 관리합니다. 데몬은 각 제공업체(provider)의 로컬 트랜스크립트 루트를 감시하고, 공유 파이프라인을 통해 증분 추가(incremental appends)를 테일링(tailing)하며, 정형화된 messages 및 태그(tag) 행을 기록합니다. CLI는 얇은 HTTP 클라이언트이며, 데이터베이스에 직접 접근하지 않습니다.

데이터 모델 (Data model):

테이블 (Table)	역할 (Role)
messages	API 호출당 하나의 행 — 모든 토큰/비용 데이터
sessions	생명주기 컨텍스트 (시작/종료, 지속 시간, 모드)
tags	메시지당 유연한 키-값(key-value) 쌍
sync_state	증분 수집 진행 상황 + 클라우드 동기화 워터마크
message_rollups_hourly	빠른 읽기를 위한 파생된 시간별 집계 데이터
message_rollups_daily	요약 스캔을 위한 파생된 일간 집계 데이터

전체 아키텍처, 데이터 흐름 및 모듈 경계에 대해서는 SOUL.md를 참조하세요.

데몬 API (Daemon API)

데몬은 http://127.0.0.1:7878에서 실행됩니다.

권한이 필요한 경로 (/admin/*, POST /sync*)는 루프백(loopback) 전용입니다.

시스템 (System):

메서드 (Method)	엔드포인트 (Endpoint)	설명 (Description)
GET	/health	상태 확인 (Health check)
POST	/sync	최근 데이터 동기화 (loopback-only)
POST	/sync/all	전체 트랜스크립트(transcript) 기록 로드 (loopback-only)
POST	/sync/reset	동기화 상태 삭제 + 전체 재동기화 (loopback-only)
GET	/sync/status	동기화 플래그 (Syncing flag) + 마지막 동기화 시간 (last_synced)

분석 (Analytics):