study8677/rename

Claude Code, Codex, Cursor는 모두 사용자의 첫 번째 메시지만을 사용하여 세션 이름을 지정하며, 그 이후에는 영원히 고정됩니다. 한 시간 뒤 작업 내용이 바뀌었음에도 사이드바에는 여전히 「브랜치가 동기화되었는지 확인」이라고 적혀 있습니다. 수백 개의 세션이 쌓이면, 당신의 가장 가치 있는 기록은 검색조차 할 수 없는 무덤이 되어버립니다.

rename는 백그라운드(Background)에서 실행됩니다. 세션이 유휴(Idle) 상태가 되면, 해당 세션의 제목을 실제 작업 내용에 맞게 변경합니다. 그리고 rename search를 통해 여러 도구를 가로질러 어떤 과거 세션이든 찾아낼 수 있습니다.

brew install study8677/rename/rename
pipx install git+https://github.com/study8677/rename.git
uv tool install git+https://github.com/study8677/rename.git

API key가 필요 없으며, 런타임 의존성(Runtime dependency)이 제로입니다. macOS, Linux 및 Windows를 지원합니다.

rename status # 무엇을 감지했는지 확인
rename list # 새 제목 미리보기 (실제 쓰기 안 함)
rename once # 한 번 실행 후 종료
...

백그라운드에서 매 분마다 한 번씩 깨어나, 5분 이상 유휴 상태이면서 마지막 이름 변경 이후 내용에 변화가 있는 세션을 찾아 이름을 변경합니다. 변화가 없는 세션은 다시 쓰지 않으므로, 반복 실행해도 부작용이 없습니다.

도구	사이드바에 표시된 내용	실제 진행 중인 작업
Cursor	로딩 애니메이션 추가	데이터베이스를 Postgres로 마이그레이션
Codex	README의 오타 수정	불안정한 CI 파이프라인 조사
Claude Code	브랜치가 동기화되었는지 확인	감사 로그(Audit log) 기능 구현

제목은 10분 만에 거짓말이 됩니다. 일주일 뒤, 분명 AI로 이 버그를 해결했던 기억이 나는데도 해당 대화를 찾을 수 없습니다. 대화는 존재하지만, 잘못된 태그에 가려져 있기 때문입니다.

$ rename list
Claude Code
16m 检查分支是否同步 → 实现审计日志写入
...

정확한 제목만큼 중요한 것이 바로 찾아내는 것입니다. rename search는 모든 도구를 한 번에 검색합니다.

$ rename search "stripe webhook"
Cursor 3h Wire up the Stripe webhook handler payments-api
Claude Code 2d Debug the Stripe webhook signature billing-svc
...

┌──────────── 매 poll_seconds (기본 60s) 마다 ────────────┐
│ │
discover ──► 5분 이상 유휴 상태이며 새 내용이 있는 각 세션 ──► namer ──► 제목 쓰기
...

각 세션의 판정 규칙은 의도적으로 보수적입니다:

아직 사용 중인가? 유휴 시간이 임계값(Threshold)에 도달하지 않았다면 → 건드리지 않습니다. 새로운 내용이 없는가? 내용 해시(Hash)가 마지막으로 기록된 제목과 일치하면 → 건너뜁니다 (반복 실행해도 비용이 들지 않습니다). 수동으로 이름을 변경했는가? 사용자가 직접 편집한 내용은 절대 덮어쓰지 않습니다. 사용자가 새 메시지를 보내고 세션이 다시 유휴 상태가 될 때까지 유지됩니다. 그 외의 경우: 새로운 제목을 생성하여 기록합니다.

이를 통해 도구 전체가 **멱등성(Idempotent)**을 가지며, 안심하고 장기간 실행할 수 있습니다.

제목은 어떻게 생성되는가. 기본적으로 rename은 이미 로그인된 claude (또는 codex) 커맨드라인 인터페이스(CLI)를 호출합니다.
——claude --model haiku -p "…"
——따라서 제목은 대화의 실제 LLM 요약이며, API key가 필요하지 않습니다. CLI가 설치되어 있지 않다면 오프라인 휴리스틱(Heuristic) 방식으로 돌아갑니다.

설치 즉시 사용 가능하며, 사용자의 기록을 몰래 바꾸지 않습니다. 처음 실행할 때 rename은

도구	읽기	쓰기	상태
Claude Code	~/.claude/projects/**/<id>.jsonl	ai-title 한 줄 추가 (순수 추가 방식 — 가장 안전한 방식)	✅ 안정
Codex	~/.codex/state_*.sqlite + rollout 파일	UPDATE threads SET title	✅ 안정
Cursor	state.vscdb (composerHeaders + composerData)	두 곳의 제목 필드를 동시에 업데이트	✅ 안정
Antigravity (Google)	IDE: state.vscdb (antigravityUnifiedStateSync.trajectorySummaries) — Companion: ~/.gemini/antigravity/agyhub_summaries_proto.pb	해당 CascadeTrajectorySummary의 summary 필드를 다시 작성 (Companion은 원자적 rename (atomic rename) 방식으로 파일 재작성)	✅ 안정
Continue (continue.dev)	~/.continue/sessions/<id>.json	title 재작성 + 원자적 rename (atomic rename)	✅ 안정
Zed (zed.dev Assistant)	~/Library/Application Support/Zed/conversations/<uuid>.json 등	summary / title 재작성 + 원자적 rename (atomic rename)	✅ 안정
Windsurf (Codeium)	state.vscdb (Cursor 계열 레이아웃)	Cursor의 쓰기 경로를 재사용하며 경로만 변경	✅ 안정
Aider	.aider.chat.history.md (프로젝트마다 하나씩 존재)	.aider.chat.history.md.title 바이패스(bypass) 파일에 작성 (Aider 자체는 읽기 전용)	✅ 안정

「애플리케이션이 실행 중일 때의 쓰기」에 대하여. Codex, Cursor, Antigravity는 모두 데이터를 현재 사용 중인 SQLite 데이터베이스에 저장합니다. rename은 쓰기에 매우 신중하며 (읽기는 읽기 전용 연결을 사용하고, 쓰기에는 busy_timeout을 설정함), 오직 유휴(idle) 세션만 건드립니다. 하지만 호스트 앱(Host App)이 대화 내용을 메모리에 캐싱(caching)하고 있기 때문에, 디스크에서 제목을 변경하더라도 해당 대화를 다시 열 때 실행 중인 앱에 의해 덮어씌워질 수 있습니다. 가장 확실한 결과를 얻으려면 앱이 종료되었을 때 rename을 실행하십시오. Claude Code의 순수 추가(append-only) 형식은 이러한 우려가 없습니다.

Antigravity는 두 가지 형태 — IDE 버전(VS Code 기반 클라이언트, Gemini 사이드바 포함)과 Companion App(독립형 데스크톱 앱, Windows 전용)이 있습니다. rename은 두 가지 모두를 지원합니다:

형태	제목 저장 위치	형식
IDE	state.vscdb → ItemTable['antigravityUnifiedStateSync.trajectorySummaries']	base64(envelope(base64(CascadeTrajectorySummary))) — Cursor와 마찬가지로 두 단계의 base64로 감싸져 있음
Companion App	~/.gemini/antigravity/agyhub_summaries_proto.pb	순수 protobuf, repeated TopEntry { uuid; CascadeTrajectorySummary }

두 형태는 동일한 CascadeTrajectorySummary 스키마(Antigravity 2.0의 FileDescriptorProto를 역컴파일하여 얻음)를 공유하며, 단지 외부 래핑(wrapping) 방식만 다릅니다. IDE는 SQL UPDATE를 사용하고, Companion은 「임시 파일 작성 + 원자적 rename (atomic rename)」 방식을 사용합니다. 두 형태의 대화 본문(~/.gemini/antigravity/conversations/<uuid>.pb)은 모두 암호화되어 있지만, Antigravity의 에이전트(agent)는 자신이 작성한 평문 작업 문서를 ~/.gemini/antigravity/brain/<uuid>/ 아래(task.md, implementation_plan.md, walkthrough.md)에 저장합니다.

, 그리고 그에 대응하는 *.metadata.json 파일들.

요약) —— 이것들이 바로 rename입니다.

namer에게 전달되는
제목 재명명(rename)을 위한 소재입니다.

• ✅ Antigravity의 대화는 rename list, rename search, rename stats에 나타납니다. - ✅
• ✅ **자동 이름 변경 (Automatic Renaming)**은 brain artifact를 생성한 모든 대화에 적용됩니다 (즉, 계획 문서가 포함된 긴 세션들 — 제목이 가장 쉽게 경로를 벗어나는 유형입니다). artifact를 생성하지 않은 짧은 대화는 「실질 내용 (substantial content)」 게이트를 통해 건너뛰며, 이는 합리적입니다 — 소재가 없으면 이름을 지을 수도 없기 때문입니다. - ✅
• ✅ rename once --tool antigravity를 통해 언제든 수동으로 이름을 변경할 수 있습니다.

만약 향후 Antigravity에서 대화 본문을 직접 노출하는 공식 확장 API가 출시된다면, 그 계층을 연결하여 완전한 커버리지를 구현하겠습니다. 관련 이슈: #1.

기본값은 auto입니다.

API key가 전혀 필요하지 않습니다: rename은 이미 로그인된 claude 또는 codex 명령줄 인터페이스 (CLI)를 직접 재사용하여 고품질 제목을 생성합니다. 두 가지 모두 설치되어 있지 않은 경우, 완전히 오프라인인 휴리스틱 (heuristic) 방식으로 전환됩니다. 단 한 글자의 key도 입력할 필요가 없습니다.

namer	역할	API key 필요 여부?
auto	이미 로그인된 claude / codex CLI를 사용, 그렇지 않으면 heuristic	필요 없음 · 기본값
heuristic	최근 메시지를 제목으로 정제; 즉각적, 오프라인	필요 없음
claude	항상 claude CLI 사용 (기본적으로 빠른 Haiku 모델)	필요 없음 — 로그인 재사용
codex	항상 codex CLI 사용 (gpt-5-codex)	필요 없음 — 로그인 재사용
anthropic	Anthropic API에 직접 연결, 본인의 key 사용	api_key 또는 ANTHROPIC_API_KEY
openai	OpenAI API에 직접 연결, 본인의 key 사용	api_key 또는 OPENAI_API_KEY

별도의 설정 없이 바로 사용 가능하며, 어떤 key도 붙여넣을 필요 없이 LLM 품질의 제목을 얻을 수 있습니다 (이미 보유한 할당량을 사용합니다). 비용 제로/완전 오프라인을 원하시나요? namer = "heuristic"으로 설정하세요.

본인의 API key 사용하기. 로그인된 CLI 대신 본인의 Anthropic / OpenAI 계정을 사용하고 싶으신가요? namer를 `

, TOML을 직접 작성할 필요 없음인간화 진행 단계— 어떠한 원시 stderr도 없음; 모든 정보는 toast 또는 시스템 알림으로 번역됨최초 실행 권한 가이드(macOS)— 클릭 한 번으로 시스템 설정 → 전체 디스크 접근 권한으로 이동, 한 번 권한을 부여하면 시스템이 매번 스캔할 때마다 권한 창을 띄우지 않음게으른 스캔 (Lazy Scan)— 대시보드를 열 때 또는 사용자가 수동으로 Refresh를 클릭할 때만 세션을 스캔하며, 평소에는 가벼운 status만 poll 하여 권한 대화 상자가 반복적으로 발생하는 것을 방지함국제화 (Internationalization)— 영어 + 간체 중국어, 시스템 언어에 따라 자동 전환

cd macos-app
./build-app.sh
open Rename.app

Rename.app을 ~/Applications로 드래그하고, 로그인 항목에 추가하면 재부팅 후 메뉴 바 아이콘이 자동으로 시작됩니다.
이것은 LSUIElement 앱입니다—Dock에는 나타나지 않고 메뉴 바에만 나타납니다.

cd windows-app
python -m venv .venv ; .venv\Scripts\activate
pip install -e .
...

부팅 시 자동 실행: rename-gui의 바로가기를 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup에 넣으세요.

두 앱 모두 subprocess / Process를 통해 Python CLI를 호출하며, 데이터는 JSON으로 주고받습니다. CLI는 rename status --json / list --json / stats --json / search --json / once --session <id> 등의 명령을 제공하며, GUI는 이들을 호출하여 결과를 표시합니다. 새로운 상태, 저장소 또는 추가적인 데몬 (daemon)은 전혀 추가되지 않았으며, Python 데몬이 여전히 유일한 진실의 원천 (Source of Truth)입니다.

rename config는 ~/.config/rename/config.toml을 생성하고 출력합니다:

idle_seconds = 300 # 5분간 유휴 상태일 경우 이름 변경
poll_seconds = 60 # 1분마다 스캔
batch_size = 25 # 매 스캔 시 최대 N개 변경 (0 = 제한 없음)
...

모든 필드는 단일 실행 시 덮어쓸 수 있습니다: rename run --idle 600 --namer anthropic --tool cursor.

명령	설명
rename list	발견된 모든 세션과 제안된 제목을 미리 보기 (아무것도 기록하지 않음)
rename search <keyword>	모든 도구를 대상으로 제목 기준 세션 검색 ( --content 추가 시 본문까지 검색)
rename stats	빠른 개요: 각 도구별 세션 수, 이름이 지정되지 않은 세션 / 유휴 상태 세션 수
rename once	최근 배치 즉시 변경 (--limit N, --all, --dry-run 사용 가능)
rename run	포그라운드에서 지속 실행 (--once, --dry-run 추가 가능)
rename install	백그라운드 서비스 설치 및 시작 (macOS는 launchd, Linux는 systemd, Windows는 부팅 시 Startup 바로가기 사용)
rename uninstall	백그라운드 서비스 중지 및 제거
rename status	설정, 감지된 도구, 데몬 상태 표시
rename config	설정 파일 생성 / 출력

rename list, rename search, rename stats는 모두 --json을 지원하여 스크립트 통합이 용이합니다.

키를 입력할 필요가 없습니다. 네이밍은 이미 로그인된 도구를 사용합니다. 기본값인 auto는 이미 로그인된 claude / codex CLI가 제목을 작성하도록 하며, 따라서 짧은 대화 발췌본이 해당 서비스 제공업체로 전송됩니다 (사용자의 기존 크레딧을 사용하므로 API key가 필요 없습니다). 어떤 데이터도 로컬 기기를 떠나지 않기를 원하시나요? namer = "heuristic"으로 설정하면 100% 오프라인으로 작동합니다. "설치하자마자 과거의 모든 채팅 내역을 바꿔버리는 일"은 발생하지 않습니다. 최초 실행 시 기준 타임스탬프를 기록하며, 이전의 오래된 세션은 기본적으로 모두 건너뜁니다. 밀린 이름을 변경하는 것은 대시보드의 버튼을 클릭하거나 (rename once --historical 실행) 하는 사용자의 능동적인 행위이며, 데몬 설치의 부작용이 아닙니다. 이 도구는 오직 제목만 변경합니다. rename은 대화를 읽고 제목 필드를 쓰거나 한 줄을 추가할 뿐, 대화 내용을 편집, 삭제 또는 재배열하지 않습니다. 가역적(reversible)이며 멱등(idempotent)합니다. 제목이 잘못 지정되더라도 단지 제목일 뿐입니다—메시지를 하나 보내면 다시 평가됩니다. 내용이 변하지 않았다면 반복 실행해도 아무 일도 일어나지 않습니다.

도구 자체의 자동 명명 기능과 충돌하나요?
충돌하지 않습니다. 도구는 단 한 번만 이름을 지정하고 멈춥니다. rename은 세션이 유휴 상태(idle)가 된 후에만 작동하므로, 두 기능이 동시에 쓰기를 수행하지 않습니다.

내가 직접 설정한 제목을 덮어쓰나요?
아니요—해당 세션에 새로운 메시지를 보내지 않는 한 덮어쓰지 않습니다. 대화가 실제로 진행되기 전까지는 수동으로 설정한 제목이 존중됩니다.

API key를 입력해야 하나요?
필요하지 않습니다. 기본적으로 이미 로그인된 claude / codex CLI를 재사용합니다 (어떤 키도 붙여넣을 필요가 없습니다). 사용 중인 기존 할당량(quota)을 사용합니다. 비용 없이 사용하고 싶다면 namer = "heuristic"으로 설정하세요 (완전 오프라인 방식).

계속 켜두어도 안전한가요?
안전합니다—그것이 이 도구의 설계 목표입니다. 작동 원리(Working Principle)를 참조하세요. 유일하게 주의할 점은 「Cursor가 켜져 있을 때 해당 데이터베이스를 수정하는 것」(위 내용 참조)입니다.

rename을 설치하면 기존의 이전 채팅들은 어떻게 되나요?
기본적으로 아무 일도 일어나지 않습니다. 처음 실행할 때 기준 타임스탬프(baseline timestamp)를 기록하며, 백그라운드에서는 "기준 시점 이후에 활성화된" 세션만 수정합니다. 쌓여 있는 과거 기록도 모두 처리하고 싶나요? 대시보드에서 **"Rename historical sessions"**를 클릭하거나, rename once --historical --dry-run을 실행하여 먼저 미리보기(preview)를 한 뒤, 문제가 없다면 --dry-run을 제거하고 실행하세요.

내부 작동 원리—역공학(reverse engineering)을 통해 알아낸 세 가지 도구의 세션 저장 형식(session storage format)을 포함하여—가 궁금하다면 ARCHITECTURE.md를 참조하세요.

새로운 도구 지원을 추가하는 데는 파일 하나면 충분합니다—src/rename/adapters/에서 네 가지 메서드(available, discover, read_transcript, set_title)를 구현하면 됩니다. 자세한 내용은 CONTRIBUTING.md를 참조하세요.

git clone https://github.com/study8677/rename.git && cd rename
pip install -e ".[dev]"
pytest

본 프로젝트는 LINUX DO 커뮤니티에서 자유롭게 소통하고 있습니다—인사 나누기, 문제 피드백, 함께 연구하기를 환영합니다.

@xiongaox 님이 Antigravity 지원을 요청하는 #1 이슈를 제기했습니다. 이 이슈는 Antigravity 어댑터 세트 전체의 구현을 이끌어냈습니다: protobuf 스키마(schema) 역컴파일, brain/ 내 평문(plaintext) 자료 발견, 그리고 이후 그가 업로드한 .pb 파일을 통해 Companion App 경로를 해제하는 과정 등이 포함됩니다.

MIT © JingWen Fan