Show GN: agent-gc – AI 코딩 에이전트가 남긴 worktree 쓰레기를 치워주는 TUI

• Codex, Claude Code 같은 에이전트에 병렬로 일을 시키다 보니 worktree가 계속 늘어났음. worktree마다 install, 빌드, 테스트가 돌면서
  node_modules

,.next

,target

,.venv

도 같이 복제됨- 어느 날 디스크가 꽉 차서 열어 보니
~/.codex/worktrees/<hash>/my-app/node_modules

가 수십 개 있었음. 처음 돌렸을 때약 70GB를 회수함

• 어느 날 디스크가 꽉 차서 열어 보니
• npkill로 지울 수는 있지만, 이 폴더가 에이전트 worktree인지, 지워도 다시 만들 수 있는지, 옆에
  .env

나.sqlite

가 있지는 않은지까지는 봐주지 않음. 그래서 에이전트 작업 흐름에 맞춰 따로 만듦

주요 기능

• Codex, Claude Code, OpenCode, Cursor, Gemini, Aider, Orca가 쓰는 경로와
  ~/dev

같은 일반 프로젝트 경로를 스캔함 - 의존성 폴더, 빌드 산출물, 언어별 캐시를 찾아 크기, 마지막 수정 시각, 프로젝트, git 상태와 함께 보여줌

• 마커를 보고 판단해서 오탐을 줄임
  target

은 상위에Cargo.toml

이 있을 때만 잡음- 그냥
env

라는 폴더는 venv 마커가 있어야 잡음 build

/dist

는 근처에 프로젝트 마커가 있어야 잡음

• 위험도는 SAFE / CAUTION / DANGER 세 단계임. DANGER(안에
  .env

,.pem

,.db

등이 있는 경우)는 잠겨 있어서 선택조차 안 됨

사용법

npx agent-gc

를 실행하면 TUI가 뜸. 키는 j/k로 이동, Space로 선택, d로 삭제- CLI 모드도 있음
agent-gc clean --dry-run --preset safe

로 무엇이 지워질지 먼저 확인 가능--preset agent-only

,--preset older --older-than 30d

같은 프리셋 지원- 스크립트에서는
--yes

필요. 터미널이 아닌 환경에서--yes

없이 지우려 하면 거부함

• 한꺼번에 지우기는 SAFE만 가능함. CAUTION은 TUI에서 하나씩 골라야 함

구현

• Rust + ratatui로 만든 단일 바이너리이고, npm 패키지는 바이너리를 감싸는 얇은 래퍼임

• macOS, Linux, Windows의 x64와 arm64까지 6개 플랫폼 바이너리를 같이 배포함

• Linux는 musl 정적 빌드라 glibc 버전을 타지 않음

• Windows는 CRT 정적 링크라 VC++ 런타임이 없어도 됨

• 릴리스할 때마다 6개 플랫폼 네이티브 러너에서 빌드, 테스트,
  npm install -g

, 실제 삭제까지 하는 스모크 테스트를 통과해야 배포됨 - crossterm은 Windows에서 키를 누를 때와 뗄 때 이벤트를 둘 다 보냄. 이것 때문에 Space 선택이 두 번 토글되는 버그가 있었음. 비슷한 TUI를 만드는 분이라면
KeyEventKind::Press

필터를 넣길 권함

한계와 계획

• Docker, Xcode DerivedData, Android 쪽은 아직 다루지 않음
• 백그라운드 자동 청소는 일부러 넣지 않았음. 지우는 결정은 사람이 하는 게 맞다고 봄
• 다른 에이전트 도구의 worktree나 캐시 경로 제보 환영함