---
title: "ts-band"
url: "https://claudemods.dev/ko/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: "도구 및 연동"
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: "ko"
content_locale: "ko"
---

# ts-band

ts-band: 프롬프트 위의 막대에 Tailscale 노드 상태를 표시하고 노드가 연결되거나 끊길 때 알림을 보여 줍니다

## Description

# ts-band: Claude Code에서 Tailscale 노드 상태 보기

**한국어** · [English](README.en.md)

입력창 위에 Tailscale 네트워크의 각 노드 연결 상태를 표시합니다. 모두 직접 연결되어 있으면 작은 표시 하나만 보이고, 중계 경로를 사용하거나 오프라인인 노드가 있을 때만 목록을 펼칩니다. Claude가 원격 시스템에 배포하거나 파일을 동기화하기 전에 경로가 정상인지 확인할 수 있습니다.

![ts-band: 두 노드는 중계를 사용하고 한 노드는 오프라인](assets/preview.png)

## 기능

- **평소에는 거의 공간을 차지하지 않음**: 모든 노드가 온라인이고 직접 연결이면 `TS ● 4/4 직접 연결`만 표시합니다.
- **문제가 있을 때만 펼침**: 온라인 노드 수를 표시하고 주의가 필요한 노드만 나열합니다. `◐` 노란색은 중계 또는 DERP를 뜻하며(예: `DERP-sfo`처럼 DERP 영역 표시), `○` 빨간색은 오프라인입니다.
- **연결 / 해제 알림**: 노드가 온라인 또는 오프라인이 되면 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` | UI 언어: `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`: hook(세션 시작 시 언어, `/ts`와 주기적 읽기, 명령, 막대).
- `hooks/config.ts`: 옵션을 타입이 지정된 `Config`로 한 번 읽습니다.
- `hooks/parse.ts`: `tailscale status --json`을 노드로 파싱하고 `nodes` 옵션을 필터 규칙으로 파싱합니다.
- `hooks/i18n.ts`: 언어별 문구.
- `hooks/kit/`: `claude-code/kit`의 복사본이며 소스 파일을 바꾼 뒤 `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`。
