The field guide
A small compass for a terminal full of agents. agent-terminal-status turns fleeting runtime context into a persistent spatial promise: before the next command lands, you can see where it will land. It is not a dashboard. It is the terminal equivalent of putting a tiny, honest “You are here” dot on the map. 01 · The line’s journey
Five careful moves, then quiet. Every refresh starts from Claude Code’s JSON and ends as one measured line. Nothing is cached, phoned home, or guessed from the shell prompt. 01
Observe workspace.current_dir
Read the actual working directory The adapter prefers Claude Code’s current directory, then uses safe local fallbacks if the payload is incomplete.
02
Locate git -C <cwd>
Ask Git about that exact place Bounded, read-only calls find the worktree root and branch with optional locks disabled. Each Git subprocess has a default 150 ms deadline.
03
Name repo/path · branch · host
Build an honest identity With the default ATS_PATH_STYLE=context, paths inside Git are repository-relative and keep the real nested directory. Outside Git, they become home-relative or absolute.
04
Defuse Cc · Cf · Cs · Zl · Zp
Remove invisible stage tricks Control, format, surrogate, and line-separator characters become spaces, so bidi overrides cannot counterfeit direction or create a second row. Ordinary CJK and emoji variation selectors stay.
05
Fit display width ≤ COLUMNS
Render for terminal cells CJK-wide characters count as two cells. The path shortens in the middle; in the default auto modes, branch and host leave before location does.
02 · The design contract
Three rules keep the line useful. 01 The path is the invariant. If Git disappears, the branch times out, or hostname lookup fails, the renderer still returns a useful location—never a blank row.
02 Optional signals must earn their space. Branch and machine help when terminals look alike. Under pressure, they yield to the directory that determines where commands act.
03 Uncertainty is rendered honestly. The project would rather omit a branch or warn that rollback history is unknown than manufacture a confident but stale answer.
03 · The width theatre
Same place. Smaller stage. The renderer measures terminal cells, not raw string length. These are real outputs from the same identity at three widths. renderer / same identity terminal cells
96 Full context
agent-terminal-status/docs/research · feature/identity · snowy-atlasPath, branch, and machine all fit.
44 Keep orientation
agent-terminal…s/docs/research · snowy-atlasBranch leaves; the nested path and machine remain.
24 Protect the invariant
agent-termi…ocs/researchOnly a middle-shortened path survives.
↳ The ellipsis is in the middle on purpose: both the repository beginning and the current-directory ending carry identity.
04 · A reversible guest
Installation borrows one setting. It does not claim the house. The installer treats your existing Claude Code status line as user data, not an obstacle to overwrite. 01 Inspect Parse settings before changing anything. Invalid JSON or an ambiguous existing status line stops the install cleanly.
02 Preserve With explicit force, save the exact previous statusLine value as rollback state. Reinstall keeps that original history while the metadata remains valid.
03 Write atomically Copy only known project files and replace settings through a safe temporary write, reducing the chance of a half-written configuration.
04 Return carefully Uninstall restores the old value only while the active command is still ours. A newer user choice is left untouched.
↘ No network calls Rendering does not contact GitHub, a telemetry endpoint, a package registry, or this website.
○ No analytics or account The site has no account backend, application database, or tracking SDK. Its Worker only renders and serves public pages and assets.
⌁ No decorative dependency stack Windows uses PowerShell 5.1 already on the machine; macOS and Linux use Python 3.9+ and the standard library.
hostname.local → public-alias
Screenshots deserve a public name. A hostname can reveal an internal naming convention. Set ATS_MACHINE to a friendly alias, or ATS_SHOW_HOST=never when sharing a screen.
ATS_MACHINE=public-aliasATS_SHOW_HOST=never06 · Try the compass
Clone, install, interact once. The installer updates your user-level Claude Code settings. Claude reloads them automatically; the next interaction refreshes the line. Windows PowerShell 5.1+
PowerShell 5.1+ · no Python, Node.js, jq, icon font, or prompt framework required.
$ git clone https://github.com/snowyukitty/agent-terminal-status.git; cd agent-terminal-status; powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1Copy
macOS / Linux Python 3.9+
Python 3.9+ · standard library only.
$ git clone https://github.com/snowyukitty/agent-terminal-status.git && cd agent-terminal-status && sh scripts/install.shCopy
Already have a status line? Installation stops without changing it. Read the force and uninstall rules before choosing to replace it.
01 It does not report dirty state, ahead/behind, model, context usage, or agent ownership.
02 Without COLUMNS it uses a 96-cell cap; terminal resize takes effect on the next Claude event rather than forcing a refresh.
03 It does not promise branch data when local Git exceeds its deadline.
04 By default, machine identity is the hostname visible inside that environment—not magical SSH, WSL, or container topology detection.
05 Removing ZWJ and ZWNJ can change the shaping of a complex emoji or connected script; the one-line safety invariant wins.
06 It cannot make Claude Code show the line during UI states where Claude temporarily hides custom status output.
The next command should never be a location quiz.
Keep one quiet line in view, let the path tell the truth, and spend your attention on the work instead. Guía de campo
Una pequeña brújula para un terminal lleno de agentes. agent-terminal-status convierte el contexto fugaz de cada ejecución en una promesa espacial persistente: antes de que llegue el siguiente comando, puedes ver dónde va a actuar. No es un panel de control. Es el equivalente, dentro del terminal, a colocar un pequeño y sincero «Estás aquí» sobre el mapa. 01
Observar workspace.current_dir
Leer el directorio de trabajo real El adaptador da prioridad al directorio actual que entrega Claude Code y recurre a alternativas locales seguras cuando los datos de entrada están incompletos.
02
Ubicar git -C <cwd>
Preguntar a Git por ese lugar exacto Llamadas acotadas y de solo lectura localizan la raíz del worktree y la rama, con los bloqueos opcionales desactivados. Cada subproceso de Git tiene un tiempo de espera predeterminado de 150 ms.
03
Nombrar repo/path · branch · host
Construir una identidad honesta Con el valor predeterminado ATS_PATH_STYLE=context, las rutas dentro de Git son relativas al repositorio y conservan el directorio anidado real. Fuera de Git se muestran relativas al directorio personal o como rutas absolutas.
04
Neutralizar Cc · Cf · Cs · Zl · Zp
Quitar los trucos invisibles del escenario Los caracteres de control, formato, sustitutos (surrogates) y separadores de línea se convierten en espacios, de modo que un control de anulación bidi no pueda falsificar la dirección ni crear una segunda línea. Los caracteres CJK normales y los selectores de variación de emoji se conservan.
05
Encajar display width ≤ COLUMNS
Renderizar según las celdas del terminal Los caracteres CJK anchos cuentan como dos celdas. La ruta se acorta por el centro; con la configuración automática predeterminada, la rama y la identidad de la máquina ceden su sitio antes que la ubicación.
01 La ruta es el invariante. Si Git no está disponible, una consulta a Git agota su tiempo de espera o falla la consulta del nombre del equipo, el renderizador sigue devolviendo una ubicación útil: nunca una línea en blanco.
02 Las señales opcionales deben merecer su espacio. La rama y la identidad de la máquina ayudan a distinguir terminales parecidos. Cuando falta espacio, ceden ante el directorio que determina dónde actúan los comandos.
03 La incertidumbre se muestra con honestidad. El proyecto prefiere omitir una rama o advertir que se desconoce el historial de reversión antes que inventar una respuesta categórica pero obsoleta.
03 · El teatro del ancho
Mismo lugar. Escenario más pequeño. El renderizador mide celdas del terminal, no la longitud bruta de la cadena. Estas son salidas reales de una misma identidad con tres anchos distintos. renderer / same identity terminal cells
96 Contexto completo
agent-terminal-status/docs/research · feature/identity · snowy-atlasHay espacio para la ruta, la rama y la identidad de la máquina.
44 Conservar la orientación
agent-terminal…s/docs/research · snowy-atlasLa rama se retira; la ruta anidada y la identidad de la máquina permanecen.
24 Proteger el invariante
agent-termi…ocs/researchSolo sobrevive la ruta acortada por el centro.
↳ Los puntos suspensivos están en el centro a propósito: tanto el inicio, que identifica el repositorio, como el final, que identifica el directorio actual, aportan identidad.
01 Inspeccionar Analiza la configuración antes de cambiar nada. Un JSON inválido o una línea de estado existente de procedencia ambigua detienen la instalación sin modificar nada.
02 Conservar Solo al usar de forma explícita la opción de forzado (-Force en Windows o --force en macOS y Linux) se guarda como estado de reversión el valor anterior exacto de statusLine. Una reinstalación conserva ese historial original mientras los metadatos sigan siendo válidos.
03 Escribir de forma atómica Copia únicamente los archivos conocidos del proyecto y sustituye la configuración mediante una escritura temporal segura, lo que reduce el riesgo de dejarla incompleta.
04 Restaurar con cuidado El desinstalador restaura el valor anterior solo si el comando activo sigue siendo el nuestro. Una elección posterior del usuario queda intacta.
↘ Sin llamadas de red El renderizado no contacta con GitHub, servicios de telemetría, registros de paquetes ni este sitio web.
○ Sin analítica ni cuentas El sitio no tiene backend de cuentas, base de datos de la aplicación ni SDK de seguimiento. Su Worker se limita a renderizar y servir páginas y recursos públicos.
⌁ Sin una pila decorativa de dependencias Windows usa el PowerShell 5.1 que ya está en el sistema; macOS y Linux usan Python 3.9+ y la biblioteca estándar.
hostname.local → public-alias
Las capturas merecen un nombre que se pueda compartir. Un nombre de host puede revelar convenciones internas de nombres. Define ATS_MACHINE con un alias reconocible o usa ATS_SHOW_HOST=never al compartir la pantalla.
ATS_MACHINE=public-aliasATS_SHOW_HOST=never06 · Prueba la brújula
Clona, instala e interactúa una vez. El instalador actualiza la configuración de Claude Code a nivel de usuario. Claude la vuelve a cargar automáticamente; la siguiente interacción actualiza la línea. Windows PowerShell 5.1+
PowerShell 5.1+ · no requiere Python, Node.js, jq, fuentes de iconos ni un framework para personalizar el prompt.
$ git clone https://github.com/snowyukitty/agent-terminal-status.git; cd agent-terminal-status; powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1Copiar
macOS / Linux Python 3.9+
Python 3.9+ · solo la biblioteca estándar.
$ git clone https://github.com/snowyukitty/agent-terminal-status.git && cd agent-terminal-status && sh scripts/install.shCopiar
¿Ya tienes una línea de estado? La instalación se detiene sin cambiarla. Lee las reglas de instalación forzada y desinstalación antes de decidir sustituirla.
01 No muestra cambios pendientes (dirty), divergencia ahead/behind, el modelo, el uso del contexto ni qué agente está a cargo.
02 Sin COLUMNS aplica un límite de 96 celdas; un cambio de tamaño del terminal se refleja en el siguiente evento de Claude en lugar de forzar una actualización.
03 No promete información de la rama cuando una consulta a Git local agota su tiempo de espera.
04 De forma predeterminada, la identidad de la máquina es el nombre de host visible dentro de ese entorno, no una detección mágica de la topología de SSH, WSL o contenedores.
05 Eliminar ZWJ y ZWNJ puede alterar la forma de un emoji complejo o de un sistema de escritura con caracteres enlazados; prevalece el invariante de seguridad de una sola línea.
06 No puede obligar a Claude Code a mostrar la línea en los estados de la interfaz donde Claude oculta temporalmente la línea de estado personalizada.
El siguiente comando nunca debería ser un acertijo sobre tu ubicación.
Mantén una línea serena a la vista, deja que la ruta diga la verdad y reserva tu atención para el trabajo. フィールドガイド
エージェントが行き交うターミナルに、小さな羅針盤を。 agent-terminal-status は、その場限りの実行コンテキストを、いつでも見える「現在地」に変えます。次のコマンドを打つ前に、それがどこへ届くのかが分かります。 これはダッシュボードではありません。地図の隅に、正直な「現在地」をひとつ置くための道具です。 01 · 一行ができるまで
五つの慎重な動作。そのあとは静かに。 更新のたびに Claude Code の JSON から始まり、幅を測った一行で終わります。キャッシュも外部通信も、シェルプロンプトからの推測もありません。 01
観測 workspace.current_dir
本当に使われている作業ディレクトリを読む まず Claude Code が渡す現在のディレクトリを使い、入力が欠けているときだけ安全なローカル情報へフォールバックします。
02
照合 git -C <cwd>
その場所について Git にだけ尋ねる GIT_OPTIONAL_LOCKS=0 として、実行時間を制限した読み取り専用の Git 呼び出しで worktree のルートと branch を調べます。各 subprocess は既定で 150 ms を超えると打ち切ります。
03
命名 repo/path · branch · host
正直な現在地を組み立てる 既定の ATS_PATH_STYLE=context では、Git 内の path をリポジトリ相対で表示し、実際の深い作業場所まで残します。Git 外ではホーム相対、できなければ絶対 path です。
04
無害化 Cc · Cf · Cs · Zl · Zp
見えない舞台装置を外す 制御・書式・サロゲート・改行区切り文字を空白に置き換え、bidi override に向きや行数を偽装させません。通常の CJK と emoji variation selector は残します。
05
整形 display width ≤ COLUMNS
文字数ではなく、ターミナルのセル幅に収める 全角 CJK は 2 cell と数えます。path は中央で短縮し、既定の auto モードでは branch と host が現在地より先に退場します。
02 · 設計の約束
役に立つ一行を守る、三つの原則。 01 path は最後まで残す。 Git がなくても、branch が timeout しても、hostname の取得に失敗しても、場所だけは返します。空行にはしません。
02 補助情報は、幅に見合うときだけ。 branch と machine は似たターミナルを見分ける助けになります。ただし狭くなれば、コマンドの作用先を示す directory に席を譲ります。
03 分からないことを、分かったふりにしない。 古い情報を自信満々に出すくらいなら、branch を省き、rollback 履歴が不明ならそう警告します。
03 · 幅のシアター
場所は同じ。舞台だけが小さくなる。 測っているのは文字列の長さではなく terminal cell です。下は、同じ identity を三つの幅で実際に描画した結果です。 renderer / same identity terminal cells
96 すべて表示
agent-terminal-status/docs/research · feature/identity · snowy-atlaspath・branch・machine が全部入ります。
44 方向感覚を優先
agent-terminal…s/docs/research · snowy-atlasbranch が退き、深い path と machine が残ります。
24 不変条件を守る
agent-termi…ocs/research中央を縮めた path だけが残ります。
↳ 省略記号が中央にあるのは意図的です。リポジトリを示す先頭と、現在の directory を示す末尾の両方が大切だからです。
04 · 元に戻せる訪問者
設定をひとつ借りても、家ごと自分のものにはしない。 installer は既存の Claude Code status line を、上書きすべき障害ではなく大切な user data として扱います。 01 確認する 変更前に settings を parse します。不正な JSON や判断できない既存設定があれば、何も変えずに止まります。
02 保存する 明示的に force した場合だけ、以前の statusLine をそのまま rollback state に保存します。metadata が有効な間は、再 install でも最初の履歴を守ります。
03 atomic に書く 既知の project file だけをコピーし、安全な一時書き込みを経て settings を置き換えます。中途半端な設定を残しにくくします。
04 慎重に返す uninstall は active command がまだ本 project のものなら旧設定を復元します。その後の user の選択には触れません。
05 · 静かさは、プライバシーでもある。
ローカルの情報は、ローカルに。 描画経路が読むのは stdin、environment、filesystem 上の場所、そして local Git。それで会話は終わりです。 ↘ network call なし GitHub、telemetry endpoint、package registry、この website のどれにも描画中は接続しません。
○ analytics も account もなし サイトにはアカウント用バックエンド、アプリケーションデータベース、トラッキング SDK はありません。Worker は公開ページとアセットの描画・配信だけを担います。
⌁ 飾りのための dependency stack なし Windows は標準の PowerShell 5.1、macOS / Linux は Python 3.9+ と standard library だけを使います。
hostname.local → public-alias
画面共有には、公開してよい名前を。 hostname は社内の命名規則を漏らすことがあります。ATS_MACHINE に親しみやすい alias を設定するか、共有時は ATS_SHOW_HOST=never を使えます。
ATS_MACHINE=public-aliasATS_SHOW_HOST=never06 · 羅針盤を試す
クローンしてインストールし、一度操作するだけ。 installer は user-level の Claude Code settings を更新します。Claude が自動で読み直し、次の操作で一行が更新されます。 Windows PowerShell 5.1+
PowerShell 5.1+ · Python、Node.js、jq、icon font、prompt framework は不要です。
$ git clone https://github.com/snowyukitty/agent-terminal-status.git; cd agent-terminal-status; powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1コピー
macOS / Linux Python 3.9+
Python 3.9+ · standard library のみ。
$ git clone https://github.com/snowyukitty/agent-terminal-status.git && cd agent-terminal-status && sh scripts/install.shコピー
既存の status line があれば、何も変えずに停止します。置き換える前に force と uninstall の規則を確認してください。
07 · あえて、しないこと
羅針盤は、天気予報のふりをしない方がいい。 Version 0.1 は答えを速く、読みやすく、信頼できるままにするため、役割を絞っています。 01 dirty state、ahead/behind、model、context 使用量、agent ownership は表示しません。
02 COLUMNS がなければ 96 cell を上限にします。terminal resize は強制更新せず、次の Claude event で反映します。
03 local Git が期限を超えたとき、branch 情報があるふりをしません。
04 machine identity の既定値はその環境から見える hostname であり、SSH・WSL・container の構成を魔法のように判別するものではありません。
05 ZWJ / ZWNJ の除去で複雑な emoji や連結文字の形が変わることがあります。一行の安全性を優先するための取捨選択です。
06 Claude Code 自身が custom status を一時的に隠す UI state では、表示を強制できません。
次のコマンドを、現在地クイズにしない。
静かな一行を視界に置き、path に事実を語らせて、注意力は本来の作業に使いましょう。 實地指南
讓 AI agents 來來往往的終端機，也有一枚小小的指南針。 agent-terminal-status 把轉瞬即逝的執行脈絡，變成持續可見的空間承諾：下一個命令落下之前，你先知道它會落在哪裡。 它不是儀表板，而是終端機地圖上那個小而誠實的「你在這裡」。 01 · 一行文字的旅程
五個謹慎步驟，然後安靜下來。 每次更新都從 Claude Code 的 JSON 開始，以一行量好寬度的文字結束。不快取、不連外，也不從 shell prompt 猜測。 01
觀察 workspace.current_dir
讀取真正的工作目錄 adapter 優先採用 Claude Code 傳入的目前目錄；只有 payload 不完整時，才退回安全的本機資訊。
02
定位 git -C <cwd>
只向 Git 詢問這個確切位置 停用 optional locks，再以有界、唯讀的呼叫找出 worktree root 與 branch；每個 Git subprocess 的預設 deadline 是 150 ms。
03
命名 repo/path · branch · host
組合誠實的 identity 在預設的 ATS_PATH_STYLE=context 下，Git 內採 repository-relative path，保留真正的巢狀目錄；在 Git 外則顯示 home-relative 或 absolute path。
04
拆彈 Cc · Cf · Cs · Zl · Zp
移除看不見的舞台機關 控制、格式、surrogate 與行分隔字元會變成空格，讓 bidi override 無法偽造方向或偷偷長出第二行；一般 CJK 與 emoji variation selector 仍會保留。
05
入鏡 display width ≤ COLUMNS
用 terminal cell，而不是字串長度排版 全形 CJK 字元計為兩格。path 從中間縮短；在預設的 auto 模式下，空間不足時 branch 與 host 會先讓位給工作位置。
01 Path 是不可犧牲的不變式。 Git 消失、branch 逾時、hostname 解析失敗時，renderer 仍會留下有用的位置，永遠不交出空白行。
02 附加訊號必須值得它佔用的寬度。 branch 與 machine 能辨認相似的終端機；空間緊張時，它們必須讓位給真正決定命令作用範圍的 directory。
03 不知道，就明白說不知道。 與其自信地展示過期資訊，專案寧可省略 branch；rollback 歷史無法確認時，也只會誠實警告。
03 · 欄寬劇場
位置沒變，只是舞台縮小了。 renderer 計算的是 terminal cell，不是原始字串長度。以下是同一組 identity 在三種寬度下的真實輸出。 renderer / same identity terminal cells
96 完整脈絡
agent-terminal-status/docs/research · feature/identity · snowy-atlaspath、branch、machine 全部容得下。
44 方向感優先
agent-terminal…s/docs/research · snowy-atlasbranch 退場，巢狀 path 與 machine 留下。
24 守住不變式
agent-termi…ocs/research只保留從中間縮短的 path。
↳ 省略號刻意放在中間：開頭告訴你是哪個 repository，結尾告訴你目前在哪個 directory，兩端都值得保留。
04 · 一位可逆的房客
借用一項設定，不代表接管整棟房子。 installer 把你原有的 Claude Code status line 視為 user data，而不是等著被覆寫的障礙。 01 先檢查 變更前先 parse settings。JSON 無效或既有 status line 歸屬不明時，完全不修改就停止。
02 保留舊值 只有明確使用 force 時，才把舊 statusLine 原樣儲存為 rollback state；metadata 有效時，重新安裝也保留最初那份歷史。
03 原子寫入 只複製專案已知檔案，並透過安全的暫存寫入替換 settings，降低留下半份設定的風險。
04 小心歸還 uninstall 只在 active command 仍屬於本專案時復原舊值；使用者後來做的新選擇一律不碰。
05 · 安靜，也代表隱私
留在本機的訊號，就讓它留在本機。 render path 只讀 stdin、environment、filesystem 位置與 local Git。對話到此為止。 ↘ 沒有 network call rendering 不會聯絡 GitHub、telemetry endpoint、package registry，甚至不會聯絡這個網站。
○ 沒有 analytics，也沒有 account 網站沒有帳號後端、應用程式資料庫或 tracking SDK；Worker 只負責呈現並遞送公開頁面與資產。
⌁ 沒有只為裝飾而堆疊的相依套件 Windows 使用系統既有的 PowerShell 5.1；macOS / Linux 使用 Python 3.9+ 與 standard library。
hostname.local → public-alias
要截圖，就先取一個可以公開的名字。 hostname 可能透露內部命名規則。可將 ATS_MACHINE 設為友善 alias，或在分享畫面時使用 ATS_SHOW_HOST=never。
ATS_MACHINE=public-aliasATS_SHOW_HOST=never06 · 試試這枚指南針
Clone、安裝，互動一次。 installer 會更新使用者層級的 Claude Code settings。Claude 會自動重新載入；下一次互動就會更新這一行。 Windows PowerShell 5.1+
PowerShell 5.1+ · 不需要 Python、Node.js、jq、icon font 或 prompt framework。
$ git clone https://github.com/snowyukitty/agent-terminal-status.git; cd agent-terminal-status; powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1複製
macOS / Linux Python 3.9+
Python 3.9+ · 只使用 standard library。
$ git clone https://github.com/snowyukitty/agent-terminal-status.git && cd agent-terminal-status && sh scripts/install.sh複製
已經有 status line？安裝程式會原封不動地停下。決定取代之前，請先閱讀 force 與 uninstall 規則。
07 · 刻意不做的事
指南針不假裝自己是氣象站，反而更可靠。 Version 0.1 刻意維持精簡，讓答案繼續快速、清楚、可信。 01 不顯示 dirty state、ahead/behind、model、context 用量或 agent ownership。
02 缺少 COLUMNS 時採 96 個 terminal cell 上限；terminal resize 不強制更新，而是在下一個 Claude event 生效。
03 local Git 超過 deadline 時，不假裝擁有 branch 資訊。
04 machine identity 的預設值是該環境能看見的 hostname，不會神奇地判讀 SSH、WSL 或 container 拓樸。
05 移除 ZWJ / ZWNJ 可能改變複雜 emoji 或連寫文字的外觀；這是為了守住單行安全性所做的取捨。
06 Claude Code 在特定 UI 狀態暫時隱藏 custom status 時，本專案無法強迫它顯示。
別讓下一個命令，變成一場工作位置猜謎。
保留一行安靜的提示，讓 path 說實話，把注意力留給真正值得處理的工作。