---
title: "ts-band: View Tailscale Node Status in Claude Code"
url: "https://claudemods.dev/en/builds/ts-band-a5dba3"
source: "https://github.com/hoobnn/hoobnn-agent-mods/tree/main/claude-code/ts-band"
source_type: "github"
repo: "https://github.com/hoobnn/hoobnn-agent-mods/tree/main/claude-code/ts-band"
author: "hoobnn"
author_handle: "hoobnn"
stars: 8
category: "Tools & integrations"
categories: ["tools"]
tags: ["Claude Code", "mod"]
permission_level: 2
scan_complete: false
install: "claude plugin marketplace add hoobnn/hoobnn-agent-mods\nclaude plugin install ts-band@hoobnn-agent-mods"
added: "2026-10-04T10:40:36.873Z"
updated: "2026-11-09T14:28:07Z"
locale: "en"
content_locale: "en"
---

# ts-band: View Tailscale Node Status in Claude Code

ts-band: Tailscale node status in a band above the prompt, with a toast when a node comes online or goes offline

## Description

# ts-band: View Tailscale Node Status in Claude Code

**Simplified Chinese** · [English](README.en.md)

Show the connection status of each node in your Tailscale network above the input box. When all nodes are direct, it takes up only a small marker; it lists nodes only when some are relayed or offline. Before Claude deploys to or syncs files with a remote machine, take a quick look at whether the link is healthy.

![ts-band: two nodes relayed, one node offline](assets/preview.png)

## Features

- **Barely takes up space when everything is normal**: when all nodes are online and direct, it shows only `TS ● 4/4 direct`.
- **Expands only when there are anomalies**: shows the number of online nodes, then lists only the nodes that need attention: `◐` yellow means relayed or DERP (the DERP region is shown, e.g. `DERP-sfo`), `○` red means offline.
- **Online/offline notifications**: shows a toast when a node comes online or goes offline.
- **Refreshes promptly**: reads `tailscale status --json` once a minute; after Claude runs `tailscale up`, `down`, `set`, `switch`, `login`, or `logout`, it refreshes immediately.
- **Doesn't clear on read failure**: if a read fails, it keeps the previous nodes and appends the error message; subsequent retry intervals double each time (up to 10 minutes), so it won't retry every time when the CLI isn't installed or the daemon isn't running.
- Doesn't run in `claude -p` or the SDK.

## Installation

First install [Tailscale](https://tailscale.com/download) and make sure the `tailscale` command is available (the CLI bundled with the macOS app is also found), then:

```sh
claude plugin marketplace add hoobnn/hoobnn-agent-mods
claude plugin install ts-band@hoobnn-agent-mods
```

## Commands

- `/ts`: toggle show/hide; `/ts off` and `/ts on` set it directly. This setting is written back to `/config` and persists in later sessions.

## Options

Modify them in `/config`, or write them in `pluginConfigs` in `~/.claude/settings.json`:

| Option | Effect | Default |
| --- | --- | --- |
| `visible` | Show the bar (this is what `/ts` changes) | On |
| `nodes` | Show only these nodes, in the order entered; `host=name` can change the display name, e.g. `nas=home, dev-box, vps-west=US West`. Leave empty to show all; the online count and notifications are also calculated only from the selected nodes | Empty |
| `hideOffline` | Don't list offline nodes in the bar (they still count toward the online count) | Off |
| `tailscalePath` | Path to the `tailscale` command; when empty, it searches PATH, Homebrew, and the macOS app in order | Empty |
| `intervalSeconds` | Seconds between reads (at least 10) | 60 |
| `language` | UI language: `auto`, `en`, `zh-Hans`, `zh-Hant`, `ja`, `ko`, `es`, `fr`, `de`, `pt-BR`, `ru` | `auto` |

When `language` is `auto`, it follows Claude Code's `language` setting and then the system locale, in that order, and uses English if neither is available.

## Same-series mods

[hoobnn-agent-mods](../../README.md) also includes a status bar HUD (`hud`), a task progress bar (`todo-bar`), a turn receipt (`receipt`), a running animation and pet (`spinner`), and hitokoto (`hitokoto`), which can be used together.

## Development

- `hooks/register.tsx`: hooks (language at session start, `/ts` and periodic reads, commands, and the bar).
- `hooks/config.ts`: options, read once into a typed `Config`.
- `hooks/parse.ts`: parses `tailscale status --json` into nodes and the `nodes` option into filter rules.
- `hooks/i18n.ts`: text for each language.
- `hooks/kit/`: a copy of `claude-code/kit`; after changing the source files, run `scripts/sync-kit.sh`.

## Install

```
claude plugin marketplace add hoobnn/hoobnn-agent-mods
claude plugin install ts-band@hoobnn-agent-mods
```

## Original README

# ts-band：在 Claude Code 里看 Tailscale 节点状态

**简体中文** · [English](README.en.md)

在输入框上方显示 Tailscale 组网里各节点的连接状态。全部直连时只占一个小标记；有节点走中继或掉线时才把它们列出来。让 Claude 往远程机器部署、同步文件之前，先看一眼链路是否正常。

![ts-band：两个节点走中继，一个节点离线](assets/preview.png)

## 功能

- **正常时几乎不占地方**：所有节点在线且直连时，只显示 `TS ● 4/4 直连`。
- **有异常才展开**：显示在线节点数，然后只列出需要注意的节点：`◐` 黄色表示走中继或 DERP（会标出 DERP 区域，如 `DERP-sfo`），`○` 红色表示离线。
- **上线 / 掉线提醒**：节点上线或掉线时弹 toast。
- **及时刷新**：每分钟读一次 `tailscale status --json`；Claude 执行 `tailscale up`、`down`、`set`、`switch`、`login`、`logout` 后立即刷新。
- **读取失败不清空**：读取失败时保留上次的节点，后面附上错误信息；之后的重试间隔逐次翻倍（最长 10 分钟），没装 CLI 或守护进程没开时不会每次都重试。
- 在 `claude -p` 和 SDK 里不运行。

## 安装

先装好 [Tailscale](https://tailscale.com/download)，确保 `tailscale` 命令可用（macOS 应用自带的 CLI 也能找到），然后：

```sh
claude plugin marketplace add hoobnn/hoobnn-agent-mods
claude plugin install ts-band@hoobnn-agent-mods
```

## 命令

- `/ts`：切换显示和隐藏；`/ts off`、`/ts on` 直接设定。这个设置会写回 `/config`，以后的会话也会沿用。

## 选项

在 `/config` 里修改，或写在 `~/.claude/settings.json` 的 `pluginConfigs` 里：

| 选项 | 作用 | 默认 |
| --- | --- | --- |
| `visible` | 显示横条（`/ts` 改的就是它） | 开 |
| `nodes` | 只显示这些节点，按填写顺序排列；`host=名字` 可以改显示名，如 `nas=家里, dev-box, vps-west=美西`。留空显示全部，在线数和提醒也只按选中的节点算 | 空 |
| `hideOffline` | 横条里不列离线节点（在线数仍然计入） | 关 |
| `tailscalePath` | `tailscale` 命令的路径；留空时依次在 PATH、Homebrew 和 macOS 应用里找 | 空 |
| `intervalSeconds` | 两次读取之间的秒数（至少 10） | 60 |
| `language` | 界面语言：`auto`、`en`、`zh-Hans`、`zh-Hant`、`ja`、`ko`、`es`、`fr`、`de`、`pt-BR`、`ru` | `auto` |

`language` 为 `auto` 时，依次跟随 Claude Code 的 `language` 设置和系统语言环境，都没有时用英语。

## 同系列 mod

[hoobnn-agent-mods](../../README.md) 里还有状态栏 HUD（`hud`）、任务进度条（`todo-bar`）、回合回执（`receipt`）、运行动画和宠物（`spinner`）和一言（`hitokoto`），可以搭配使用。

## 开发

- `hooks/register.tsx`：钩子（会话开始时的语言、`/ts` 和定时读取，命令和横条）。
- `hooks/config.ts`：选项，一次性读成类型化的 `Config`。
- `hooks/parse.ts`：把 `tailscale status --json` 解析成节点，把 `nodes` 选项解析成筛选规则。
- `hooks/i18n.ts`：各语言文案。
- `hooks/kit/`：`claude-code/kit` 的副本；改源文件后运行 `scripts/sync-kit.sh`。
