본문으로 건너뛰기

Claude Code statusline 설정: 스크립트 예제와 문제 해결

개인용 상태 표시줄은 /statusline으로 만들 수 있습니다. 동작을 직접 관리하려면 statusLine에 스크립트 실행 명령을 지정합니다. 모델명·현재 폴더·Git 브랜치·컨텍스트 사용률·세션 비용 추정치를 표시하는 예제와 빈 화면의 확인 순서를 제공합니다.

LaoZhang AI Team게시업데이트 10 분 소요
목차
Claude Code 상태 표시줄을 설정하는 방법 비교

Claude Code 상태 표시줄(statusline)은 현재 세션의 JSON을 받아 화면에 표시할 텍스트를 출력하는 로컬 명령입니다. 개인용으로 빠르게 시작하려면 Claude Code 안에서 /statusline에 원하는 항목을 요청합니다. 어떤 값을 읽고 어떤 명령을 실행하는지 직접 관리하려면 스크립트를 만든 뒤 설정 파일의 statusLine에 연결합니다. 공식 상태 표시줄 문서

처음에는 모델명, 현재 폴더, Git 브랜치, 컨텍스트 사용률 정도로 시작하면 됩니다. 비용도 필요하다면 세션 비용 추정치라는 뜻을 함께 표시합니다. 아래 수동 예제는 모의 JSON으로 먼저 확인할 수 있으며, 측정값이 없을 때 ?를 출력해 실제 0과 구분합니다.

/statusline, 직접 만든 스크립트, 추천 도구 중 무엇을 고를까요?

원하는 결과먼저 선택할 방법선택 이유와 필요한 확인
개인용 한 줄을 빨리 만들기/statusline원하는 표시를 말로 요청합니다. 생성된 스크립트와 실행 명령을 확인합니다.
표시할 값과 실행 동작을 직접 관리하기수동 statusLine작은 스크립트에서 입력, 출력, 누락값 처리를 함께 관리합니다.
팀에서 같은 구성을 사용하기공유 프로젝트 설정스크립트와 필요한 실행 환경을 함께 공유해야 합니다. 개인 홈 경로를 그대로 넣지 않습니다.
테마·여러 줄·위젯을 화면에서 편집하기ccstatusline 같은 별도 도구편집 기능이 필요한 경우에 적합합니다. 패키지 설치와 선택한 위젯의 파일·자격 증명·네트워크 접근도 검토합니다.

이 비교는 용도에 따른 선택 기준입니다. 도구 간 속도나 안정성을 실측한 순위는 아닙니다. 단순한 표시가 목적이라면 아래 스크립트로 시작하고, 표시 편집에 드는 시간이 커질 때 별도 도구를 고려하는 편이 이해하기 쉽습니다.

말로 요청해서 만들기

Claude Code 안에서 다음처럼 입력합니다.

/statusline 모델명, 현재 폴더, Git 브랜치, 컨텍스트 사용률을 한 줄로 표시해 주세요. 측정값이 없으면 ?로 표시하고, 비용을 넣는다면 세션 비용 추정치라고 밝혀 주세요.

/statusline은 사용자 설정 영역에 스크립트를 만들고 설정을 갱신할 수 있습니다. 생성 후에는 실제 파일과 statusLine.command를 읽어 봅니다. Git 조회가 어느 폴더를 대상으로 하는지, 추가 파일이나 네트워크를 읽는지 확인하면 나중에 값을 고치기도 쉽습니다. 상태 표시줄이 보이고 요청한 항목이 표시되는 것이 화면에서의 첫 성공 신호입니다. 공식 /statusline 설명

수동 설정: 스크립트와 모의 JSON부터 확인하기

Claude Code는 명령의 표준 입력(stdin)으로 JSON을 전달합니다. 스크립트는 화면에 보여 줄 문자열을 표준 출력(stdout)으로 내보냅니다. 진단 메시지는 표준 오류(stderr)로 보냅니다. 설정 키는 대소문자를 구분하는 statusLine이며, 명령 이름인 /statusline과 표기가 다릅니다. 입력·출력 규칙

Claude Code에서 스크립트로 전달되는 JSON과 화면 출력의 흐름

1. 실행 환경과 파일 준비

이 예제에는 Node.js가 필요합니다. Git 브랜치를 표시하려면 git도 실행할 수 있어야 합니다. Claude Code를 설치했다고 Node.js가 반드시 함께 설치되는 것은 아닙니다. Node.js가 없는 환경이라면 /statusline에 이미 사용하는 인터프리터로 만들어 달라고 요청하거나, 해당 환경에 맞는 스크립트를 선택합니다.

아래 전체 코드를 statusline.cjs라는 파일에 저장합니다. 먼저 원하는 일반 폴더에서 시험한 뒤 개인용으로 사용할 파일 위치를 정하면 됩니다. .cjs 확장자를 사용하므로 주변 프로젝트의 모듈 설정과 관계없이 CommonJS로 실행합니다.

js
const { spawnSync } = require("node:child_process");

const object = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
const number = (v) => typeof v === "number" && Number.isFinite(v);
const clean = (v) => typeof v === "string"
  ? v.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim() : "";

function branchAt(directory) {
  if (!directory) return "-";
  const run = (args) => {
    const r = spawnSync("git", ["-C", directory, ...args], {
      encoding: "utf8", timeout: 250, windowsHide: true,
      maxBuffer: 8192, stdio: ["ignore", "pipe", "pipe"]
    });
    return r.status === 0 ? clean(r.stdout) : "";
  };
  const branch = run(["symbolic-ref", "--quiet", "--short", "HEAD"]);
  if (branch) return branch;
  const commit = run(["rev-parse", "--short", "HEAD"]);
  return commit ? `detached:${commit}` : "-";
}

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", () => {
  let data;
  try {
    data = object(JSON.parse(input));
  } catch {
    console.error("statusline: JSON 입력을 확인하세요.");
    process.exitCode = 1;
    return;
  }
  const model = object(data.model);
  const workspace = object(data.workspace);
  const directory = clean(workspace.current_dir) || clean(data.cwd);
  const folder = directory.replace(/\\/g, "/").split("/").filter(Boolean).pop() || "폴더 ?";
  const context = object(data.context_window).used_percentage;
  const cost = object(data.cost).total_cost_usd;
  const parts = [
    clean(model.display_name) || clean(model.id) || "모델 ?",
    folder,
    `git ${branchAt(directory)}`,
    number(context) && context >= 0 && context <= 100
      ? `컨텍스트 ${Math.round(context)}%` : "컨텍스트 ?",
    number(cost) && cost >= 0 ? `추정 USD ${cost.toFixed(2)}` : "추정 USD ?"
  ];
  const window = object(object(data.rate_limits).five_hour);
  const now = Date.now() / 1000;
  if (number(window.used_percentage) && window.used_percentage >= 0 &&
      window.used_percentage <= 100 && number(window.resets_at) && window.resets_at > now) {
    parts.push(`5시간 사용 ${Math.round(window.used_percentage)}%`);
  }
  process.stdout.write(parts.join(" | ") + "\n");
});

스크립트는 JSON에 있는 현재 폴더를 대상으로 읽기 전용 Git 조회를 합니다. 일반 브랜치와 아직 첫 커밋이 없는 브랜치는 이름을 표시하고, detached HEAD는 커밋 ID를 표시합니다. Git이 없거나 폴더가 없거나 조회에 실패하면 git -를 표시합니다. git - 자체가 저장소에 변경 사항이 없다는 뜻은 아닙니다. 이 예제는 파일 변경 여부를 계산하지 않습니다.

각 Git 조회는 250ms 제한을 두지만, Node.js 시작 시간을 포함한 전체 실행 시간이나 실제 화면 반응 속도를 보장하는 수치는 아닙니다. Git 표시가 필요 없다면 branchAt 함수와 해당 표시 항목을 빼면 됩니다. JSON을 표시하는 부분은 네트워크, 자격 증명, 대화 기록을 읽지 않습니다.

2. 모의 입력으로 출력 확인

같은 폴더에 mock.json을 저장합니다. 아래 값은 실제 세션이나 계정에서 얻은 값이 아닙니다.

json
{
  "model": { "display_name": "테스트 모델" },
  "context_window": { "used_percentage": 42 },
  "cost": { "total_cost_usd": 0.18 }
}

macOS·Linux·Git Bash에서 실행합니다.

bash
node ./statusline.cjs < ./mock.json

PowerShell에서는 다음처럼 입력을 전달합니다.

powershell
Get-Content -Raw -Encoding UTF8 ./mock.json | node ./statusline.cjs

예상 표준 출력은 다음 한 줄입니다.

테스트 모델 | 폴더 ? | git - | 컨텍스트 42% | 추정 USD 0.18

context_window.used_percentage를 null로 바꾸면 컨텍스트 ?, 숫자 0으로 바꾸면 컨텍스트 0%가 나와야 합니다. 폴더와 브랜치도 확인하려면 workspace.current_dir에 자신의 시험용 저장소 절대 경로를 추가합니다. 표시되는 폴더명과 브랜치가 그 저장소와 일치하는지 확인합니다. 현재 터미널의 폴더를 대신 조회하는 방식이 아닙니다.

이 예제는 모의 JSON, 누락·null·0·잘못된 자료형, 합성한 만료 시각과 별도 시험용 Git 저장소로 로컬 출력을 확인했습니다. 실제 Claude Code 화면이나 Windows 클라이언트에서 동작을 실측한 결과는 아닙니다.

3. 설정 파일에 실행 명령 연결

개인 기본값으로 쓰려면 사용자 설정 파일인 ~/.claude/settings.json에 statusLine 항목을 추가합니다. 아래는 기존 설정에 합칠 조각입니다. YOUR_NAME과 파일 경로를 실제 위치로 바꾸고, 기존 permissions 등 다른 항목은 보존합니다.

json
{
  "statusLine": {
    "type": "command",
    "command": "node \"/Users/YOUR_NAME/.claude/statusline.cjs\""
  }
}

Linux에서는 /home/YOUR_NAME/.claude/statusline.cjs처럼 실제 절대 경로를 사용합니다. node를 찾지 못하면 Node.js 실행 파일에도 절대 경로를 지정합니다. 이 예제는 인터프리터가 파일을 읽으므로 스크립트에 chmod +x가 필요하지 않습니다. 스크립트 자체를 직접 실행하는 방식이라면 실행 권한과 올바른 shebang이 필요합니다.

저장 후 해당 명령이 적용되는 Claude Code 세션에서 줄이 표시되는지 확인합니다. 대부분의 설정은 저장 시 다시 읽히며, statusLine.command 변경은 즉시 실행을 유발합니다. 스크립트 파일 내용만 바꾼 경우에는 다음 갱신 이벤트에 반영됩니다. 외부 터미널에서 한 줄이 나오더라도 Claude Code에서의 적용 범위와 실행 허용 조건은 별도로 확인해야 합니다. 설정 적용과 상태 표시줄 갱신

현재 JSON 필드: 컨텍스트, 비용, 구독 한도는 서로 다릅니다

모델은 문자열이 아니라 객체입니다. 이름에는 model.display_name, 식별자에는 model.id를 사용합니다. 현재 폴더는 workspace.current_dir 또는 cwd이고, workspace.project_dir는 시작 폴더이므로 이동 후 현재 폴더와 다를 수 있습니다. 현재 스키마에는 일반 브랜치용 git.branch가 없습니다. worktree.branch 등은 해당 worktree 세션에서만 나타나는 값이므로 일반 저장소 브랜치와 혼용하지 않습니다. 현재 입력 스키마

알고 싶은 값사용할 필드해석
지금 사용한 컨텍스트 비율context_window.used_percentage마지막 API 응답에 해당하는 현재 컨텍스트입니다. percentage라는 옛 필드는 사용하지 않습니다.
남은 컨텍스트 비율context_window.remaining_percentage값이 제공된 경우 표시합니다. 누락이나 null을 100% 남음으로 바꾸지 않습니다.
현재 입력 토큰context_window.total_input_tokens입력 토큰과 캐시 생성·읽기 토큰의 합입니다. 세션 전체 누적 사용량이 아닙니다.
세션 비용 추정cost.total_cost_usd클라이언트가 모델 가격을 기준으로 계산한 추정치이며 청구서가 아닙니다.
5시간·7일 사용 비율rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage해당 창의 사용한 비율입니다. 컨텍스트 비율이나 남은 비율이 아닙니다.
한도 창의 종료 시각각 창의 resets_atUnix 시각의 초 단위입니다. JavaScript 날짜 객체에 넣을 때는 1,000을 곱합니다.

컨텍스트 비율은 입력 토큰을 기준으로 하며 출력 토큰은 포함하지 않습니다. 예를 들어 입력 10,000, 캐시 생성 5,000, 캐시 읽기 25,000이면 현재 입력 합계는 40,000토큰입니다. 창 크기를 200,000토큰으로 가정하면 20%이며, 출력 토큰을 여기에 더해 계산하지 않습니다. /context는 아직 보내지 않은 새 메시지의 추정량도 포함할 수 있으므로 상태 표시줄보다 높은 값을 보이는 것이 곧 오류는 아닙니다. 컨텍스트 계산 설명

첫 API 응답 전이나 /compact 직후에는 current_usage와 비율이 null일 수 있습니다. ?는 데이터가 아직 없다는 표시이고 0%는 실제 숫자 0을 받았다는 표시입니다. 비용 0도 같은 원칙으로 처리합니다. /clear로 새 세션을 시작할 때 비용 추정치를 0으로 초기화하는 동작은 v2.1.211부터 적용되므로, 이전 버전에서 이어지는 값과 구분합니다. 시간 필드인 total_duration_ms와 total_api_duration_ms는 밀리초입니다. 비용·시간 필드

rate_limits는 첫 API 응답 이후, claude.ai Pro·Max 구독 또는 지출 한도가 있는 Claude apps gateway에서 제공됩니다. 5시간·7일·지출 한도 창은 각각 없을 수 있으며, resets_at이 지나면 해당 창은 제거됩니다. 예제도 만료된 5시간 창을 숨깁니다. 항목이 안 보인다고 사용량 0, 무제한, API 키 오류로 판단하지 않습니다. 사용 한도 필드의 적용 대상

추가 항목은 필요한 경우에만 넣습니다. Gateway의 spend_limit.used_percentage는 100을 넘을 수 있고 v2.1.251 이상이 필요합니다. used_usd, limit_usd, period는 클라이언트와 gateway 모두 v2.1.284 이상이어야 하며, 비율이 있어도 금액은 없을 수 있습니다. 금액은 약 5분 간격으로 별도 조회되어 늦게 반영될 수 있습니다. prompt_cache는 v2.1.251 이상에서 첫 응답 후 제공되는 주 대화의 캐시 통계이며, 하위 에이전트 호출을 포함하지 않습니다. 한 번의 캐시 표시만으로 비용 증가 원인을 확정하지 않습니다. 선택 필드와 버전 조건

개인 설정과 팀 공유 설정의 위치

개인 기본값은 사용자 설정, 프로젝트별 개인 설정은 로컬 설정, 팀이 함께 사용할 값은 공유 프로젝트 설정에 둡니다. 같은 키의 우선순위는 관리형 설정 → --settings로 지정한 설정 → 프로젝트 로컬 → 공유 프로젝트 → 사용자 설정 순입니다. 일부 키를 생략했다고 하위 범위의 다른 키가 모두 없어지는 것은 아닙니다. 설정 범위와 우선순위

범위일반적인 파일 또는 지정 방식사용할 때
사용자~/.claude/settings.json이 컴퓨터에서 사용하는 개인 기본값
프로젝트 로컬.claude/settings.local.json해당 프로젝트에서 자신만 다른 경로·표시를 사용할 때
공유 프로젝트.claude/settings.json검토한 스크립트와 설정을 저장소에 함께 공유할 때
임시 실행--settings특정 실행에서 설정을 지정할 때
관리형조직이 배포한 설정관리자가 허용한 구성을 적용할 때

Git worktree의 로컬 설정은 기본 checkout 쪽에 위치할 수 있으며, Windows·홈 디렉터리·소유권·버전에 따른 예외도 있습니다. 공유 설정은 주 작업 디렉터리에서 읽고, v2.1.246부터 /cd로 바꾼 디렉터리의 공유 설정도 읽습니다. 파일이 항상 지금 보고 있는 worktree 루트에 있다고 단정하기보다 /status의 Setting sources에서 실제로 읽은 파일 목록을 확인합니다. 이 목록은 각 키의 최종 출처를 하나씩 표시하는 목록은 아닙니다. 설정 파일 탐색 규칙

팀용이라면 모든 사람이 접근할 수 있는 저장소 경로에 스크립트를 두고 실행 환경도 문서화합니다. 예를 들어 프로젝트 루트에 tools/statusline.cjs를 둔다면 공유 설정에서 다음 조각을 사용할 수 있습니다.

json
{
  "statusLine": {
    "type": "command",
    "command": "node ./tools/statusline.cjs"
  }
}

이 조각은 tools/statusline.cjs와 Node.js가 준비되어 있고, 그 프로젝트 루트가 실행 작업 디렉터리인 경우를 전제로 합니다. 여러 프로젝트로 이동하며 쓸 개인 설정에는 앞의 절대 경로 방식이 더 분명합니다. 팀원이 실행할 코드이므로 개인 경로·비밀값·불필요한 외부 호출을 빼고 검토합니다.

값이 언제 갱신되나요?

상태 표시줄은 세션 시작·재개, 어시스턴트 메시지, /compact 완료, 권한 모드·Vim 모드 변화, 명령 변경 등의 이벤트에서 갱신됩니다. 공식 문서는 300ms 디바운스를 설명하며, 새 갱신이 오면 진행 중인 스크립트는 취소됩니다. 긴 작업이 반복해서 취소되면 결과가 잘 나오지 않을 수 있습니다. 갱신 시점

JSON에 있는 값만 보여 준다면 이벤트 갱신으로 시작합니다. 다른 프로그램에서 바뀌는 Git 브랜치나 시간 기반 표시를 유휴 상태에서도 반영하려면 statusLine 객체에 다음 항목을 추가할 수 있습니다.

json
"refreshInterval": 10

단위는 초이며 최소 1초입니다. 이 조각은 앞의 command 뒤에 쉼표를 넣고 같은 객체 안에 합칩니다. 타이머는 스크립트를 다시 실행하지만, 마지막 응답의 컨텍스트가 새로 측정되었다는 뜻은 아닙니다. 예제의 Git 조회는 다시 수행되어도 컨텍스트 값은 다음 API 응답까지 같을 수 있습니다.

폭을 맞추려면 Claude Code가 전달하는 COLUMNS·LINES를 사용합니다. 출력이 TTY에 직접 연결된 구조가 아니므로 tput cols로 실제 표시 폭을 얻는다고 가정하지 않습니다. 여러 줄, ANSI 색, OSC 8 링크도 지원되지만 터미널 기능과 좁은 폭에 따라 표시가 달라집니다. macOS Terminal.app은 클릭 가능한 OSC 8 링크를 지원하지 않습니다. 처음에는 예제처럼 일반 문자로 확인하는 편이 문제를 좁히기 쉽습니다. 표시 형식과 터미널 조건

Windows에서는 인터프리터와 경로를 명확히 지정하기

현재 공식 문서는 Windows에서 Git Bash가 설치되어 있으면 이를 사용하고, 없으면 PowerShell을 사용한다고 설명합니다. Windows에서 PowerShell 방식이 불가능하거나 Node.js만 쓸 수 있다는 설명은 맞지 않습니다. Windows 설정 예제

앞의 Node.js 스크립트를 쓴다면 사용자 설정은 다음처럼 작성할 수 있습니다. 이름과 설치 위치는 실제 환경에 맞게 바꿉니다.

json
{
  "statusLine": {
    "type": "command",
    "command": "node \"C:/Users/YOUR_NAME/.claude/statusline.cjs\""
  }
}

설정의 명령 경로에는 /를 사용하면 JSON의 역슬래시 이스케이프가 단순해집니다. node가 명령 실행 환경에서 검색되지 않으면 실행 파일을 따옴표로 감싼 절대 경로로 지정합니다. PowerShell 파일을 선택했다면 공식 문서처럼 powershell -NoProfile -File에 .ps1 경로를 넘기는 방식도 가능합니다.

Claude Code가 사용하는 셸에서 설정에 적은 동일한 명령에 모의 입력을 전달해 확인합니다. 수동 실행부터 실패한다면 파일 위치, 따옴표, 인터프리터 검색 경로를 먼저 고칩니다. 출력 문자가 깨지면 입력 파일의 UTF-8 인코딩과 해당 셸의 입출력 인코딩을 확인합니다. 터미널 글꼴과 Powerline 기호는 일반 텍스트가 보인 뒤에 추가합니다.

테마와 위젯이 필요하면 ccstatusline

ccstatusline은 TUI에서 여러 줄, 위젯, 테마와 Powerline 구성을 편집하고 미리 볼 수 있는 별도 프로젝트입니다. 표시 배치를 자주 바꾸는 경우에 선택할 이유가 있습니다. 프로젝트 README의 빠른 시작 명령은 다음과 같습니다. 패키지를 내려받아 실행하는 명령이므로 설치할 환경에서 내용을 확인한 후 선택합니다. 프로젝트 README

bash
npx -y ccstatusline@latest

Bun 환경에서는 README의 bunx -y ccstatusline@latest 경로도 있습니다. 초기 화면의 Pinned global install 선택은 해당 버전을 실제로 전역 설치하고 고정 버전의 실행 명령을 설정합니다. 고정·전역 설치 후에는 ccstatusline으로 TUI를 엽니다. 설정은 ~/.config/ccstatusline/settings.json에 보관합니다. README는 지원하는 Claude 버전에서 refreshInterval을 기록한다고 설명하며 그 기준을 v2.1.97 이상으로 명시합니다. 설치와 설정 방식

위젯은 모두 stdin JSON만 읽는 것은 아닙니다. 사용량 위젯은 자격 증명이나 macOS Keychain을 조회하고 Anthropic 사용량 API를 직접 호출할 수 있습니다. 일부 항목은 대화 기록·캐시를 읽고 서비스 상태 위젯은 네트워크 데이터를 사용합니다. 선택한 위젯이 무엇을 읽는지 확인해야 하며, 위의 자체 스크립트와 의존성이 같다고 볼 수 없습니다. 이 글에서는 패키지 설치, TUI 실행, Keychain 접근이나 사용량 API 호출을 시험하지 않았습니다. 위젯 데이터와 의존성

빈 줄·오래된 값·건너뛴 설정을 고치는 순서

상태 표시줄의 입력과 설정 범위를 확인하는 문제 해결 흐름

먼저 명령 출력 문제와 Claude Code가 명령을 선택하지 않는 문제를 나눕니다. 같은 명령에 모의 JSON을 전달했을 때 한 줄이 나온다면 스크립트의 기본 입력·출력은 확인한 것입니다. 이후에는 적용 파일, 실행 환경과 관리형 제한을 봅니다.

증상먼저 확인할 것다음 조치
모의 입력에서도 아무 출력이 없음종료 상태와 stderr, 파일·인터프리터 경로올바른 JSON과 명시적 실행 명령으로 수정합니다. stdout에 최종 문자열이 나오는지 확인합니다.
터미널에서는 되지만 Claude Code에서는 안 보임/status의 설정 파일 목록, 키 이름 statusLine, 상위 범위의 값적용 파일과 명령을 맞춘 뒤 아래 실행 허용 조건을 확인합니다.
컨텍스트 ?가 보임첫 API 응답 전인지, /compact 직후인지, used_percentage를 읽는지응답 후에도 같다면 필드명과 값의 자료형을 확인합니다. ?만으로 실행 실패라 판단하지 않습니다.
Git 브랜치가 다른 저장소의 값임workspace.current_dir·cwd에 대해 조회하는지제공된 폴더에 git -C로 조회하도록 고칩니다. 프로젝트 시작 폴더와 현재 폴더를 구분합니다.
외부에서 바꾼 브랜치가 유휴 상태에서 그대로임다음 갱신 이벤트가 있었는지필요하면 refreshInterval을 넣습니다. 컨텍스트의 새 측정과 혼동하지 않습니다.
결과가 나오다가 자주 사라짐느린 네트워크·Git 작업, 비정상 종료와 취소무거운 계산을 줄이고 단계별로 복원합니다. 도움말·권한 질문 중 잠깐 숨겨지는 현상도 구분합니다.
5시간 한도가 안 보임대상 계정·경로인지, 첫 응답 이후인지, 창이 만료됐는지누락을 미제공 상태로 처리합니다. 0이나 무제한으로 대체하지 않습니다.
Windows에서만 실행 실패같은 셸의 동일 명령과 경로 인용인터프리터 경로와 UTF-8 입출력을 확인합니다.

설정 JSON의 구문 오류나 잘못된 값도 확인합니다. 현재 클라이언트는 대화형 시작 시 잘못된 JSON과 알려진 유효하지 않은 값을 알리며, claude doctor로 거부된 설정 항목을 진단할 수 있습니다. 설정 오류가 항상 조용히 무시된다고 가정하지 않습니다. 설정 검증

정상 명령이 실행되지 않는 관리형 제한

상태 표시줄에는 다음 구분이 중요합니다.

  • 관리형 disableAllHooks: true 또는 신뢰되지 않은 작업 공간에서는 사용자 지정 상태 표시줄이 모두 꺼집니다.
  • allowManagedHooksOnly, 유효한 비관리형 disableAllHooks: true, --safe-mode에서는 관리형 설정에서 온 상태 표시줄만 실행할 수 있습니다. 개인·프로젝트·플러그인 값은 경고 없이 건너뛸 수 있으며, 관리자가 배포한 statusLine은 실행될 수 있습니다.
  • 관리자가 강제 활성화한 플러그인의 hook이 허용되어도 그 플러그인의 상태 표시줄까지 자동 허용되는 것은 아닙니다. statusLine 값 자체가 관리형 설정에서 와야 합니다.

명령과 설정 위치가 맞는데 조직의 제한에 해당한다면 관리자에게 허용된 구성을 확인합니다. 회사 정책을 끄거나 설정 파일 전체를 삭제하는 방식으로 해결하지 않습니다. 정확한 실행 제한

자주 묻는 질문

상태 표시줄이 모델 토큰을 추가로 사용하나요?

공식 stdin JSON을 읽고 문자열을 출력하는 자체 스크립트는 모델 요청을 하지 않습니다. 위 예제는 여기에 로컬 Git 조회만 추가합니다. 별도 도구의 위젯은 네트워크나 사용량 API를 호출할 수 있으므로 도구별 동작을 확인해야 합니다. 공식 실행 방식, ccstatusline 위젯

비용 추정치로 구독의 남은 한도를 계산해도 되나요?

계산하지 않는 것이 맞습니다. cost.total_cost_usd는 세션의 모델 가격 기준 추정치이며 실제 청구액이나 구독 잔여량이 아닙니다. 구독 사용 비율은 해당 계정에서 제공되는 rate_limits 창을 따로 읽습니다. 미제공 값을 비용으로 역산하지 않습니다. 비용과 사용 한도 필드

색상 없이 여러 줄로 만들어도 되나요?

가능합니다. 일반 상태 표시줄은 여러 줄 출력을 지원하며 색상은 필수가 아닙니다. 좁은 터미널이나 알림에 따라 줄 일부가 잘릴 수 있으므로 필요한 항목부터 배치합니다. 하위 에이전트용 subagentStatusLine은 별도의 JSON 출력 규칙이 있으므로 이 글의 문자열 출력을 그대로 연결하지 않습니다. 표시와 하위 에이전트 규칙

상태 표시줄을 끄려면 어떻게 하나요?

설정 파일에서 statusLine 항목만 제거하거나 /statusline에 없애 달라고 요청합니다. 다른 설정은 남겨 둡니다. 더 높은 범위에서 같은 키를 제공한다면 그 범위도 확인해야 합니다. 해제 방법, 설정 우선순위

참고 자료4

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026년 10월 8일.

  1. 1.공식 상태 표시줄 문서code.claude.com/docs/en/statusline
  2. 2.설정 범위와 우선순위code.claude.com/docs/en/settings
  3. 3.프로젝트 READMEgithub.com/sirmalloc/ccstatusline
  4. 4.정확한 실행 제한code.claude.com/docs/en/settings-reference
Claude Code에서 내장 스킬, 공식 스킬, 프로젝트 전용 스킬을 선택하는 시작 경로
Claude Code

Claude Code 스킬 추천: 작업별 첫 선택과 설치·확인 방법

코드의 버그를 찾으려면 /code-review, 변경한 코드를 정리하려면 /simplify부터 써보세요. 화면 디자인은 frontend-design, 반복적인 브라우저 검증은 webapp-testing이 후보입니다. 지금 필요한 작업에 맞춰 선택하고, 설치 목록과 실제 결과를 따로 확인하는 것이 좋습니다.

11 분
Claude Code에서 작업에 맞는 첫 MCP를 선택하는 경로
Claude Code

Claude Code MCP 추천: 용도별 첫 서버 선택과 설치 확인

PR과 이슈가 필요하면 GitHub, 버전별 문서가 필요하면 Context7, 브라우저 동작 확인은 Playwright, 운영 오류 조사는 Sentry가 첫 후보입니다. 이미 쓰는 도구로 충분한지 확인한 뒤, 필요한 서버 하나를 연결하고 실제 조회 결과까지 확인하세요.

10 분