Jinsi ya kuweka statusline ya Claude Code kwenye VPS

Maana ya statusline ya Claude Code

Statusline ya Claude Code ni mstari ulio chini ya prompt unaoonyesha matokeo ya script unayoandika. Unaongeza block ya statusLine kwenye settings.json na kuielekeza kwenye command fulani. Claude Code huendesha command hiyo, hutuma hali ya session kwake kama JSON kupitia standard input, na kuchapisha chochote ambacho command hiyo inakiandika kwenye standard output.

Huo ndio mkataba mzima. Script yako inasoma JSON kwenye stdin na kuchapisha maandishi kwenye stdout. Inaendeshwa kwenye mashine yako na hakuna cho

Mahali ambapo mpangilio wa statusLine unapatikana katika settings.json

Uweke kwenye mipangilio yako ya mtumiaji katika ~/.claude/settings.json, ambayo inatumika kwa kila mradi kwenye mashine hiyo. Mipangilio ya mradi katika .claude/settings.json ndani ya hazina (repository) pia inafanya kazi, na hiyo ndiyo inayopewa kipaumbele kwa saraka (directory) husika.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

type daima ni "command". Thamani ya command hupitia kwenye shell, kwa hivyo inaweza kuwa njia ya script au amri ya kawaida. Thibitisha kuwa muunganisho unafanya kazi kabla ya kuandika script yoyote:

{
  "statusLine": {
    "type": "command",
    "command": "hostname -s"
  }
}

Anzisha Claude Code na utume ujumbe mmoja. Upau ulio chini ya prompt sasa unaonyesha jina fupi la seva (hostname). Ikiwa utabaki tupu, tatizo ni mpangilio au mazungumzo ya uaminifu (trust dialog), si script yako. Soma "Kwa nini statusline inabaki tupu" hapa chini.

Kuna funguo tatu za hiari kufikia Agosti 2026. padding huongeza nafasi ya mlalo kwa herufi na thamani yake chaguo-msingi ni 0. refreshInterval huendesha upya amri kila baada ya sekunde N juu ya vichochezi (triggers) vya kawaida, na kiwango cha chini ni 1, ambacho unakihitaji tu wakati mstari huo unaonyesha saa au kitu kinachobadilika wakati kikao kimekaa bila kufanya kazi. hideVimModeIndicator huficha maandishi ya ndani ya -- INSERT -- wakati script yako mwenyewe tayari inaonyesha hali ya vim.

Ni data gani script ya statusline hupokea?

Usiweke imani kwenye orodha ya field yoyote unayosoma, ikiwemo ukurasa huu. Nasa object halisi inayotumwa na toleo lako. Andika script ya muda inayohifadhi stdin kwenye faili:

cat > ~/.claude/statusline-capture.sh <<'EOF'
#!/bin/bash
cat > /tmp/statusline-input.json
echo "captured"
EOF
chmod +x ~/.claude/statusline-capture.sh

Elekeza statusLine.command kwenye faili hilo, anzisha session, na utume ujumbe mmoja. Bar inasoma captured. Sasa angalia kile kilichowasili:

jq . /tmp/statusline-input.json

Una umbo kamili kwa ajili ya build yako, na unaweza kurudia hili wakati wowote update inapobadilisha kitu.

Sehemu thabiti, kama zilivyoandikwa mnamo Agosti 2026, ni object zilizopangwa ndani ya nyingine badala ya keys bapa. model inashikilia id na display_name. workspace inashikilia current_dir na project_dir: current_dir ni mahali ambapo session ipo sasa, project_dir ni mahali ilipozinduliwa, na hizi mbili hutofautiana mara tu directory ya kazi inapobadilika katikati ya session. cwd ya ngazi ya juu inabeba thamani sawa na workspace.current_dir. context_window inashikilia idadi ya token pamoja na used_percentage iliyohesabiwa awali. cost inashikilia total_cost_usd na kaunta za muda. session_id ni thabiti kwa muda wote wa session na ni ya kipekee katika kila session, jambo ambalo ni muhimu kwa ajili ya caching baadaye.

Kanuni tatu huifanya script iendelee kufanya kazi wakati wa mabadiliko ya schema.

Baadhi ya keys hazipo, si kwamba ni null. vim, agent, pr, worktree na effort huonekana tu wakati kipengele husika kikiwa kimewashwa. Kusoma .vim.mode kwa kutumia jq -r wakati vim mode imezimwa huchapisha string halisi null, na bar yako huonyesha null kwa msomaji. Ongeza // empty kwenye kila selector, ili key inayokosekana isichapishe chochote.

Baadhi ya thamani huwa null mwanzoni. context_window.used_percentage na context_window.current_usage huwa null kabla ya majibu ya kwanza ya API, na current_usage hurudi kuwa null baada ya /compact hadi call inayofuata itakapoiijaza tena. Kwa hiyo, asilimia ya muktadha kwenye bar inahitaji // 0, vinginevyo itasoma null kwa sekunde za kwanza za kila session. Kabla hujaweka namba hiyo kwenye bar, inasaidia kujua jinsi dirisha la muktadha linavyojazwa kihalisi.

Tawi la git halipo kwenye JSON. Hakuna field inayoliripoti. Tawi lolote kwenye bar yako linatokana na script yako kuendesha git yenyewe.

Hati ya statusline inayopunguza utendaji badala ya kuharibika

Hii ni toleo la kunakili na kubandika. Inachapisha hostname, saraka ya sasa (working directory), tawi la git, na jina la modeli. Kila sehemu ina njia mbadala, kwa hivyo hata kitu cha JSON tupu bado hutoa mstari unaoweza kutumika.

#!/bin/bash
# ~/.claude/statusline.sh
input=$(cat)

# Read one field. Prints nothing when the key is missing or null.
field() { printf '%s' "$input" | jq -r "$1 // empty" 2>/dev/null; }

HOST=$(hostname -s 2>/dev/null)
[ -z "$HOST" ] && HOST="host"

DIR=$(field '.workspace.current_dir')
[ -z "$DIR" ] && DIR=$(field '.cwd')
[ -z "$DIR" ] && DIR="$PWD"

MODEL=$(field '.model.display_name')
[ -z "$MODEL" ] && MODEL="claude"

SHORT="$DIR"
if [ -n "$HOME" ]; then
  case "$DIR" in
    "$HOME") SHORT="~" ;;
    "$HOME"/*) SHORT="~/${DIR#"$HOME"/}" ;;
  esac
fi

BRANCH=""
if git -C "$DIR" rev-parse --git-dir >/dev/null 2>&1; then
  BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
  [ -z "$BRANCH" ] && BRANCH="detached"
fi

CYAN=$'\033[36m'
YELLOW=$'\033[33m'
DIM=$'\033[2m'
RESET=$'\033[0m'

LINE="${CYAN}${HOST}${RESET} ${SHORT}"
[ -n "$BRANCH" ] && LINE="${LINE} ${YELLOW}${BRANCH}${RESET}"
LINE="${LINE} ${DIM}${MODEL}${RESET}"

printf '%s\n' "$LINE"

Kila usomaji hupitia field, ambayo huongeza // empty, kwa hivyo ufunguo uliopatiwa jina jipya au kuondolewa hutoa kamba tupu na mstari unaofuata hutoa thamani chaguo-msingi. Saraka hurejea kutoka workspace.current_dir kwenda cwd hadi $PWD. Tawi hutoka kwenye git -C "$DIR" badala ya git tupu, kwa hivyo tawi daima hulingana na saraka inayoonyeshwa kwenye upau.

Ihifadhi, kisha ifanye iweze kutekelezeka:

chmod +x ~/.claude/statusline.sh

Bit ya kutekeleza si ya hiari. Claude Code huendesha amri kupitia shell, kwa hivyo hati isiyo na +x itashindwa na Permission denied, haitatoa stdout yoyote, na mstari utabaki tupu bila kosa linaloonekana.

jq huchanganua JSON kwenye mstari wa amri na haijasakinishwa kwenye seva mpya ya Ubuntu:

sudo apt update && sudo apt install -y jq

Kisha elekeza mpangilio kwenye hati hiyo, kwa kutumia kizuizi cha kwanza cha settings.json hapo juu.

Jaribu script kabla ya kuiamini

Iendeshe mara mbili kwa mkono. Kwanza ukiwa na object ya session ya kawaida:

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/srv/api"},"session_id":"t1"}' | ~/.claude/statusline.sh

Utapata hostname, ikifuatiwa na /srv/api, kisha Opus. Hakuna branch inayoonekana, kwa sababu /srv/api kwenye mashine yako pengine si git repository.

Pili, jaribio la degradation, ambalo ndilo watu huliruka:

echo '{}' | ~/.claude/statusline.sh

Object tupu ndiyo hali mbaya zaidi inayoweza kutokea kutokana na mabadiliko ya schema. Mstari bado unachapisha: hostname, saraka ya sasa kutoka $PWD, na neno claude mahali ambapo jina la model linapaswa kuwa. Hakuna kinachokwama na hakuna kinachochapisha null. Script inayopita jaribio hili itastahimili uwanja (field) kubadilishwa jina, kwa sababu kwa script yako, uwanja uliopata jina jipya na uwanja uliopotea ni tukio moja.

Unachopaswa kuona

Statusline hujichora kwenye mstari wake yenyewe juu ya beji za chini zilizojengewa ndani na haizichukui nafasi yake. Kwenye usanidi unaofanya kazi, huu ni mstari mmoja: hostname fupi kwa rangi ya cyan, ikifuatiwa na saraka ya sasa (working directory) huku saraka yako ya nyumbani ikiwa imefupishwa kuwa ~, kisha jina la branch kwa rangi ya manjano ikiwa saraka hiyo ni git repository, na mwishowe jina la model likiwa limefifishwa. Kitu kinachokaribia web-01 ~/api main Opus, kikiwa na sehemu hizo nne zikiwa na rangi zake.

Mstari huu huendesha script yako upya wakati session inapoanza, ikiwemo kurejelea (resume), ujumbe mpya wa assistant unapowasili, baada ya /compact kumaliza, hali ya ruhusa (permission mode) inapobadilika, vim mode inapogeuzwa, na kwenye tick ya refreshInterval ikiwa utaiweka. Masasisho hufanyiwa debounce kwa 300 ms, hivyo mfululizo wa mabadiliko huendesha script hiyo mara moja tu. Upau huu hujificha wakati wa autocomplete, menyu ya usaidizi na maombi ya ruhusa, kisha hurudi tena.

Kwa nini hostname inapaswa kuwa ya kwanza

Unapokuwa na mawakala (agents) wanaoendesha kwenye seva zaidi ya moja, terminal ndiyo kitu pekee kinachokuambia mahali ulipo, na terminal hudanganya. Fungua muunganisho wa pili wa ssh kutoka ndani ya tmux pane na kichwa cha dirisha mara nyingi hubaki na jina la zamani, kwa sababu kichwa hicho huwekwa na shell ambayo haijui kuwa imehama. Acha Claude Code ikiendesha kwenye detached tmux session kwenye VPS na uunganishe tena baada ya siku moja, na hakuna kitu kwenye skrini kinachotofautisha seva ya build na ile ya production.

Statusline ni tofauti kwa sababu inatolewa na Claude Code yenyewe, kwa kila session, kutoka kwa data ambayo session hiyo inashikilia. Haiwezi kurithiwa kutoka kwenye pane isiyo sahihi au kubaki imepitwa na wakati na shell prompt ambayo haijajirefresha. Inachosema ndiyo seva ambayo wakala anatumia kuandikia faili.

Ipe kila seva rangi yake ili uweze kuitambua kabla ya kuisoma. Mistari miwili, iliyowekwa juu ya assignment ya LINE=:

CODE=$(printf '%s' "$HOST" | cksum | cut -d' ' -f1)
HOST_COLOR=$(printf '\033[%dm' "$((31 + CODE % 6))")

Kisha tumia ${HOST_COLOR} badala ya ${CYAN}. cksum huchapisha checksum ya hostname, hivyo jina fulani hupewa rangi ileile kila wakati katika safu ya 31 hadi 36, ambayo ni kuanzia nyekundu hadi cyan. Nakili hati hiyo hiyo kwenye kila seva na kila moja itajiwekea lebo yenyewe.

Saraka (directory) inastahili nafasi yake kwa sababu hiyo hiyo. /srv/api na /srv/api-staging ni vibonyezo tofauti kwa hatua moja tu katika amri ya ssh lakini vina matokeo tofauti kabisa wakati wa hitilafu. Model na branch ni vitu vingine viwili vinavyostahili nafasi hiyo: model inakuambia ni session ipi uliyoendeleza, na branch inakuambia kama wakala anakaribia kufanya commit kwenye main.

Skrini ndogo hufanya yote haya kuwa wazi zaidi, kwa sababu hakuna kichwa cha dirisha cha kutegemea. Ikiwa huo ndio usanidi wako, angalia kuendesha Claude Code kutoka kwa simu.

Dumisha kasi ya hati

Hati yako huendeshwa katika kila ujumbe wa msaidizi, na Claude Code husitisha utekelezaji unaoendelea wakati sasisho jipya linapowasili. Hivyo, hati ya polepole huonyesha maandishi yaliyopitwa na wakati, au haionyeshi maandishi yoyote.

Kila mwito wa jq huchukua milisekunde chache. git ndiyo sehemu inayopunguza kasi: git status katika hazina kubwa (repository) yenye cache baridi huchukua mamia ya milisekunde. Hati iliyo hapo juu huepuka git status kwa makusudi na kuita git branch --show-current, ambayo husoma .git/HEAD na kurejesha matokeo mara moja.

Ukiongeza kitu kizito zaidi, kihifadhi kwenye faili na ukisasishe kila baada ya sekunde chache. Tumia kipengele cha session kama ufunguo wa faili hiyo:

CACHE="/tmp/statusline-$(field '.session_id')"

Tumia session_id, si $$. $$ ni kitambulisho cha mchakato (process ID) cha hati yako, ambacho ni tofauti katika kila uanzishaji, kwa hivyo cache inayotumia ufunguo huo haitawahi kupata data (cache miss) na utalazimika kulipia gharama kamili kila wakati. session_id ni thabiti kwa kipindi chote cha session na ni tofauti kati ya session moja na nyingine, kwa hivyo session mbili za Claude Code katika hazina mbili tofauti haziwezi kusoma jina la branch lililohifadhiwa na nyingine. Session hubaki zimetengwa hivyo kwa usanifu, kwa hivyo kuifanya moja ikabidhi kazi kwa nyingine huhitaji hatua ya makusudi, ambayo ndiyo kazi ya kutuma ujumbe kutoka session moja ya Claude Code kwenda nyingine.

Kikomo kingine kinachofaa kujulikana: tput cols haifanyi kazi ndani ya hati ya statusline. Claude Code hunasa matokeo badala ya kuunganisha hati yako kwenye terminal, kwa hivyo utambuzi wa upana hauna cha kupima. Claude Code huweka vigezo vya mazingira vya COLUMNS na LINES kabla ya kuendesha amri, katika toleo la v2.1.153 na kuendelea, kwa hivyo soma $COLUMNS unapohitaji kuamua ni kiasi gani cha kuchapisha.

Kwa nini mstari wa hali (statusline) unabaki wazi

Hakuna kinachoonekana kabisa. Hakikisha bit ya execute imewekwa kwa kutumia ls -l ~/.claude/statusline.sh, kisha endesha script hiyo kwa mkono ukitumia data ya majaribio (mock input) iliyo hapo juu. Ikiwa inachapisha mstari kwenye shell lakini si katika Claude Code, anza na claude --debug, ambayo inarekodi exit code na stderr ya uendeshaji wa kwanza wa statusline katika kikao hicho.

Log ya debug inasema Status line command skipped: workspace trust not accepted. Statusline huendesha amri ya shell, kwa hivyo inakaa nyuma ya lango lilelile la uaminifu wa workspace (workspace trust gate) kama hooks. Hadi utakapokubali mazungumzo ya uaminifu (trust dialog) kwa saraka hiyo, amri hiyo haitaendeshwa kamwe. Hili ni jambo la kawaida kwenye VPS, ambapo kila clone mpya ni saraka ambayo Claude Code haijawahi kuiona. Anzisha upya Claude Code katika saraka hiyo na ukubali mazungumzo hayo.

Kila kitu ni wazi na disableAllHooks imewekwa. "disableAllHooks": true katika settings.json huzima statusline pia, kwa sababu ni lango lilelile la uendeshaji wa shell. Iondoe au iweke kuwa false.

Mstari unachapisha null. Selector ya jq imefikia ufunguo (key) ambao haupo au ni null, na jq -r huchapisha null kama herufi nne null. Ongeza // empty kwa maandishi na // 0 kwa namba.

Mstari unakuwa wazi mara tu baada ya kuhariri script. Amri inayotoka (exit) kwa thamani isiyo ya sifuri, au isiyochapisha chochote, hufuta mstari huo. Sababu ya kawaida ni mstari wa mwisho kama [ -n "$BRANCH" ] && LINE="...", ambao hutoa exit code 1 wakati branch haina kitu na kuchukua exit code ya script nzima pamoja nayo. Weka printf mwisho, au ongeza exit 0.

Escape codes zinaonekana kama maandishi ya kawaida kama vile \e]8;; kwenye upau. Tumia printf '%b' badala ya echo -e. Viungo vya OSC 8 vinavyoweza kubofya pia vinahitaji terminal inayounga mkono, na tmux au SSH inaweza kuondoa mfuatano huo, kwa hivyo rangi ya kawaida ndiyo chaguo salama zaidi kwenye mashine ya mbali (remote box).

Upande wa kulia wa mstari umekatwa. Arifa za mfumo na kaunta ya token ya verbose-mode hushiriki mstari huo kutoka upande wa kulia, na terminal nyembamba hupoteza sehemu hiyo inayopishana. Weka matokeo mafupi. Kwa hesabu halisi ya matumizi badala ya namba kwenye upau, angalia jinsi Claude Code inavyohesabu token.

FAQ

Mpangilio wa statusline ya Claude Code unapatikana wapi?

Katika settings.json, kama block ya statusLine ambapo type imewekwa kuwa "command" na command imewekwa kuwa njia ya script au amri ya shell. Mipangilio ya mtumiaji iko katika ~/.claude/settings.json na inatumika kwa kila mradi kwenye mashine hiyo. Mipangilio ya mradi iko katika .claude/settings.json ndani ya repository na inashinda mipangilio mingine kwa saraka hiyo. Mipangilio hujipakia upya yenyewe, lakini mabadiliko huonekana tu kwenye trigger ya update inayofuata, kama vile ujumbe wako unaofuata.

Kwa nini statusline ya Claude Code yangu haina kitu?

Sababu nne hufunika karibu kila kitu. Script inakosa execute bit, kwa hivyo shell inarudisha Permission denied na hakuna kinachofika kwenye stdout. Dialog ya workspace trust haikukubaliwa kamwe, na claude --debug inarekodi Status line command skipped: workspace trust not accepted. disableAllHooks ni true, jambo ambalo huzima statusline chini ya kizuizi hicho hicho. Au script inatoka kwa status isiyo ya sifuri, jambo ambalo hufuta mstari huo. Ijaribu kwa mkono kwanza: echo '{}' | ~/.claude/statusline.sh lazima ichapishe kitu.

Je, JSON ya statusline inajumuisha git branch?

Hapana. JSON inabeba hali ya session kama vile model, saraka za workspace, namba za context window na gharama. Hakuna kitu ndani yake kinachoripoti git. Branch kwenye bar yako inatoka kwenye script yako mwenyewe inayopiga git branch --show-current. Pitisha saraka kutoka kwenye JSON na git -C "$DIR", ili branch iendane kila wakati na saraka ambayo bar inaonyesha.

Je, statusline inagharimu tokens au kupunguza kasi ya session?

Haigharimu tokens, kwa sababu script inaendeshwa ndani ya mashine (locally) na matokeo yake hayatumwi kamwe kwa model. Kasi ni jukumu lako. Amri inaendeshwa kwenye kila ujumbe wa assistant ikiwa na debounce ya 300 ms, na Claude Code inaghairi uendeshaji unaoendelea wakati update mpya inapofika, kwa hivyo script inayochukua sekunde nzima itaonyesha maandishi ya zamani. Epuka git status katika repository kubwa, na weka cache ya chochote kinachochelewa kwenye faili iliyowekewa alama ya session_id.

Ninawezaje kuonyesha statusline tofauti kwenye kila seva?

Tumia script moja na uiruhusu isome mashine. Script iliyo hapo juu inachapisha $HOSTNAME ikiwa na hostname -s kama fallback, kwa hivyo faili moja iliyonakiliwa kwenye kila kisanduku inatambulisha kila moja kwa usahihi, na mbinu ya rangi ya checksum inapa kila hostname rangi yake. Ikiwa seva moja inahitaji mpangilio tofauti, weka block ya statusLine katika mipangilio ya mradi ya repository unayofanyia kazi kwenye kisanduku hicho, kwa kuwa mipangilio ya mradi inashinda mipangilio ya mtumiaji kwa saraka hiyo.