janole/session-bandit

사전 요구 사항

Session Bandit은 시스템에 설치되어야 하는 CLI 도구입니다. 사용 가능한지 확인하세요:

command -v session-bandit

설치되지 않은 경우, 전역으로 설치하세요:

npm install -g session-bandit

패키지가 아직 npm에 없는 경우, 소스에서 설치하세요:

git clone https://github.com/janole/session-bandit.git
cd session-bandit
pnpm install
pnpm -r build
npm install -g packages/cli

Node.js 22+ 및 pnpm 10+가 필요합니다 (소스에서 빌드할 때만; npm 설치는 Node.js만 있으면 됩니다).

설치를 확인하세요:

session-bandit --version

Session Bandit이 하는 일

Session Bandit은 코딩 에이전트(Claude Code, Codex, BotBandit)가 디스크에 JSONL로 기록한 세션 기록을 인덱싱합니다. 완전히 오프라인으로 작동하며 — API 호출, 인증, 네트워크가 필요 없습니다. 기본적으로 ~/.claude/projects/, ~/.codex/sessions/, ~/.botbandit/sessions/를 스캔합니다.

출력 모드

Session Bandit을 에이전트 도구로 사용할 때는 기본 기계 판독 가능 출력을 선호하세요:

• list 와 search 는 기본적으로 JSON 라인을 출력합니다.
• extract, redact-check, doctor 는 기본적으로 JSON을 출력합니다.
• show 는 사람이 읽을 수 있는 트랜스크립트를 출력합니다.

사람이 읽을 수 있는 터미널 보기가 브라우징이나 사용자에게 보고할 때 유용한 경우에만 --pretty를 사용하세요. 핸드오프나 메모 노트를 위한 구조화된 입력으로 구문 분석하거나 사용하려는 명령에는 --pretty를 추가하지 마세요.

명령어

세션 목록 조회

# 모든 세션 나열, 최신순 (JSON 라인)
session-bandit list

# 중요도 계층이 포함된 사람이 읽을 수 있는 테이블
session-bandit list --pretty

# 에이전트 또는 프로젝트로 필터링
session-bandit list --agent codex --project botbandit

# 내용/중요도별 정렬 (무거운 세션 먼저)
session-bandit list --sort importance

# 사소한 세션 제외
session-bandit list --min-importance moderate

# 특정 기간으로 제한: 상대적 (7d, 24h, 2w, 3m) 또는 절대 날짜
session-bandit list --since 7d
session-bandit list --since 2026-06-01 --until 2026-06-15

세션 트랜스크립트 보기

# 전체 ID 또는 접두사 일치
session-bandit show 342647fa-5bf
session-bandit show 342647fa --agent claude

세션 간 검색

session-bandit search "tool approval"
session-bandit search "apply_patch" --agent codex
session-bandit search "adapter" --since 3d --pretty

세션 다이제스트 추출 (핸드오프/메모리를 위한 핵심 기능)

# 구조화된 다이제스트 (JSON) — 내용 점수, 파일, 명령어, 오류, 주요 전환점
session-bandit extract 342647fa-5bf

# 보낼 준비가 된 합성 프롬프트로 다이제스트 감싸기
session-bandit extract 342647fa-5bf --prompt handoff
session-bandit extract 342647fa-5bf --prompt memory

# 다이제스트에 전체 트랜스크립트 포함
session-bandit extract 342647fa-5bf --full --prompt handoff

파싱 상태 확인

session-bandit doctor
session-bandit doctor --agent codex
session-bandit doctor --agent botbandit

게시 전 편집 확인

# 기본적으로 JSON 보고서
session-bandit redact-check 342647fa-5bf

# 사용자와 검토할 사람이 읽을 수 있는 보고서
session-bandit redact-check 342647fa-5bf --pretty

# 더 보수적인 미리보기
session-bandit redact-check 342647fa-5bf --redact strict

검토/게시를 위한 마크다운 내보내기

session-bandit export-md 342647fa-5bf --out ./session.md
session-bandit export-md 342647fa-5bf --out ./session.md --report-out ./redaction-report.json
session-bandit export-md 342647fa-5bf --out ./session.md --title "Apple Watch 인터페이스"

export-md는 기본적으로 --redact cautious를 사용합니다. 사용자가 명시적으로 요청하고 위험을 수락하지 않는 한 공개 아티팩트에 --redact none을 사용하지 마세요; CLI는 해당 모드에 --yes가 필요합니다.

세션 게시

코딩 세션 게시를 요청받으면 Session Bandit을 결정론적이고 오프라인 상태로 유지하세요. CLI를 사용하여 편집된 마크다운 아티팩트와 편집 보고서를 생성하고, 세션 선택, 제목/슬러그 선택, 선택적 산문 다듬기, 사용자에게 위험 보고에는 에이전트 판단만 사용하세요.

1. 원본 세션을 찾으세요. 사용자가 세션 ID를 제공하면 직접 사용하세요. 그렇지 않으면 가능성 있는 세션을 검색하거나 나열하세요:

   session-bandit list --sort importance
   session-bandit search "주제"
   

   사용자가 대상을 좁히면 --agent 또는 --project를 사용하세요.

2. 제목, 슬러그 및 출력 경로를 선택하세요. GitHub Pages 스타일 저장소의 경우 세션당 하나의 폴더를 선호하세요:

   sessions/<slug>/index.md
   sessions/<slug>/redaction-report.json
   

   슬러그는 짧게, 소문자로, 안정적으로 유지하세요. 제목이 불확실하면 내보내기 전에 사용자에게 제안하세요.

3. 아티팩트를 작성하기 전에 편집을 미리보세요:

   session-bandit redact-check <sessionId> --pretty
   

   개수와 주목할 만한 위험을 보고하세요. 세션에 개인 고객 데이터, 자격 증명, 독점 출력 또는 비정상적으로 민감한 로컬 컨텍스트가 포함된 것으로 보이면 --redact strict를 사용하세요.

4. 마크다운과 보고서를 내보내세요:

   session-bandit export-md <sessionId> \
     --out sessions/<slug>/index.md \
     --report-out sessions/<slug>/redaction-report.json \
     --title "사람이 읽을 수 있는 제목"
   

   사용자가 명시적으로 요청하고 위험을 수락하지 않는 한 공개 게시에 --redact none을 사용하지 마세요.

5. 게시하기 전에 검토하세요. 마크다운과 편집 보고서를 검사하세요. 요약 섹션, 관련 세션, 명령어, 도구 출력, 로컬 경로가 적절한지 확인하세요. 자동 편집은 최선의 노력이며 안전을 보장하지 않습니다.

6. 선택적으로 마크다운을 다듬으세요. CLI 출력 외부에 짧은 소개, 섹션 제목 또는 마무리 메모를 추가하거나 편집할 수 있습니다. 사실을 지어내지 마세요; 트랜스크립트, 다이제스트, 출처 및 편집 보고서는 그대로 유지하세요.

7. 공개하기 전에 물어보세요. git add, git commit, git push 또는 배포 작업 전에 편집 위험을 요약하고 사용자가 이미 현재 턴에서 승인하지 않은 한 명시적인 사용자 승인을 요청하세요.

GitHub Pages 템플릿

이 스킬은 이 SKILL.md 옆에 templates/github-pages-default/에 기본 게시 템플릿을 제공합니다. 사용자가 GitHub Pages 저장소, 정리된 정적 사이트 또는 내보낸 세션의 기본 공개 프레젠테이션을 요청할 때 사용하세요.

템플릿 동작:

• 사용자 정의 레이아웃과 CSS가 있는 Jekyll/GitHub Pages 사이트입니다.
• 생성된 세션을 sessions/<slug>/index.md에 위치시킵니다.
• 편집 보고서를 세션 옆에 sessions/<slug>/redaction-report.json으로 위치시킵니다.
• 내보낸 Session Bandit 마크다운이 자동으로 세션 레이아웃을 받도록 _config.yml 기본값을 사용합니다.
• Jekyll 또는 Pages 배포 없이 레이아웃을 확인할 수 있는 로컬 .design/session-page.html 픽스처를 포함합니다.
• 정적이고 자체 포함되어 있습니다; 사용자가 명시적으로 요청하지 않는 한 외부 에셋, 추적기, 글꼴 또는 원격 스크립트를 추가하지 마세요.

빈 게시 저장소를 초기화할 때:

cp -R <skill-디렉토리>/templates/github-pages-default/. <대상-저장소>/

저장소가 이미 존재하는 경우, 묻지 않고 _config.yml, _layouts/, assets/session.css, index.md 또는 README.md를 덮어쓰지 마세요. 사용자가 수동 색인을 원하는 경우에만 sessions/<slug>/index.md, sessions/<slug>/redaction-report.json 및 색인 항목을 추가하거나 업데이트하세요.

시각적 템플릿 변경의 경우, 게시하기 전에 templates/github-pages-default/.design/session-page.html을 로컬에서 확인하는 것을 선호하세요. 의도적으로 일반 HTML로 제작되었으므로 Jekyll이 필요하지 않습니다.

핸드오프 노트 작성

이전 세션에서 핸드오프 노트를 작성하라는 요청을 받으면:

1. 세션을 찾으세요. 사용자가 세션 ID를 제공하면 직접 사용하세요. 그렇지 않으면 최근 세션을 나열하고 관련 세션을 선택하세요:

   session-bandit list --sort importance
   

   또는 주제를 검색하세요:

   session-bandit search "주제"
   

   수동 브라우징을 위해 테이블/발췌문이 필요한 경우에만 --pretty를 추가하세요.

2. 핸드오프 프롬프트로 다이제스트를 생성하세요:

   session-bandit extract <sessionId> --prompt handoff
   

   이렇게 하면 구조화된 다이제스트(내용 점수, 작성된 파일, 오류, 요약/재개, 목표, 최종 상태)가 무엇을 써야 하는지 알려주는 합성 프롬프트로 감싸져 출력됩니다.

3. 핸드오프를 작성하세요. 프롬프트는 다음을 포함하도록 요청합니다: 목표, 수행된 작업, 현재 상태, 남은 작업. 다이제스트의 구조화된 데이터(작성된 파일, 오류, 주요 전환점)를 사실적 기반으로 사용하세요. 간결하게 유지하세요 — 돌아오는 에이전트는 전체 기록이 아닌 상태가 필요합니다.

4. 핸드오프를 사용자가 원하는 곳(문서 저장소, 마크다운 파일 등)에 저장하세요.

메모 노트 작성

과거 세션에서 메모 노트를 생성하라는 요청을 받으면:

1. 세션을 찾고 추출하세요:

   session-bandit extract <sessionId> --prompt memory
   

2. 메모 노트를 작성하세요. 프롬프트는 2-4문장으로 다음을 포함하도록 요청합니다: 세션이 무엇에 관한 것이었는지, 주요 결과, 기억할 가치가 있는 파일/결정. 제안된 중요도 계층(사소함 / 가벼움 / 보통 / 중요 / 무거움)으로 끝내세요.

3. 메모 노트를 사용자가 원하는 곳에 저장하세요.

팁

• --prompt handoff 및 --prompt memory 템플릿은 초안입니다. 출력 형식을 사용자의 필요에 자유롭게 적응시키세요 — 다이제스트 데이터가 가치 있는 부분이지 템플릿 텍스트가 아닙니다.
• 복잡한 다단계 작업과 같이 컨텍스트를 위해 전체 트랜스크립트가 필요할 때 --full을 사용하세요. --full이 없으면 다이제스트는 간결하며 세부 사항이 생략될 수 있습니다.
• Claude 요약, Codex 압축 및 BotBandit 메모리/압축 이벤트는 summary 메시지로 표시되고 추출에 포함됩니다. 유용한 합성 컨텍스트로 취급하되, 여전히 핸드오프와 메모리를 다이제스트의 파일, 오류, 테스트 및 최종 전환점에 근거하세요.
• 세션을 공개적으로 게시하거나 내보내기 전에 session-bandit redact-check <sessionId> --pretty를 실행하고 남은 위험을 보고하세요. 자동 편집은 최선의 노력이며 안전을 보장하지 않습니다.
• 마크다운 내보내기의 경우 session-bandit export-md <sessionId> --out <path> --report-out <reportPath>를 선호하고, 커밋/게시를 제안하기 전에 보고서를 검사하세요.
• 마크다운이 표준 게시 아티팩트입니다. 사용자가 명시적으로 HTML을 요청하지 않는 한 기본 HTML 트랜스크립트를 생성하지 마세요; 고품질 HTML은 검토된 마크다운 또는 편집된 번들에서 생성되어야 합니다.
• 새로운 GitHub Pages 게시 저장소에는 번들된 templates/github-pages-default/ 템플릿을 선호하세요. 사용자가 다른 스타일을 요청하지 않는 한 이것이 기본 공개 프레젠테이션입니다.
• 내용 점수는 활동(도구 호출, 파일 쓰기, 테스트 실행)을 측정하며 중요성을 측정하지 않습니다. 짧은 세션에 중요한 결정이 포함될 수 있습니다. 점수만 보지 말고 주요 전환점을 읽으세요.
• 세션 ID는 접두사로 지정할 수 있습니다 (예: 전체 UUID 대신 342647fa).
• session-bandit doctor을 실행하면 문제가 있는지 확인합니다 — 파싱 가정이 실제 세션 파일과 일치하는지, 형식 드리프트, 주입 마커, 인식되지 않은 유형 및 조용한 건너뛰기를 포함합니다. --agent claude, --agent codex 또는 --agent botbandit을 사용하여 확인 범위를 좁히세요.