mikehasa/agentacct

agentacct – 코드 에이전트의 솔직한 작업 영수증

무엇인가요 – AI 코딩 보조 도구(Claude Code, Codex, OpenCode, Hermes 등)가 이미 로컬 머신에 기록하는 로그 파일을 감시하는 로컬 우선 도구입니다. 이 도구는 이러한 로그를 실제 명령어, 파일 편집, 도구 호출과 연결하여 각 작업에 대해 하나의 작업 영수증을 생성합니다. 영수증은 무엇이 수행되었는지, 비용은 얼마인지, 그리고 증거의 신뢰도는 얼마나 되는지(에이전트 주장, 자가 확인, 훅 관측, CI 검증)를 보여줍니다. 모든 데이터는 컴퓨터 내부에만 유지되며, 클라우드 서비스, 추적 데이터, API 키 처리가 없습니다.

---

핵심 개념

개념	의미
작업 영수증	작업당 감사 스타일의 기록으로, 행동, 비용, 각 주장에 대한 증거 등급을 나열합니다.
증거 등급	네 가지 등급 – 에이전트 주장 < 자기 보고된 확인 < 훅 관측된 종료 코드 < CI – 파이프 모양으로 시각화됩니다.
로컬 JSON API	다른 스크립트가 영수증을 조회할 수 있는 로컬만 허용하는 HTTP 서버(127.0.0.1:8765)입니다.
macOS 앱 / TUI	동일한 영수증을 렌더링하는 두 가지 프론트엔드(네이티브 macOS GUI 및 터미널 대시보드)입니다.

---

제공되는 기능

• 작업당 하나의 영수증 – 행동(명령어, 수정된 파일, 사용된 도구), 비용(실제 토큰 수 + 가격표 추정치), 명확한 결정/증거 분리 제공.
• 상세 탐색 뷰 – 영수증을 확장하여 모든 세션 단계, 라이프사이클, 종료 코드 확인, 출처 칩(훅, 전사, MCP 기록)을 확인할 수 있습니다.
• 증거 중심 대시보드 – 검토가 필요한 최우선 작업이 강조 표시되며, 증거 검토 버튼과 간결한 "Shift Brief"가 제공됩니다.
• 사용량 및 계획 비용 – 실시간 제공자 할당량 창, 기록된 토큰 사용량, 주간 Claude 계획에서의 추정 사용 비율(자신의 한도 기록에서 유도).
• 소유권 신뢰도 – 사용량과 작업 간의 연결은 정확, 높음, 중간, 낮음으로 레이블링되며, 누락된 연결은 추측하지 않고 명시적으로 표시됩니다.
• 프라이버시 설계 – 모든 상태는 평범한 로컬 파일(~/.local/state/agentacct/ 또는 리포지토리 로컬 .agent-sentinel/)에 저장되며, 유일한 네트워크 리스너는 로컬 JSON API뿐이며, 키는 절대 저장되거나 전송되지 않습니다.

---

설치

플랫폼	단계
macOS (GUI)	최신 릴리스에서 인증된 .dmg를 다운로드하여 Applications 폴더로 드래그한 후 실행합니다. 앱은 CLI를 포함하며 에이전트를 자동으로 온보딩합니다.
macOS / Linux (CLI)	```bash
pipx install agentacct # 또는 uv tool install agentacct
agentacct onboard # 에이전트를 감지하고 글로벌 스토어를 생성하며, 동기화 및 API를 시작합니다.
agentacct tui # 실시간 터미널 대시보드를 엽니다.

| **Windows** | WSL을 사용하고 macOS/Linux CLI 단계를 따릅니다. |

*온보딩*은 리포지토리에 파일을 하나도 쓰지 않으며, 글로벌 스토어만 생성하고 에이전트 설정 파일에 훅을 등록하여 향후 세션을 캡처합니다.

---
### 일반적인 워크플로우
1. **온보딩** – 머신당 한 번(또는 `--scope project`로 프로젝트별로).
2. 일반적인 AI 코딩 에이전트(Claude Code, Codex 등)를 실행합니다. 에이전트의 자체 로깅 훅이 세션 파일을 기록합니다.
3. `agentacct tui` (또는 macOS 앱을 열기) – 대시보드는 검토가 필요한 최우선 작업을 표시합니다.
4. 영수증에 **Enter**를 누르면 전체 감사 기록을 확인하고, 세션/단계로 드릴다운하여 각 주장에 대한 증거 등급을 검토할 수 있습니다.
5. 프로그래밍 접근이 필요하면 `http://127.0.0.1:8765/receipts`를 쿼리하거나(또는 `docs/reference.md`에 문서화된 유사 엔드포인트 사용).
6. 완료 후 `agentacct stop`으로 백그라운드 동기화를 중지하고, README에 표시된 명령어로 제거합니다.

---
### 작동 방식(개요)
- **사용량 진실** – 각 에이전트의 로컬 세션 파일에서 직접 추출됩니다(토큰 수는 `client_reported`; 비용은 내장된 가격표에서 유도).
- **작업 의미** – 에이전트가 생성하는 MCP 이벤트(`agentacct_record_section`, `agentacct_record_machine_check`)와 독립적인 확인(테스트 실행, CI)에서 수집됩니다.
- **연결** – 클라이언트 ID, 세션 ID, 전사 ID를 매칭하여 영수증을 생성하고, 각 소유권을 신뢰도 수준으로 레이블링합니다.
- **증거 등급 파이프** – 기반 확인의 독립성 등급에서 유도된 시각적 표시입니다.

---
### 누구에게 적합한가요
- AI 코딩 보조 도구에 의존하고 비용 통제 및 신뢰도 검증을 위한 **감사 기록**이 필요한 개발자.
- AI 생성 변경 사항이 실제로 실행되고 테스트를 통과했음을 **증명**해야 하는 팀.
- **프라이버시**에 관심이 있으며, SaaS 대시보드에 데이터를 전송하지 않고도 토큰 사용량을 완전히 로컬에서 확인하고 싶은 사람.

---
### 현재 상태
- 초기 알파 – 기능이 변경될 수 있습니다.
- Claude Code, Codex, OpenCode(완전한 영수증), Hermes(사용량 + 제한된 캡처), OpenClaw(사용량만), Cursor(존재만) 지원.
- macOS GUI와 완전한 터미널 TUI는 작동 중이며, Linux 사용자는 TUI를 사용할 수 있습니다.

---
### 링크 및 문서(리포지토리에 나열됨)
- **참고** – `docs/reference.md`
- **설치 가이드** – `INSTALL.md`
- **사용량 및 비용 진실 표** – `docs/usage-truth-table.md`
- **아키텍처 및 안전성** – `docs/architecture.md`, `docs/safety-boundaries.md`
- **전체 데모** – `docs/full-demo.md`

---
### 빠른 시작 예제
```bash
# CLI 설치
pipx install agentacct

# 글로벌 스토어 설정 및 백그라운드 동기화 시작
agentacct onboard

# 터미널 UI 열기
agentacct tui

이제 어떤 리포지토리에서든 Claude Code 세션을 실행하면 대시보드가 즉시 새 작업에 대한 영수증을 목록으로 표시합니다.

---

결론적으로: agentacct는 클라우드 측 구성 요소 없이, AI 코딩 에이전트가 실제로 수행한 작업, 비용, 증거의 신뢰도를 투명하게 로컬에 저장한 원장입니다.