keep-codex-fast: 로컬 Codex 상태를 백업 우선으로 정리해 빠르게 유지하는 스킬

9bow · 7월 18, 2026, 4:30오전

keep-codex-fast 소개

OpenAI의 코딩 에이전트 Codex CLI를 몇 주 동안 쓰다 보면, 쌓인 대화 기록과 터미널, 로그, 워크트리(worktree), 프로젝트 기록 때문에 도구가 점점 무거워집니다. keep-codex-fast 는 이렇게 느려진 로컬 Codex 상태를 안전하게 들여다보고 정리해, 속도를 되찾도록 돕는 Codex 스킬입니다. 무언가를 지우기보다 백업과 아카이브를 앞세우는 "백업 우선(backup-first)" 원칙을 내세웁니다.

이 스킬의 핵심 규칙은 "핸드오프(handoff)를 먼저 만들고, 삭제가 아니라 아카이브하며, 준비가 됐을 때만 실제로 적용한다" 로 요약됩니다. 기본 동작은 오직 보고(report)뿐이라, 사용자가 명시적으로 요청하기 전까지는 파일을 쓰거나 백업을 만들거나 폴더를 옮기거나 로컬 Codex 상태를 바꾸지 않습니다. 무엇이 얼마나 커졌는지 먼저 보여 주고, 무엇을 남기고 무엇을 아카이브할지는 사용자가 결정합니다.

keep-codex-fast 는 커진 로컬 상태를 진단하고, 오래된 대화를 아카이브하기 전에 이어서 작업할 수 있는 핸드오프 문서를 만들며, 변경 전 중요한 상태를 백업합니다. 여기에 채팅 탐색을 느리게 만드는 비정상적으로 큰 스레드 제목·미리보기 메타데이터를 탐지하고, 오래된 워크트리를 옮기고, 큰 로그를 회전(rotate)하고, 죽은 프로젝트 참조를 정리하는 일까지 다룹니다. 무거운 Node/개발 프로세스는 죽이지 않고 보고만 합니다.

keep-codex-fast의 세 가지 모드

keep-codex-fast 는 얼마나 개입할지를 세 단계 모드로 나눕니다.

점검(Inspect) : 보고 전용으로, 아무것도 쓰지 않습니다. 어떤 로컬 상태가 커졌는지 진단만 합니다.
정리(Maintain) : 일반 적용 모드입니다. 먼저 백업한 뒤 오래된 세션을 아카이브하고, 오래된 워크트리를 옮기고, 로그를 회전하고, 죽은 설정을 정리하고, 경로를 정규화합니다. 단, 스레드 제목·미리보기 메타데이터는 건드리지 않습니다.
선택적 복구(Optional repair) : --apply --repair-thread-metadata-bloat 를 명시했을 때만 동작합니다. 백업 후 지나치게 커진 SQLite의 표시용 제목·미리보기 메타데이터를 짧게 다듬되, 대화 기록(transcript) 자체는 그대로 둡니다.

기본 원칙은 어떤 경우에도 대화·로그·워크트리를 영구 삭제하지 않는다는 것입니다. 이들은 아카이브 폴더로 옮겨지고, 적용 전에 백업·복구 산출물이 함께 기록됩니다.

keep-codex-fast의 안전한 정리 흐름

권장하는 사용 흐름은 네 단계입니다. 먼저 보고를 받아(1단계) Codex가 어떤 큰 세션, 오래된 워크트리, 로그, 경로 문제, Node 프로세스를 가지고 있는지 확인합니다. 이 단계에서는 아직 아무것도 바뀌지 않습니다. 다음으로 계속 이어 갈 만한 활성 대화에 대해 핸드오프 문서를 만듭니다(2단계). 핸드오프는 무엇을 하고 있었는지, 무엇이 바뀌었는지, 어떤 파일과 명령이 중요한지, 다음에 할 일은 무엇인지를 담는 작은 연속성 노트로, 이것이 있어야 무거운 옛 대화를 아카이브하고 새 스레드에서 이어 갈 수 있습니다.

그 다음 백업을 만들고 확인한 뒤(3단계)에만 실제 적용을 진행하며, 이때 Codex가 실행 중이라면 먼저 종료해야 합니다. 마지막으로 오래된 세션·워크트리·큰 로그를 삭제가 아니라 아카이브로 옮깁니다(4단계). 저자는 이 흐름의 사고 모형을 "대화는 실행을 위한 것, 핸드오프 문서는 기억을 위한 것, 아카이브는 기록을 위한 것, 새 스레드는 속도를 위한 것" 이라고 정리합니다.

keep-codex-fast가 정리하는 대상

이 스킬이 안전하게 다루는 항목은 다음과 같습니다.

고정(pin)되지 않은 오래된 활성 세션
오래된 워크트리
커진 logs_2.sqlite* 로그 파일
config.toml 안의 죽은/임시 프로젝트 항목
로컬 SQLite 텍스트 필드에 남은 윈도우 경로(\\?\C:\...) 불일치
state_5.sqlite 의 지나치게 커진 스레드 제목·첫 메시지 미리보기 메타데이터 (--repair-thread-metadata-bloat 를 줬을 때만)

일부 Codex 빌드는 첫 사용자 프롬프트 전체를 스레드 제목과 목록 미리보기로 저장하는데, 이 값이 수십만 자까지 커지면 대화를 열기도 전에 목록 탐색이 느려질 수 있습니다. keep-codex-fast 는 보고 모드에서 이 제목·미리보기 크기를 알려 주고, 위 플래그를 명시했을 때만 백업 후 값을 다듬습니다. 이때도 실제 대화 기록은 남습니다. 다만 백업 폴더에는 로컬 Codex 메타데이터 같은 민감한 정보가 담길 수 있으므로, 저자는 백업 폴더(특히 thread-metadata-repairs.jsonl 과 restore-thread-metadata.py)를 외부에 공유하지 말고 로컬에 보관하라고 당부합니다.

keep-codex-fast 설치 및 사용법

가장 간단한 방법은 Codex에게 스킬 설치를 요청하는 것입니다.

Install the keep-codex-fast skill from https://github.com/vibeforge1111/keep-codex-fast

또는 이 폴더를 Codex 스킬 디렉토리에 keep-codex-fast 로 복사해도 됩니다. 설치 후에는 Codex 안에서 자연어로 점검을 요청할 수 있습니다.

Use $keep-codex-fast to inspect my Codex local state and recommend a safe maintenance plan.

스크립트를 직접 실행하고 싶다면, 기본은 읽기 전용 보고입니다.

# 보고만 (읽기 전용, 기본값)
python scripts/keep_codex_fast.py

# 상세 정보(스레드 ID·제목·경로 등)까지
python scripts/keep_codex_fast.py --details

# 백업만 생성, 이동·변경은 하지 않음
python scripts/keep_codex_fast.py --backup-only

# 핵심 정리 적용 (제목/미리보기 메타데이터는 건드리지 않음)
python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7

# Codex 종료를 기다린 뒤 적용
python scripts/keep_codex_fast.py --apply --wait-for-codex-exit

정기 점검이 필요하다면 자동 적용이 아니라 리마인더 형태로 두기를 저자는 권합니다. 자동화는 사용자가 어떤 대화에 핸드오프를 만들어 뒀는지 알 수 없으므로, 보고와 알림만 하고 아카이브·이동·정리·삭제 같은 변경은 사람이 확인한 뒤에만 수동으로 적용하는 것이 안전하기 때문입니다.

keep-codex-fast의 라이선스

keep-codex-fast 는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

keep-codex-fast 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~