Gearshift for Claude Code

Switch Claude Code models by dragging a manual-transmission gear stick with your mouse.

마우스로 수동변속기 기어봉을 조작하듯 Claude Code의 모델을 전환하는 VSCode 확장.

Disclaimer This is an unofficial community extension. It is not affiliated with, endorsed, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic PBC, referenced here only to describe compatibility.

면책 조항 이것은 비공식 커뮤니티 확장입니다. Anthropic과 제휴·후원·승인 관계가 없습니다. "Claude", "Claude Code"는 Anthropic PBC의 상표이며, 이 확장에서는 호환 대상을 설명하기 위한 목적으로만 사용됩니다.

Requirements / 필요한 것

All three are required. If any one is missing, moving the gear will do nothing.

아래 3가지가 모두 갖춰져야 합니다. 하나라도 빠지면 기어를 움직여도 아무 일이 일어나지 않습니다.

If step 3 prints nothing, install it: 3번에서 버전이 안 뜨면 설치하세요:

npm install -g @anthropic-ai/claude-code

Why is the global CLI needed? The Claude Code extension's "Open in Terminal" mode runs the real claude command from your PATH, not a bundled binary. Without a global install the terminal just prints claude: command not found and no session starts.

왜 전역 CLI가 필요한가? Claude Code 확장의 "터미널에서 열기" 모드는 내장 바이너리가 아니라 PATH에 설치된 진짜 claude 명령을 실행합니다. 전역 설치가 없으면 claude: command not found만 뜨고 세션이 시작되지 않습니다.

No OS restrictions. Works on Windows / macOS / Linux — it only uses VS Code's integrated terminal API, so no extra tools (xdotool, etc.) are needed.

운영체제 제약은 없습니다. Windows / macOS / Linux 모두 동작하며, VS Code 통합 터미널 API만 사용하므로 별도 도구를 깔 필요가 없습니다.

Installation / 설치

Search "Gearshift for Claude Code" in the Extensions panel (Ctrl+Shift+X) and click Install.

확장 검색창(Ctrl+Shift+X)에서 "Gearshift for Claude Code" 를 검색해 Install.

How to Use / 사용법

Step 1 — Open the gear stick / 기어봉 열기

Command Palette (Ctrl+Shift+P) → "Gearshift: Open Model Switcher"

Step 2 — Connect a Claude session / Claude 세션 연결하기

Click "Pick session". You will choose twice:

"세션 선택" 을 누르면 두 번 고르게 됩니다.

1. Pick a terminal — where gear commands (/model ...) will be typed. If no terminal is open, choose "Open new Claude Code session" and one will be created. A terminal you started yourself with claude --resume also works, regardless of its name. 터미널 고르기 — 기어 명령을 흘려보낼 터미널. 없으면 "새 Claude Code 세션 열기"를 고르면 자동으로 띄워줍니다. 직접 claude --resume으로 켠 터미널도 이름과 상관없이 고를 수 있습니다.

2. Pick a transcript — the actual Claude conversation the fuel gauge will track. Choose the recently active Claude Code session shown with an 8-character alphanumeric code. That code is the beginning of the session's full UUID; if several conversations exist in the same folder, choose the UUID belonging to the conversation you want to measure. 대화 기록 고르기 — 연료 게이지가 추적할 실제 Claude 대화입니다. 최근 활동 시각과 영문·숫자 8자리 코드로 표시되는 Claude Code 세션을 고르세요. 이 코드는 전체 세션 UUID의 앞부분이며, 같은 폴더에 대화가 여러 개라면 측정하려는 대화의 UUID를 선택합니다.

Step 3 — Shift gears / 기어 넣기

Drag the red knob into a slot and the matching command is typed into that terminal. Like a real manual gearbox, you must pass through the neutral crossbar to move between columns.

빨간 노브를 드래그해 슬롯에 놓으면 해당 명령이 그 터미널에 자동 입력됩니다. 실제 수동변속기처럼, 다른 열로 넘어가려면 중앙 가로줄(중립)을 거쳐야 합니다.

Step 4 — Set your goal at the ⛽ gas station / ⛽ 주유소에서 목표 세우기

Click the ⛽ button (bottom-right) to open the settings panel. Set two things:

우하단 ⛽ 버튼을 누르면 설정 패널이 열립니다. 두 가지를 정합니다.

Then press "Start tracking". The clock starts, the gauge starts draining, and the car starts driving.

입력했으면 "추적 시작" 을 누릅니다. 그 순간부터 카운트가 돌고, 게이지가 줄고, 자동차가 달리기 시작합니다.

Gear Mapping / 기어 매핑

⛽ The Fuel Gauge — a meter for burning fuel, not saving it

⛽ 연료 게이지 — 아끼는 게 아니라 "다 태우는" 계기판

A normal fuel gauge exists to tell you to conserve. This one is the opposite.

일반적인 연료 게이지는 아껴 쓰라고 있습니다. 이건 반대입니다.

If you have ever let a 5-hour window expire having used less than half your subscription, that is exactly what this targets. You already paid for it — unused capacity simply evaporates. So this gauge pushes you to burn your token goal before time runs out.

구독제를 쓰면서 정작 한도의 절반도 못 쓰고 5시간 창을 흘려보낸 적이 있다면, 그게 바로 이 기능이 노리는 지점입니다. 결제한 몫은 이미 나갔습니다 — 안 쓰면 그냥 증발합니다. 그래서 이 게이지는 정해진 시간 안에 목표 토큰을 다 소진하도록 등을 떠밉니다.

The less fuel remains, the faster the car drives. 남은 연료가 줄어들수록 자동차가 빨라집니다.

So a slow car is a warning, not praise. A full tank with the clock running means you have not put Claude to work yet.

즉 차가 느리다는 건 칭찬이 아니라 경고입니다. 연료가 가득한데 시간만 흘러가고 있다면, 아직 Claude를 충분히 굴리지 않았다는 뜻입니다.

Ways to burn it / 이렇게 써먹으면 좋다

• Don't be shy about higher gears. If fuel is plentiful and you are still sitting in 2nd (Haiku), shift up to 4th (Opus) or 5th (Fable) and throw harder problems at it. Unused capacity disappears anyway. 더 센 기어를 겁내지 마세요. 연료가 남아도는데 계속 2단(Haiku)에 머물러 있다면, 4단(Opus)이나 5단(Fable)로 올려 더 어려운 문제를 던지세요. 어차피 안 쓰면 사라집니다.

• Stop saving work for later. That refactor, those tests, the docs, the code review you keep postponing — if there is fuel left, now is the time. 작업을 아껴두지 마세요. 미뤄둔 리팩터링, 테스트 작성, 문서화, 코드 리뷰 — 연료가 남아 있다면 지금이 그때입니다.

• Run subagents. Parallel work and broad exploration eat a lot of tokens — which is exactly the fastest way to burn the gauge down. 서브에이전트를 굴리세요. 병렬 작업과 큰 탐색은 토큰을 많이 먹고, 그게 곧 게이지를 태우는 가장 빠른 길입니다.

• Time almost up but half a tank left? Hand Claude one big task wholesale for the remaining window. 시간이 다 되어가는데 연료가 반이라면, 남은 시간에 큰 작업 하나를 통째로 맡기세요.

How usage is counted / 계산 방식

• Tracks exactly one transcript — the one you picked. Usage from other projects or other Claude sessions never bleeds in. 선택한 대화 기록 하나만 추적합니다. 다른 프로젝트나 세션의 사용량은 섞이지 않습니다.

• Polls that transcript's usage records every 20 seconds. 20초마다 그 대화의 usage 기록을 집계합니다.

• Cache-read tokens are included. Fuel reflects every token Claude processes for a response: input, cache creation, cache reuse, and output. 캐시 재사용(cache_read) 토큰도 포함합니다. 연료는 응답 하나를 위해 Claude가 처리한 모든 토큰(입력, 캐시 생성, 캐시 재사용, 출력)을 반영합니다.

• One response is counted once. Claude Code can write thinking, text, and tool records for the same response, so Gearshift de-duplicates them by message ID before adding the four token categories. 응답 하나는 한 번만 계산합니다. Claude Code는 같은 응답을 사고·텍스트·도구 기록으로 여러 줄에 쓸 수 있으므로, Gearshift는 메시지 ID로 중복을 제거한 뒤 네 종류의 토큰을 합산합니다.

• When the time limit ends, usage freezes at that point. Changing the token goal mid-run does not reset the clock or accumulated usage. 목표 시간이 끝나면 그 시점 사용량으로 고정됩니다. 도중에 목표 토큰량을 바꿔도 시작 시각과 누적 사용량은 초기화되지 않습니다.

• Pit-in at an empty tank. When accumulated usage reaches or exceeds the token goal, the fuel gauge reaches 0% and the car holds top speed (220 km/h) for 3 seconds before animating into the PIT lane, after which the speed label changes to PIT. 연료가 비면 피트인합니다. 누적 사용량이 목표 토큰 이상이 되면 게이지가 0%가 되고, 차량이 최고속도(220 km/h)로 3초간 달린 뒤 PIT 레인으로 들어가며 속도 표시는 PIT으로 바뀝니다.

⚠ The goal is yours to set. Anthropic does not publish per-plan limits as token counts (only message counts and relative multipliers). So the number you enter is a work goal you set for yourself, not a real subscription quota. Tune it to your own usage pattern.

⚠ 목표치는 스스로 정하는 것입니다. Anthropic은 플랜별 토큰 한도를 토큰 수로 공개하지 않습니다. 따라서 여기 입력하는 값은 실제 구독 한도가 아니라 본인이 세우는 작업 목표입니다.

Other Controls / 그 밖의 조작

In the bottom-right control bar / 우하단 컨트롤 바에서:

• Size / 크기 — scale the whole panel with the slider
• Language / 언어 — English / 한국어 / Deutsch
• ⛽ — token goal and time limit / 토큰 소비 목표와 목표 시간

Settings save automatically. / 설정은 자동 저장됩니다.

🔄 Gear Sync / 기어 자동 동기화

The stick shows the session's real model, not just the last gear you pulled. Type /model opus in the terminal by hand and the knob slides to 4 on its own within a couple of seconds.

기어봉은 세션의 실제 모델을 가리킵니다. 내가 넣은 기어를 그냥 표시하는 게 아닙니다. 터미널에 직접 /model opus를 쳐도 1~2초 안에 노브가 스스로 4단으로 미끄러집니다.

Gearshift watches the session's transcript (~/.claude/projects/**/*.jsonl) for two kinds of evidence and trusts whichever is newer:

Gearshift는 세션 기록(~/.claude/projects/**/*.jsonl)에서 두 가지 증거를 지켜보고, 더 최신인 쪽을 믿습니다:

• The /model announcement. The CLI logs Set model to Opus 4.8 the instant the command runs — this is what makes the sync immediate. /model 실행 알림. CLI가 명령 즉시 Set model to Opus 4.8을 기록합니다. 동기화가 즉각적인 건 이 덕분입니다.
• The model that answered. Every Claude turn is logged with the model that produced it — the ground truth, confirming what actually took the wheel. 실제 응답한 모델. Claude의 매 응답에는 처리한 모델이 함께 남습니다. 실제로 운전대를 잡은 게 무엇인지 확인해 주는 최종 근거입니다.

Two details worth knowing / 알아두면 좋은 두 가지:

• 1st gear (default) syncs only from the announcement, which spells it out (Sonnet 5 (default)). An answered turn can't: "default" is resolved to a real model before it reaches the transcript. So a session parked in 1 will drop into whichever gear that turned out to be once Claude speaks — the honest reading. 1단(default)은 알림으로만 동기화됩니다. 알림은 Sonnet 5 (default)처럼 명시해 주기 때문입니다. 응답 기록으로는 안 됩니다 — "default"는 실제 모델로 정해진 뒤에 기록되니까요. 그래서 1단에 세워둔 세션은 Claude가 답하는 순간 그게 실제로 무엇이었는지에 해당하는 단수로 내려앉습니다.
• Your hand wins. While you're dragging the knob, sync stays out of the way. 손이 우선입니다. 노브를 잡고 있는 동안엔 자동 동기화가 끼어들지 않습니다.

⚠ Important Limitation / 중요한 한계

This extension cannot control the regular Claude Code chat in the sidebar/panel. /model is a terminal-only CLI command; in panel (webview) mode claude itself refuses it:

이 확장은 사이드바/패널의 일반 Claude Code 채팅을 조작하지 못합니다. /model은 터미널 전용 CLI 명령이라, 패널 모드에서는 claude가 다음과 같이 거부합니다:

opens an interactive panel and isn't available in this environment. Run it from the Claude Code terminal instead.

So it can only drive a claude session running in a terminal. If you are using the sidebar/panel chat, seeing no terminals in "Pick session" (or no reaction after picking) is expected — open a terminal and start claude or claude --resume first.

그래서 오직 터미널에서 실행 중인 claude 세션만 조작할 수 있습니다. 사이드바/패널 채팅을 쓰고 있다면 "세션 선택"에 터미널이 없거나 골라도 반응이 없는 게 정상입니다 — 먼저 터미널을 열고 claude를 실행하세요.

VS Code does not expose which program actually runs inside a terminal, only its display name. So "Pick session" lists every open terminal (ones named Claude Code are sorted first as a hint).

VS Code는 터미널 안에서 도는 프로그램을 알려주지 않고 이름만 보여줍니다. 그래서 "세션 선택"은 열려 있는 모든 터미널을 나열합니다.

Troubleshooting / 잘 안 될 때

Tips / 팁

• The knob moves like a real gearbox: vertical travel stays in one column, and crossing columns requires passing through the neutral crossbar. 기어 노브는 실제 수동변속기처럼 움직입니다: 한 열 안에서는 위/아래로만, 열 전환은 중립을 거쳐야 합니다.

• P is not a model — it interrupts the response in progress (sends ESC). Useful when Claude heads the wrong way. P는 모델이 아닙니다 — 진행 중인 응답을 중단(ESC)합니다. 엉뚱한 방향으로 갈 때 바로 세울 수 있습니다.