box-status · Claude Code mod

Preview · a replayed session in a sandbox

claude · ~/work/app · box-status

› fix the failing auth test and add an audit log call ⏺ Read(src/auth.ts) ⎿ Read 6 lines ⏺ Update(src/auth.ts) ⎿ Added 2 lines, removed 1 line ⏺ Bash(bun test) ⎿ 3 pass, 1 fail ● Done. refresh now rejects expired claims and logs an audit event. ✻ Worked for 42s · done 4:20 PM ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts ⚠ box-status: dev · ping:none · sudo:yes

README

claude-mods

Five small Claude Code mods (function-hook plugins). They run in the terminal CLI (no GUI panes), and they are written to work the same on every machine: Linux or macOS, any username, any home directory. Nothing personal is baked into the source. Per-machine values (a Telegram chat id, an email address) come from the environment, so the same checkout is safe to push publicly and hand to other people.

The mods

Mod	What it does	How it shows
`dot-guard`	Blocks a `git add` that would stage your whole `$HOME` work-tree (`dot add -A`, `dot add .`, `dot add *`). One fat-finger away from committing your entire home directory.	Denies the tool call with a reason.
`emdash-watch`	Flags em-dashes the model writes into public-facing prose (`.md`, `.html`, `.css`, `.txt`, `.rst`). Internal files (`CLAUDE.md`, anything under `memory/` or `.claude/`) are exempt.	Non-blocking note appended to the write's result, visible to the model only.
`home-path-guard`	Flags a hardcoded user home (`/home/<user>`, `/Users/<user>`) written into a file, nudging `$HOME` / `~`. Machine-local files (`.local.`) are exempt.	Non-blocking note to the model.
`box-status`	Status line showing which box you are on, which out-of-band channel it can reach you on (`telegram` / `email` / `none`), and whether passwordless `sudo` works.	One status-line entry under the prompt.
`idle-ping`	When a turn that did real work ends, pings you out of band so you can step away. Telegram when a bot token and chat id are present, otherwise email.	Sends a message; logs to the debug sink when no channel is configured.

Install (per machine)

Clone this repo to the same relative path on each box, for example:

git clone <your-remote> ~/apps/claude-mods

Then point Claude Code at the five folders. The cleanest cross-machine way is CLAUDE_CODE_PLUGIN_DIRS in the env block of ~/.claude/settings.json (which uses ~, so the one line works on every machine):

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "~/apps/claude-mods/dot-guard:~/apps/claude-mods/emdash-watch:~/apps/claude-mods/box-status:~/apps/claude-mods/home-path-guard:~/apps/claude-mods/idle-ping"
  }
}

(On Windows the list separator is ; instead of :.)

Or load them for a single session without touching settings:

claude --plugin-dir ~/apps/claude-mods/dot-guard --plugin-dir ~/apps/claude-mods/idle-ping

Per-machine configuration (idle-ping)

idle-ping reads its target from the environment, never from source:

Telegram (preferred when set): it reads TELEGRAM_BOT_TOKEN (and optionally TELEGRAM_CHAT_ID) from ~/.claude/channels/telegram/.env, and TELEGRAM_CHAT_ID from the process environment if not in that file. Keep that file out of version control (mode 600).
Email (fallback): set CLAUDE_PING_EMAIL to the recipient. The mod sends through the first mailer it finds on PATH (msmtp, sendmail, mail, mailx).
If neither is configured, it writes what it would have sent to the debug log and does nothing else.

box-status reports the same channel resolution, so a glance at the status line tells you whether a ping would actually go out on this box.

Settings knobs

dot-guard.wrappers (default dot): comma-separated command names that run git with --work-tree=$HOME. Set it to your own dotfiles alias if it is not dot.
idle-ping.minTools (default 2): how many tool calls a turn needs before it counts as real work worth a ping. Raise it to ping less often.

Developing

Each mod is a folder with .claude-plugin/plugin.json, hooks/hooks.json, and hooks/register.ts. Check and test one with:

claude plugin validate <mod>
claude plugin test <mod>

Source 1 files

hooks/register.ts 40 lines

1import type { Register } from 'claude-code'
2
3async function shortHost($: any): Promise<string> {
4  for (const argv of [['hostname', '-s'], ['hostname']]) {
5    const r = await $.process.run(argv, { timeoutMs: 4000 }).catch(() => undefined)
6    const out = r?.stdout?.trim()
7    if (out) return out.split('.')[0]
8  }
9  return (await $.env.get('HOSTNAME')) || (await $.env.get('HOST')) || 'host'
10}
11
12// Which out-of-band channel this box can reach the user on. Mirrors idle-ping.
13async function channel($: any): Promise<string> {
14  const home = (await $.env.get('HOME')) ?? ''
15  const tgEnv = `${home}/.claude/channels/telegram/.env`
16  if (home && (await $.fs.exists(tgEnv).catch(() => false))) {
17    const txt = await $.fs.read(tgEnv).catch(() => '')
18    if (/(^|\n)\s*(?:export\s+)?TELEGRAM_BOT_TOKEN\s*=/.test(txt)) return 'telegram'
19  }
20  if (await $.env.get('CLAUDE_PING_EMAIL')) return 'email'
21  return 'none'
22}
23
24async function sudo($: any): Promise<string> {
25  const r = await $.process.run(['sudo', '-n', 'true'], { timeoutMs: 4000 }).catch(() => undefined)
26  return r?.exitCode === 0 ? 'yes' : 'no'
27}
28
29export const register: Register = on => {
30  on('session.start', async ($, e, next) => {
31    const started = await next(e)
32    // ponytail: detach so start isn't delayed by the probes; status needs no turn.
33    void (async () => {
34      const [h, c, s] = await Promise.all([shortHost($), channel($), sudo($)])
35      $.ui.status(`${h} · ping:${c} · sudo:${s}`)
36    })()
37    return started
38  })
39}
40