VPS پر Claude Code statusline کیسے بنائیں

Claude Code کی statusline کیا دکھاتی ہے

Claude Code کی statusline، prompt کے نیچے ایک سطر ہوتی ہے جو آپ کی لکھی ہوئی script کا output دکھاتی ہے۔ آپ statusLine block کو settings.json میں شامل کرتے ہیں اور اسے ایک command کی طرف point کرتے ہیں۔ Claude Code وہ command چلاتا ہے، session state کو JSON کی صورت میں standard input پر بھیجتا ہے، اور command کے standard output پر لکھی ہوئی ہر چیز دکھاتا ہے۔

یہی مکمل contract ہے۔ آپ کی script stdin سے JSON پڑھتی ہے اور stdout پر text لکھتی ہے۔ یہ آپ کی machine پر چلتی ہے، اور اس کا کوئی بھی output model کو نہیں بھیجا جاتا۔ اس لیے اس پر کوئی tokens خرچ نہیں ہوتے۔

ایک project والے laptop پر یہ صرف ظاہری سجاوٹ ہے۔ تین servers پر یہ حفاظتی سہارا بن جاتی ہے۔ ہر terminal میں ہر Claude Code session ایک جیسا دکھائی دیتا ہے، اس لیے بغیر labels والی چار SSH windows میں migration کو غلط server پر چلانا آسان ہے۔ hostname سے شروع ہونے والی statusline اس قسم کی غلطی کو روکتی ہے۔

settings.json میں statusLine setting کہاں موجود ہوتی ہے

اسے اپنی user settings میں ~/.claude/settings.json پر شامل کریں۔ یہ اسی machine کے ہر project پر لاگو ہوتی ہے۔ Repository کے اندر موجود project settings، یعنی .claude/settings.json، بھی کام کرتی ہیں اور اس directory کے لیے ترجیح رکھتی ہیں۔

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

type ہمیشہ "command" ہوتی ہے۔ command کی value ایک shell کے ذریعے چلتی ہے، اس لیے یہ script path یا سادہ command ہو سکتی ہے۔ کوئی script لکھنے سے پہلے تصدیق کریں کہ wiring درست کام کر رہی ہے:

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

Claude Code شروع کریں اور ایک message بھیجیں۔ اب prompt کے نیچے موجود bar میں server کا مختصر hostname دکھائی دے گا۔ اگر یہ خالی رہے تو مسئلہ setting یا trust dialog میں ہے، آپ کی script میں نہیں۔ نیچے موجود "statusline خالی کیوں رہتی ہے" پڑھیں۔

August 2026 تک 3 اختیاری keys موجود ہیں۔ padding حروف میں افقی spacing شامل کرتی ہے اور اس کی default value 0 ہے۔ refreshInterval معمول کے triggers کے علاوہ ہر N seconds بعد command دوبارہ چلاتی ہے، جس کی کم از کم value 1 ہے۔ اسے صرف اس وقت استعمال کریں جب line میں clock یا session کے idle رہنے کے دوران تبدیل ہونے والی کوئی چیز دکھائی جاتی ہو۔ hideVimModeIndicator built-in -- INSERT -- text کو چھپا دیتی ہے، جب آپ کی اپنی script vim mode پہلے ہی render کرتی ہو۔

statusline script کو کون سا data ملتا ہے؟

کسی بھی جگہ پڑھی ہوئی field list پر اعتماد نہ کریں، اس صفحے پر بھی نہیں۔ اصل object capture کریں جو آپ کا version بھیجتا ہے۔ ایک عارضی script لکھیں جو stdin کو file میں محفوظ کرے:

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

statusLine.command کو اس file کی طرف point کریں، session شروع کریں، اور ایک message بھیجیں۔ bar captured کو پڑھتی ہے۔ اب دیکھیں کہ کیا موصول ہوا:

jq . /tmp/statusline-input.json

آپ کے build کے لیے exact structure موجود ہے، اور جب بھی update کسی چیز کو تبدیل کرے تو آپ یہ عمل دوبارہ کر سکتے ہیں۔

August 2026 میں دستاویزی طور پر مستحکم حصے flat keys کے بجائے nested objects ہیں۔ model میں id اور display_name شامل ہیں۔ workspace میں current_dir اور project_dir شامل ہیں: current_dir موجودہ session کی جگہ ہے، project_dir وہ جگہ ہے جہاں session شروع کیا گیا تھا، اور working directory session کے دوران تبدیل ہونے پر دونوں مختلف ہو جاتے ہیں۔ top-level cwd میں workspace.current_dir جیسی value ہوتی ہے۔ context_window میں token counts اور پہلے سے calculated used_percentage شامل ہوتا ہے۔ cost میں total_cost_usd اور duration counters شامل ہوتے ہیں۔ session_id پورے session کے دوران مستحکم رہتا ہے اور sessions کے درمیان منفرد ہوتا ہے، جو بعد میں caching کے لیے اہم ہے۔

یہ تین اصول schema changes کے بعد بھی script کو فعال رکھتے ہیں۔

کچھ keys موجود نہیں ہوتیں، null نہیں ہوتیں۔ vim، agent، pr، worktree اور effort صرف اس وقت ظاہر ہوتے ہیں جب متعلقہ feature فعال ہو۔ vim mode بند ہونے پر jq -r کے ساتھ .vim.mode پڑھنے سے literal string null چھپتی ہے، اور bar پڑھنے والے کو null دکھاتی ہے۔ ہر selector کے آخر میں // empty شامل کریں، تاکہ missing key کی صورت میں کچھ بھی ظاہر نہ ہو۔

کچھ values ابتدا میں null ہوتی ہیں۔ پہلی API response سے پہلے context_window.used_percentage اور context_window.current_usage null ہوتے ہیں، اور /compact کے بعد current_usage دوبارہ null ہو جاتا ہے، جب تک اگلی call اسے دوبارہ پُر نہ کرے۔ اس لیے bar پر context percentage دکھانے کے لیے // 0 درکار ہے، ورنہ ہر session کے ابتدائی seconds میں null پڑھا جائے گا۔ اس number کو bar پر رکھنے سے پہلے یہ جاننا مفید ہے کہ context window حقیقت میں کیسے بھرتی ہے۔

git branch JSON میں شامل نہیں ہوتی۔ کوئی field اسے report نہیں کرتی۔ bar پر دکھائی جانے والی branch آپ کی script کے خود git چلانے سے آتی ہے۔

ایسی statusline script جو خراب ہونے کے بجائے محدود حالت میں بھی کام کرتی رہے

یہ copy-paste ورژن ہے۔ یہ hostname، working directory، git branch اور model name دکھاتا ہے۔ ہر field کے لیے fallback موجود ہے، اس لیے خالی JSON object بھی استعمال کے قابل line تیار کرتا ہے۔

#!/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"

ہر read field کے ذریعے ہوتی ہے، جو // empty شامل کرتا ہے۔ اس لیے renamed یا removed key خالی string دیتی ہے، اور اگلی line default فراہم کرتی ہے۔ Directory کے لیے fallback ترتیب workspace.current_dir، پھر cwd، پھر $PWD ہے۔ Branch براہِ راست git کے بجائے git -C "$DIR" سے حاصل ہوتی ہے، اس لیے branch ہمیشہ اسی directory سے مطابقت رکھتی ہے جسے bar دکھا رہا ہے۔

اسے save کریں، پھر executable بنائیں:

chmod +x ~/.claude/statusline.sh

Execute bit اختیاری نہیں ہے۔ Claude Code command کو shell کے ذریعے چلاتا ہے، اس لیے +x کے بغیر script Permission denied کے ساتھ fail ہو جاتی ہے، کوئی stdout پیدا نہیں کرتی، اور row بغیر کسی نمایاں error کے خالی رہتی ہے۔

jq command line پر JSON parse کرتا ہے اور fresh Ubuntu server پر installed نہیں ہوتا:

sudo apt update && sudo apt install -y jq

پھر setting کو script کی طرف point کریں۔ اس کے لیے اوپر موجود پہلے settings.json block کا استعمال کریں۔

اسکرپٹ پر اعتماد کرنے سے پہلے اس کی جانچ کریں

اسے ہاتھ سے دو مرتبہ چلائیں۔ پہلی مرتبہ عام session object کے ساتھ:

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

آپ کو hostname، پھر /srv/api، اور اس کے بعد Opus ملے گا۔ کوئی branch ظاہر نہیں ہوگی، کیونکہ آپ کی مشین پر /srv/api غالباً git repository نہیں ہے۔

دوسری مرتبہ degradation test چلائیں، جسے لوگ عموماً چھوڑ دیتے ہیں:

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

خالی object وہ بدترین صورت ہے جو schema میں تبدیلی آپ کو دے سکتی ہے۔ لائن پھر بھی hostname، $PWD سے موجودہ directory، اور جہاں model name آنا چاہیے وہاں claude کا لفظ پرنٹ کرتی ہے۔ کچھ بھی crash نہیں ہوتا اور null بھی پرنٹ نہیں ہوتا۔ جو اس test میں کامیاب ہو، وہ اس وقت بھی درست رہتا ہے جب کوئی field rename ہو جائے، کیونکہ آپ کے اسکرپٹ کے لیے renamed field اور missing field ایک ہی واقعہ ہیں۔

آپ کو کیا نظر آنا چاہیے

statusline اپنی الگ row میں built-in footer badges کے اوپر render ہوتی ہے اور ان کی جگہ نہیں لیتی۔ درست setup میں یہ ایک row ہوتی ہے: پہلے cyan رنگ میں مختصر hostname، پھر working directory، جس میں آپ کی home directory کو ~ تک مختصر کیا جاتا ہے، اس کے بعد جب directory ایک git repository ہو تو yellow رنگ میں branch name، اور آخر میں مدھم رنگ میں model name۔ مجموعی شکل web-01 ~/api main Opus سے ملتی جلتی ہوگی، اور یہ چاروں حصے رنگین ہوں گے۔

یہ row session شروع ہونے پر، resume سمیت، نیا assistant message آنے پر، /compact مکمل ہونے کے بعد، permission mode تبدیل ہونے پر، vim mode toggle ہونے پر، اور اگر آپ نے ایسا interval مقرر کیا ہو تو refreshInterval کے ہر tick پر آپ کی script دوبارہ چلاتی ہے۔ Updates میں 300 ms کی debounce ہوتی ہے، اس لیے تبدیلیوں کے ایک مختصر سلسلے میں script صرف ایک بار چلتی ہے۔ autocomplete، help menu اور permission prompts کے دوران bar چھپ جاتی ہے، پھر دوبارہ ظاہر ہو جاتی ہے۔

ہوسٹ نیم پہلے کیوں ہونا چاہیے

جب آپ ایک سے زیادہ سرورز پر agents چلا رہے ہوں تو terminal ہی یہ بتاتا ہے کہ آپ کہاں ہیں، اور terminals پر ہمیشہ بھروسا نہیں کیا جا سکتا۔ کسی tmux pane کے اندر سے دوسرا ssh connection کھولیں تو window title اکثر پرانا نام برقرار رکھتا ہے، کیونکہ title ایسے shell نے set کیا ہوتا ہے جسے یہ معلوم ہی نہیں ہوتا کہ وہ دوسری جگہ منتقل ہو چکا ہے۔ VPS پر Claude Code کو detached tmux session میں چلتا چھوڑیں اور ایک دن بعد دوبارہ attach کریں، تو اسکرین پر build server اور production box میں فرق کرنے والی کوئی چیز نہیں رہتی۔

statusline مختلف ہے، کیونکہ اسے Claude Code خود، ہر session کے لیے، اس session میں موجود data سے render کرتا ہے۔ یہ غلط pane سے inherit نہیں ہو سکتی اور نہ ہی ایسے shell prompt کی وجہ سے پرانی رہتی ہے جو refresh نہ ہوا ہو۔ اس میں جو نام دکھتا ہے، وہی وہ box ہے جس پر agent files لکھ رہا ہے۔

ہر server کے لیے الگ colour مقرر کریں تاکہ پڑھنے سے پہلے ہی اسے پہچان سکیں۔ LINE= assignment کے اوپر یہ دو lines شامل کریں:

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

اس کے بعد ${CYAN} کی جگہ ${HOST_COLOR} استعمال کریں۔ cksum hostname کا checksum print کرتا ہے، اس لیے ہر نام ہمیشہ 31 سے 36 کے range میں ایک ہی colour سے map ہوتا ہے؛ یہ colours red سے cyan تک ہیں۔ یہی script ہر box پر copy کریں، اور ہر box اپنا label خود دکھائے گا۔

directory بھی اسی وجہ سے اہم ہے۔ /srv/api اور /srv/api-staging کے درمیان ssh command میں صرف ایک keystroke کا فرق ہے، لیکن اثر کے لحاظ سے پورا incident پیدا ہو سکتا ہے۔ model اور branch باقی دو معلومات ہیں جن کے لیے یہ جگہ دینا مفید ہے: model بتاتا ہے کہ آپ نے کون سا session resume کیا ہے، اور branch بتاتی ہے کہ agent main پر commit کرنے والا ہے یا نہیں۔

چھوٹی اسکرین پر یہ سب زیادہ اہم ہو جاتا ہے، کیونکہ وہاں window title کا متبادل موجود نہیں ہوتا۔ اگر آپ کا setup ایسا ہے تو فون سے Claude Code چلانے کا طریقہ دیکھیں۔

اسکرپٹ کو تیز رکھیں

آپ کا اسکرپٹ ہر assistant message پر چلتا ہے، اور نیا update آنے پر Claude Code جاری run کو منسوخ کر دیتا ہے۔ اس لیے سست اسکرپٹ پرانا متن دکھا سکتا ہے یا کوئی متن نہیں دکھاتا۔

ہر jq call پر چند milliseconds خرچ ہوتے ہیں۔ git وہ حصہ ہے جو سست ہو جاتا ہے: cold cache کے ساتھ بڑی repository میں git status کو مکمل ہونے میں سیکڑوں milliseconds لگ سکتے ہیں۔ اوپر دیا گیا اسکرپٹ جان بوجھ کر git status سے گریز کرتا ہے اور git branch --show-current کو call کرتا ہے، جو .git/HEAD پڑھ کر فوراً واپس آ جاتا ہے۔

اگر آپ کوئی زیادہ بھاری عمل شامل کریں تو اسے file میں cache کریں اور ہر چند seconds بعد refresh کریں۔ file کی شناخت session کی بنیاد پر کریں:

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

session_id استعمال کریں، $$ نہیں۔ $$ آپ کے اسکرپٹ کا process ID ہے، جو ہر invocation میں مختلف ہوتا ہے۔ اس لیے اس پر مبنی cache کبھی hit نہیں ہوتا اور ہر بار مکمل cost ادا کرنی پڑتی ہے۔ session_id پورے session میں مستحکم رہتا ہے اور sessions کے درمیان مختلف ہوتا ہے۔ اس لیے مختلف repositories میں چلنے والے دو Claude Code sessions ایک دوسرے کے cached branch name کو نہیں پڑھ سکتے۔

ایک اور حد بھی ذہن میں رکھیں: tput cols statusline script کے اندر کام نہیں کرتا۔ Claude Code output capture کرتا ہے، اس لیے آپ کے اسکرپٹ کو terminal کے ساتھ attach نہیں کرتا۔ چنانچہ width detection کے لیے ناپنے کو کچھ نہیں ہوتا۔ Claude Code command چلانے سے پہلے، v2.1.153 اور بعد کے versions میں، COLUMNS اور LINES environment variables set کرتا ہے۔ جب آپ کو یہ طے کرنا ہو کہ کتنا output دکھانا ہے تو $COLUMNS پڑھیں۔

اسٹیٹس لائن خالی کیوں رہتی ہے

بالکل کچھ بھی ظاہر نہیں ہوتا۔ ls -l ~/.claude/statusline.sh سے execute بٹ کی جانچ کریں، پھر اوپر دیے گئے mock input کے ساتھ اسکرپٹ کو دستی طور پر چلائیں۔ اگر shell میں ایک لائن ظاہر ہوتی ہے لیکن Claude Code میں نہیں، تو claude --debug سے شروع کریں۔ یہ session میں statusline کے پہلے run کا exit code اور stderr لاگ کرتا ہے۔

ڈیبگ لاگ میں Status line command skipped: workspace trust not accepted لکھا ہے۔ statusline ایک shell command چلاتی ہے، اس لیے یہ hooks کے same workspace trust gate کے تحت آتی ہے۔ جب تک آپ اس directory کے لیے trust dialog قبول نہیں کرتے، command نہیں چلتی۔ VPS پر یہ عام بات ہے، کیونکہ ہر نیا clone ایسی directory ہوتا ہے جسے Claude Code نے پہلے نہیں دیکھا۔ Claude Code کو اسی directory میں restart کریں اور dialog قبول کریں۔

سب کچھ خالی ہے اور disableAllHooks set ہے۔ settings.json میں "disableAllHooks": true بھی statusline کو disable کرتا ہے، کیونکہ یہ بھی وہی shell-execution gate استعمال کرتا ہے۔ اسے ہٹا دیں یا false پر set کریں۔

row میں null ظاہر ہوتا ہے۔ jq selector ایسی key تک پہنچا جو موجود نہیں یا null ہے، اور jq -r null کو null کے چار characters کے طور پر print کرتا ہے۔ متن کے لیے // empty اور numbers کے لیے // 0 شامل کریں۔

اسکرپٹ edit کرنے کے فوراً بعد row خالی ہو جاتی ہے۔ جو command non-zero exit کرے یا کچھ بھی print نہ کرے، وہ row کو خالی کر دیتی ہے۔ عام وجہ آخری line جیسی [ -n "$BRANCH" ] && LINE="..." ہوتی ہے، جو branch خالی ہونے پر 1 exit کرتی ہے اور پورے script کا exit code بھی یہی بن جاتا ہے۔ printf کو آخری رکھیں، یا exit 0 شامل کریں۔

Escape codes bar پر literal text کے طور پر دکھائی دیتے ہیں، مثلاً \e]8;;۔ echo -e کے بجائے printf '%b' استعمال کریں۔ Clickable OSC 8 links کے لیے بھی ایسا terminal درکار ہے جو انہیں support کرتا ہو۔ tmux یا SSH یہ sequences strip کر سکتے ہیں، اس لیے remote box پر plain colour زیادہ محفوظ انتخاب ہے۔

row کا دائیں حصہ کٹ جاتا ہے۔ System notifications اور verbose-mode token counter اسی row میں دائیں جانب سے جگہ استعمال کرتے ہیں، اور narrow terminal میں یہ ایک دوسرے سے overlap ہو جاتے ہیں۔ Output مختصر رکھیں۔ Usage کی حقیقی accounting کے لیے، نہ کہ bar پر موجود ایک number کے لیے، Claude Code tokens کیسے شمار کرتا ہے دیکھیں۔

FAQ

Claude Code statusline کی setting کہاں موجود ہوتی ہے؟

یہ settings.json میں ایک statusLine block کے طور پر موجود ہوتی ہے، جس میں type کو "command" پر set کیا جاتا ہے اور command کو script path یا shell command پر set کیا جاتا ہے۔ User settings ~/.claude/settings.json میں ہوتی ہیں اور اس machine کے ہر project پر لاگو ہوتی ہیں۔ Project settings repository کے اندر .claude/settings.json میں ہوتی ہیں اور اس directory کے لیے ترجیح رکھتی ہیں۔ Settings خود reload ہو جاتی ہیں، لیکن تبدیلی اگلے update trigger پر ہی نظر آتی ہے، مثلاً آپ کے اگلے message پر۔

میری Claude Code statusline خالی کیوں ہے؟

تقریباً تمام صورتوں کی وجہ چار میں سے ایک ہوتی ہے۔ Script میں execute bit موجود نہیں، اس لیے shell Permission denied واپس کرتا ہے اور stdout پر کچھ نہیں پہنچتا۔ Workspace trust dialog کبھی accept نہیں کیا گیا، اور claude --debug Status line command skipped: workspace trust not accepted log کرتا ہے۔ disableAllHooks، true ہے، جس کی وجہ سے اسی gate کے تحت statusline غیر فعال ہو جاتی ہے۔ یا script non-zero کے ساتھ exit کرتی ہے، جس سے row خالی ہو جاتی ہے۔ پہلے اسے دستی طور پر test کریں: echo '{}' | ~/.claude/statusline.sh کو کچھ output کرنا ضروری ہے۔

کیا statusline JSON میں git branch شامل ہوتی ہے؟

نہیں۔ JSON میں session state شامل ہوتی ہے، جیسے model، workspace directories، context window numbers اور cost۔ اس میں git کے بارے میں کوئی معلومات نہیں ہوتی۔ آپ کی bar میں branch آپ کی اپنی script کے git branch --show-current چلانے سے آتی ہے۔ JSON سے directory git -C "$DIR" کے ذریعے pass کریں، تاکہ branch ہمیشہ اسی directory سے مطابقت رکھے جو bar دکھا رہی ہے۔

کیا statusline tokens استعمال کرتی ہے یا session کو سست کرتی ہے؟

یہ کوئی tokens استعمال نہیں کرتی، کیونکہ script مقامی طور پر چلتی ہے اور اس کا output model کو کبھی نہیں بھیجا جاتا۔ رفتار برقرار رکھنا آپ کی ذمہ داری ہے۔ Command ہر assistant message پر 300 ms debounce کے ساتھ چلتی ہے، اور نیا update آنے پر Claude Code جاری run کو cancel کر دیتا ہے؛ اس لیے اگر script کو پورا 1 second لگے تو پرانا text دکھائی دیتا ہے۔ بڑی repositories میں git status سے گریز کریں، اور ہر سست عمل کو session_id پر مبنی file میں cache کریں۔

ہر server پر مختلف statusline کیسے دکھاؤں؟

ایک ہی script رکھیں اور اسے machine کی معلومات پڑھنے دیں۔ اوپر والی script $HOSTNAME کو hostname -s کے fallback کے ساتھ print کرتی ہے، اس لیے ہر box پر copy کی گئی یہی file ہر server کو درست label کرتی ہے، جبکہ checksum colour trick ہر hostname کو اپنا الگ colour دیتی ہے۔ اگر کسی server پر مختلف layout درکار ہو تو اس server پر استعمال کی جانے والی repository کی project settings میں statusLine block رکھیں، کیونکہ اس directory کے لیے project settings user settings پر ترجیح رکھتی ہیں۔