Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// Claude subscription usage for a REMOTE (SSH project) account, read over that project's
// ControlMaster. v1 deliberately had none of this ("remote accounts are excluded"), so a user
// whose Claude runs on a server saw an empty pill while the host had perfectly good numbers.
//
// **The token never leaves the host.** The desktop could `cat` the remote `.credentials.json`
// and call the API itself — it already reads remote transcripts over the same master — but a
// bearer token pulled off a (possibly shared) server into another machine's memory is a bigger
// surface than any transcript read, and it buys nothing: the host can make the request itself.
// So the remote shell reads its own credential file and curls the endpoint; we only ever see
// the JSON answer. Two consequences the command below is built around:
// - the token must not appear in the remote **argv** (`ps` is readable by other users on a
// shared host), which is why it is piped into `curl --config -` instead of `-H`;
// - the reply is marker-delimited, so shell/profile noise can never be parsed as usage
// (same lesson as `claude-version-probe`).
//
// curl is a hard requirement, not a fallback-to-wget: the canvas-control and context-link shims
// already require it on every host, and wget would put the token back on the command line.
import type { ClaudeAccount, ClaudeUsage } from '../../shared/types'
import { emptyUsage, usageFromPayload } from './claude-usage-map'
/** Same shape of id every remote path builder validates against (see claude-accounts-core). */
const ACCOUNT_ID_RE = /^[A-Za-z0-9_-]+$/
const BEGIN = '__NTU_BEGIN__'
const END = '__NTU_END__'
const EMAIL = '__NTU_EMAIL__'
const STATUS = '__NTU_STATUS__'
const HTTP = '__NTU_HTTP__'
/** How long the REMOTE curl may take. Below the ssh runner's own 15 s child timeout. */
const REMOTE_CURL_TIMEOUT_S = 10
/** One remote Claude identity the usage popover can show a row for. */
export interface RemoteUsageTarget {
/** Omitted on legacy Claude targets. */
provider?: 'claude' | 'codex'
remoteHome?: string
/** Changes when the reader connection is replaced; prevents reusing a former host session. */
connectionKey?: string
/** Stable row identity: `<hostKey>#<accountId ?? ''>`. Also the service's cache key. */
key: string
/** `user@host` of the connection — matches `ClaudeAccount.host`. */
hostKey: string
/** A connected SSH project on that host, whose ControlMaster carries the read. */
projectId: string
/** Managed remote account, or null for the host's system `~/.claude`. */
accountId: string | null
/** Display label: the account's own label, else the host key. */
label: string
}
/** Runs a POSIX sh command on the target's host; resolves its stdout, or null if it could not run. */
export type RemoteUsageRunner = (
target: RemoteUsageTarget,
command: string
) => Promise<string | null>
/**
* The rows to offer, given every connected SSH project and the configured accounts.
*
* One host answers once: several projects can share a host (and share its `$HOME`), so the hosts
* are deduped and the first connected project is elected reader — a second read over a second
* master would return the same numbers at twice the cost. Each host contributes its system
* account (`~/.claude`, the common case: someone SSHes in and runs plain `claude`) plus every
* managed account pinned to that host. `pending` accounts have no credentials yet, so they are
* skipped exactly as the local popover skips them.
*/
export function remoteUsageTargets(
connected: readonly { projectId: string; hostKey: string }[],
accounts: readonly ClaudeAccount[]
): RemoteUsageTarget[] {
const out: RemoteUsageTarget[] = []
const seen = new Set<string>()
for (const { projectId, hostKey } of connected) {
if (!hostKey || seen.has(hostKey)) continue
seen.add(hostKey)
out.push({ key: `${hostKey}#`, hostKey, projectId, accountId: null, label: hostKey })
for (const a of accounts) {
if (a.host !== hostKey || a.pending || !ACCOUNT_ID_RE.test(a.id)) continue
out.push({
key: `${hostKey}#${a.id}`,
hostKey,
projectId,
accountId: a.id,
label: a.label || a.id
})
}
}
return out
}
/**
* The remote sh command for one account's usage. `accountId` null = the host's system account.
*
* The two file paths mirror `usageCredsPaths`' file leg, rooted at the REMOTE `$HOME`: a managed
* account keeps both under its config dir (`remoteAccountConfigDir`), the system account splits
* them (`~/.claude/.credentials.json` + `~/.claude.json`). There is no keychain leg — a remote
* host is a Linux server in practice, and prompting a headless macOS host's Keychain over ssh
* would hang rather than answer.
*
* The account id is re-validated here even though the caller already filtered on it: this is an
* interpolation into a remote shell command, and the type system is compile-time only.
*/
export function remoteUsageCommand(accountId: string | null): string {
if (accountId !== null && !ACCOUNT_ID_RE.test(accountId)) {
throw new Error(`invalid account id: ${JSON.stringify(accountId)}`)
}
const credsFile = accountId
? `"$HOME/.nodeterm/claude-accounts/${accountId}/.credentials.json"`
: '"$HOME/.claude/.credentials.json"'
const identityFile = accountId
? `"$HOME/.nodeterm/claude-accounts/${accountId}/.claude.json"`
: '"$HOME/.claude.json"'
// `tr -d` first so a pretty-printed file parses too (grep is line-based, and the CLI's writer
// is not contractually single-line). `head -n 1` takes the first match: in `.claude.json` —
// large and full of unrelated history — the identity block is the one we want, and a later
// stray "emailAddress" must not win.
const firstString = (key: string): string =>
`grep -o '"${key}"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed 's/.*"\\([^"]*\\)"$/\\1/'`
const flatten = (file: string): string => `tr -d '\\n\\r' < ${file} 2>/dev/null`
return [
`printf '%s\\n' '${BEGIN}'`,
// `.credentials.json` holds MORE than one "accessToken": every MCP server the CLI has
// authorized keeps its own under `mcpOAuth`. Taking the first match in the file hands the
// endpoint an MCP token, which answers 401 — i.e. the row reports "not signed in" on a host
// that is perfectly signed in. So narrow to the `claudeAiOauth` object first, exactly as the
// local `parseCreds` does (`j.claudeAiOauth ?? j`); a file without that key falls back to the
// whole text, which is the flat top-level shape parseCreds also accepts.
`c=$(${flatten(credsFile)})`,
`case "$c" in *claudeAiOauth*) c=\${c#*claudeAiOauth}; c=\${c%%\\}*};; esac`,
`t=$(printf '%s' "$c" | ${firstString('accessToken')})`,
`e=$(${flatten(identityFile)} | ${firstString('emailAddress')})`,
`printf '${EMAIL}%s\\n' "$e"`,
`if [ -z "$t" ]; then printf '${STATUS}nocreds\\n%s\\n' '${END}'; exit 0; fi`,
`if ! command -v curl >/dev/null 2>&1; then printf '${STATUS}nocurl\\n%s\\n' '${END}'; exit 0; fi`,
// The token goes in on stdin as a curl config directive — never in argv, where `ps` would
// hand it to every other user on the host.
`printf 'header = "authorization: Bearer %s"\\n' "$t" | ` +
`curl -sS -m ${REMOTE_CURL_TIMEOUT_S} --config - ` +
`-H 'anthropic-beta: oauth-2025-04-20' ` +
`-w '\\n${HTTP}%{http_code}\\n' ` +
`'https://api.anthropic.com/api/oauth/usage' 2>/dev/null`,
`printf '%s\\n' '${END}'`
].join('; ')
}
export interface RemoteUsageOutput {
/** 'nocreds' | 'nocurl' when the remote short-circuited, else null. */
reason: string | null
email: string | null
/** HTTP status curl reported, or null when it never got that far. */
httpCode: number | null
/** The response body, with every marker line stripped. */
body: string
/** Did the command actually run to completion (both markers present)? */
complete: boolean
}
/**
* Split the marker-delimited reply. Anything outside BEGIN/END is discarded — an ssh banner, a
* host's MOTD or an rc-file warning is noise, and parsing it as JSON is how a "usage" row ends
* up reporting nonsense.
*/
export function parseRemoteUsageOutput(stdout: string): RemoteUsageOutput {
const start = stdout.indexOf(BEGIN)
const end = stdout.indexOf(END, start + 1)
const complete = start >= 0 && end > start
const inner = complete ? stdout.slice(start + BEGIN.length, end) : ''
let reason: string | null = null
let email: string | null = null
let httpCode: number | null = null
const bodyLines: string[] = []
for (const line of inner.split('\n')) {
if (line.startsWith(EMAIL)) {
const v = line.slice(EMAIL.length).trim()
email = v || null
} else if (line.startsWith(STATUS)) {
reason = line.slice(STATUS.length).trim() || null
} else if (line.startsWith(HTTP)) {
const n = Number(line.slice(HTTP.length).trim())
httpCode = Number.isFinite(n) && n > 0 ? n : null
} else {
bodyLines.push(line)
}
}
return { reason, email, httpCode, body: bodyLines.join('\n').trim(), complete }
}
/**
* One target's snapshot. Fails soft in every direction — this is an informational pill, and a
* host that is mid-reconnect, missing curl, or logged out must degrade to a quiet row rather
* than an error the user has to dismiss.
*
* Status mapping mirrors the local fetch: no credentials or a 401/403 means "nothing to show
* for this identity" ('unavailable', which the UI hides), while a reachable-but-broken read
* ('error') stays visible — a configured account whose numbers stopped arriving is information.
*/
export async function fetchRemoteUsage(
target: RemoteUsageTarget,
run: RemoteUsageRunner,
now: number
): Promise<ClaudeUsage> {
let stdout: string | null = null
try {
stdout = await run(target, remoteUsageCommand(target.accountId))
} catch {
return emptyUsage(null, now, 'error')
}
if (stdout === null) return emptyUsage(null, now, 'error')
const out = parseRemoteUsageOutput(stdout)
// The command never ran (master down, project disconnected mid-read): not evidence that this
// account has no subscription, so it must not report 'unavailable' and vanish from the popover.
if (!out.complete) return emptyUsage(out.email, now, 'error')
if (out.reason === 'nocreds') return emptyUsage(out.email, now, 'unavailable')
if (out.reason) return emptyUsage(out.email, now, 'error')
if (out.httpCode === 401 || out.httpCode === 403) return emptyUsage(out.email, now, 'unavailable')
if (out.httpCode === 429) return { ...emptyUsage(out.email, now, 'error'), rateLimited: true }
if (out.httpCode !== 200 || !out.body) return emptyUsage(out.email, now, 'error')
try {
return usageFromPayload(JSON.parse(out.body), out.email, now)
} catch {
return emptyUsage(out.email, now, 'error')
}
}