Jinsi ya kuweka Claude Code statusline 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 inaandika kwenye standard output.

Huo ndio mkataba mzima. Script yako inasoma JSON kwenye stdin na kuchapisha maandishi kwenye stdout. Inaendeshwa kwenye mashine yako na hakuna chochote inachochapisha kinachotumwa kwa model, kwa hivyo haitumii tokens zozote.

Kwenye laptop yenye mradi mmoja, hii ni mapambo tu. Kwenye seva tatu, hii ni njia ya usalama. Kila session ya Claude Code inaonekana sawa katika kila terminal, kwa hivyo madirisha manne ya SSH yasiyo na lebo ndiyo njia ya kufanya makosa ya kuhamisha data kwenye seva isiyo sahihi. Statusline inayoanza na hostname inamaliza aina hiyo ya makosa.

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 hiyo.

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

type daima ni "command". Thamani ya command huendeshwa kupitia 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 ya kawaida ni 0. refreshInterval huendesha upya amri kila baada ya sekunde N juu ya vichochezi vya kawaida, na kiwango cha chini ni 1, ambacho unakihitaji tu wakati mstari unaonyesha saa au kitu kinachobadilika wakati kikao kimekaa bila kufanya kazi. hideVimModeIndicator huficha maandishi ya kawaida ya -- INSERT -- wakati script yako mwenyewe tayari inaonyesha hali ya vim.

Ni data gani script ya statusline hupokea?

Usiweke imani kwenye orodha ya field unayosoma popote, ikiwemo ukurasa huu. Nasa object halisi inayotumwa na toleo lako. Andika script ya muda mfupi 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 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 kuwa funguo bapa. model inashikilia id na display_name. workspace inashikilia current_dir na project_dir: current_dir ndipo session ilipo sasa, project_dir ndipo ilipozinduliwa, na mbili hizi 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 vihesabio vya muda. session_id ni thabiti kwa maisha yote ya session na ni ya kipekee katika session zote, jambo ambalo ni muhimu kwa caching baadaye.

Kanuni tatu huifanya script kubaki hai katika mabadiliko ya schema.

Funguo zingine hazipo, si null. vim, agent, pr, worktree na effort huonekana tu wakati kipengele kinacholingana kikiwa hai. Kusoma .vim.mode kwa kutumia jq -r wakati vim mode imezimwa huchapisha string halisi null, na bar yako inaonyesha null kwa msomaji. Ambatisha // empty kwenye kila selector, ili ufunguo usiopatikana usichapishe chochote.

Thamani zingine ni null mwanzoni. context_window.used_percentage na context_window.current_usage ni null kabla ya majibu ya kwanza ya API, na current_usage hurudi kuwa null baada ya /compact hadi wito unaofuata uijaze tena. Asilimia ya context kwenye bar kwa hiyo inahitaji // 0, au itasoma null kwa sekunde za kwanza za kila session. Kabla hujaweka namba hiyo kwenye bar, inasaidia kujua jinsi dirisha la context linavyojazwa kihalisi.

Tawi la git halimo 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 (fallback), 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 git -C "$DIR" badala ya git tupu, kwa hivyo tawi hulingana kila wakati na saraka inayoonyeshwa kwenye upau.

Ihifadhi, kisha uifanye iweze kutekelezeka:

chmod +x ~/.claude/statusline.sh

Bit ya kutekeleza (execute bit) si ya hiari. Claude Code huendesha amri kupitia shell, kwa hivyo hati isiyo na +x itashindwa na kutoa 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 hati kabla ya kuiamini

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

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

Utapata hostname, kisha /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 ndilo tukio baya zaidi ambalo mabadiliko ya schema yanaweza kukuletea. Mstari bado unachapishwa: hostname, saraka ya sasa kutoka $PWD, na neno claude pale jina la model linapopaswa kuwa. Hakuna kinachokwama na hakuna kinachochapisha null. Hati inayofaulu jaribio hili itastahimili uwanja (field) kubadilishwa jina, kwa sababu kwa hati yako, uwanja uliopata jina jipya na uwanja uliopotea ni tukio moja.

Unachopaswa kuona

Mstari wa hali (statusline) hujichora kwenye safu yake yenyewe juu ya beji za chini zilizojengewa ndani na hauzibadilishi. Katika usanidi unaofanya kazi, huu ni mstari mmoja: jina fupi la seva (hostname) 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 wakati saraka hiyo ni git repository, na mwishowe jina la modeli likiwa limefifishwa. Kitu kinachokaribia web-01 ~/api main Opus, kikiwa na sehemu hizo nne zikiwa na rangi.

Mstari huu huendesha hati yako upya wakati kikao (session) kinapoanza, ikijumuisha kurejesha kikao, ujumbe mpya wa msaidizi unapowasili, baada ya /compact kumaliza, wakati hali ya ruhusa (permission mode) inapobadilika, wakati hali ya vim inapogeuzwa, na kwenye tick ya refreshInterval ikiwa utaiweka. Masasisho hufanyiwa debounce kwa 300 ms, hivyo mfululizo wa mabadiliko huendesha hati 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) wanaoendelea kufanya kazi kwenye seva zaidi ya moja, terminal ndiyo kitu pekee kinachokuambia mahali ulipo, na terminal husema uongo. Fungua muunganisho wa pili wa ssh ukiwa ndani ya tmux pane na kichwa cha dirisha (window title) mara nyingi hubaki na jina la zamani, kwa sababu kichwa hicho huwekwa na shell ambayo haijui kuwa imehama. Acha Claude Code ikiendelea kufanya kazi kwenye detached tmux session kwenye VPS na uunganishe tena baada ya siku moja, na hakuna chochote kwenye skrini kitakachotofautisha seva ya build na ile ya production.

Statusline ni tofauti kwa sababu inatolewa na Claude Code yenyewe, kwa kila session, kutokana na data inayoshikiliwa na session hiyo. Haiwezi kurithiwa kutoka kwenye pane isiyo sahihi au kubaki imepitwa na wakati na shell prompt ambayo haijajirefresha. Inachokionyesha ndicho kisanduku (box) ambacho wakala anatumia kuandikia faili.

Ipe kila seva rangi yake ili uitambue kabla hata hujaisoma. 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 kisanduku na kila moja itajiwekea lebo yenyewe.

Saraka (directory) inastahili nafasi yake kwa sababu hiyo hiyo. /srv/api na /srv/api-staging ni vibonyezo tofauti kwenye amri ya ssh lakini vina matokeo tofauti kabisa wakati wa tukio (incident). 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 kwenye simu.

Dumisha kasi ya script

Script yako huendeshwa kwenye kila ujumbe wa assistant, na Claude Code husitisha utekelezaji unaoendelea wakati update mpya inapofika. Hivyo, script ya polepole huonyesha maandishi yaliyopitwa na wakati, au haionyeshi chochote.

Kila wito wa jq hugharimu milisekunde chache. git ndiyo sehemu inayopunguza kasi: git status katika repository kubwa yenye cache baridi huchukua mamia ya milisekunde. Script 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 cache katika faili na ukifanye upya kila baada ya sekunde chache. Tumia session kama ufunguo wa faili hilo:

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

Tumia session_id, si $$. $$ ni kitambulisho cha mchakato (process ID) cha script yako, ambacho ni tofauti katika kila uanzishaji, kwa hivyo cache inayotumia ufunguo huo haitawahi kupata data (cache miss) na utalipa gharama kamili kila wakati. session_id ni thabiti kwa session nzima na ni tofauti kati ya session mbalimbali, kwa hivyo session mbili za Claude Code katika repository mbili tofauti haziwezi kusoma jina la branch lililohifadhiwa na nyingine.

Kikomo kingine cha kuzingatia: tput cols haifanyi kazi ndani ya script ya statusline. Claude Code hunasa matokeo badala ya kuunganisha script yako kwenye terminal, kwa hivyo utambuzi wa upana (width detection) hauna cha kupima. Claude Code huweka vigezo vya mazingira (environment variables) 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 utekelezaji (execute bit) imewekwa kwa kutumia ls -l ~/.claude/statusline.sh, kisha endesha hati 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 hurekodi (log) exit code na stderr ya uendeshaji wa kwanza wa statusline katika kipindi hicho.

Log ya debug inasema Status line command skipped: workspace trust not accepted. Statusline hutekeleza amri ya shell, kwa hivyo inabaki nyuma ya kizuizi kilekile cha usalama wa workspace kama ilivyo kwa hooks. Hadi utakapokubali mazungumzo ya uaminifu (trust dialog) kwa saraka hiyo, amri hiyo haitawahi kutekelezwa. Hii ni 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 kizuizi kilekile cha utekelezaji wa shell. Iondoe au iweke kuwa false.

Mstari unachapisha null. Kichagua (selector) cha jq kimefikia 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 hati. Amri inayotoka (exit) kwa hali 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 tawi (branch) ni tupu na huchukua exit code ya hati nzima pamoja nayo. Weka printf mwisho, au ongeza exit 0.

Nambari za kutoroka (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 (output) kuwa 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 hazina (repository) na inashinda mipangilio mingine kwa saraka hiyo. Mipangilio hujipakia upya yenyewe, lakini mabadiliko huonekana tu kwenye trigger ya sasisho inayofuata, kama vile ujumbe wako unaofuata.

Kwa nini statusline yangu ya Claude Code haina kitu?

Sababu nne hufunika karibu visa vyote. Script inakosa ruhusa ya execute, kwa hivyo shell inarudisha Permission denied na hakuna kinachofika kwenye stdout. Dialog ya kuamini workspace haikukubaliwa, na claude --debug huandika kwenye logi Status line command skipped: workspace trust not accepted. disableAllHooks ni true, jambo linalozima statusline chini ya kizuizi hicho hicho. Au script inatoka na exit code isiyo sifuri, jambo linalofanya mstari kuwa wazi. Ijaribu kwa mkono kwanza: echo '{}' | ~/.claude/statusline.sh lazima ichapishe kitu.

Je, JSON ya statusline inajumuisha tawi la git?

Hapana. JSON inabeba hali ya session kama vile modeli, saraka za workspace, namba za dirisha la muktadha (context window) na gharama. Hakuna kitu ndani yake kinachoripoti git. Tawi kwenye upau wako linatokana na script yako mwenyewe inayopiga git branch --show-current. Pitisha saraka kutoka kwenye JSON ukitumia git -C "$DIR", ili tawi lilingane kila wakati na saraka ambayo upau unaonyesha.

Je, statusline inagharimu tokens au kupunguza kasi ya session?

Haigharimu tokens zozote, kwa sababu script inaendeshwa ndani ya mashine yako na matokeo yake hayatumwi kamwe kwa modeli. Kasi ni jukumu lako. Amri inaendeshwa kwenye kila ujumbe wa msaidizi na debounce ya 300 ms, na Claude Code inaghairi uendeshaji unaoendelea wakati sasisho jipya linapofika, kwa hivyo script inayochukua sekunde nzima itaonyesha maandishi ya zamani. Epuka git status katika hazina kubwa, na weka akiba (cache) ya kitu chochote cha polepole kwenye faili iliyowekewa alama na session_id.

Ninawezaje kuonyesha statusline tofauti kwenye kila seva?

Tumia script moja na uiruhusu isomwe na mashine. Script iliyo hapo juu inachapisha $HOSTNAME na hostname -s kama mbadala, kwa hivyo faili ile ile 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 hazina unayofanyia kazi kwenye kisanduku hicho, kwa kuwa mipangilio ya mradi inabatilisha mipangilio ya mtumiaji kwa saraka hiyo.