token-weather · Claude Code mod

Preview · a replayed session in a sandbox

claude · ~/work/app · token-weather

› 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 ☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Band

☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady

README

DeepSeek Orb

English | 中文

A desktop AI agent assistant that stays on call, for macOS and Windows, built on DeepSeek Harness (dsh 0.2.1-alpha.2).

DeepSeek Orb is an unofficial community project and is not affiliated with DeepSeek AI.

A floating ball rests at the edge of your screen. Tell it what you need: quick, visible actions are executed directly in the current app, finished in front of you through Computer Use; long-running complex tasks are dispatched to a background coding session, and the result comes back to the ball when it finishes. The main window keeps the full dsh Web UI — session management, the plugin market, and model settings — so you can still write code, edit files, and run commands in it.

The app collects no telemetry.

Dual-track agent architecture

The Computer Use Agent inside the floating ball decides how every message is handled; there is no separate task classifier at runtime:

flowchart TD
    user["You speak to the floating ball"] --> orb["Computer Use Agent"]
    orb -->|"Visible GUI actions"| gui["13 GUI tools<br>executed in the current window"]
    orb -->|"Quick lookups: weather, news"| web["web_search / web_fetch<br>answered on the ball"]
    orb -->|"Dig through files, produce documents or websites"| bg["code_agent background session<br>queued, returns immediately"]
    bg -->|"Completion notice"| orb

Foreground track · Computer Use: visible operations — opening apps, clicking buttons, filling forms, changing settings — are executed with GUI tools right in front of you, each step based on a live screenshot of the frontmost window. Quick lookups such as weather or news headlines stay on the ball too, answered directly with web_search / web_fetch.
Background track · Code Agent: complex tasks — digging through files, producing Word/PPT/Excel documents, building a website — are dispatched through code_agent to a background standard session. Dispatch returns immediately; the ball tells you the background is running and you can keep chatting. When the background session ends and the ball is idle, the completion summary returns to the ball automatically, and the Computer Use Agent decides the next move — keep clicking, dispatch more background work, or wrap up.

A background session is the same kind of session you create manually in the main window; it appears in the dsh_orb folder in the main-window sidebar, where you can open, continue, or stop it. Only the ball conversation that started it can continue or stop it. Follow-up changes to the same deliverable go back to the same background session; unrelated new work opens another one. The Stop button on the floating ball only cancels the ball's Computer Use session and never affects a background session.

The floating ball

On startup the ball rests at the right edge of the primary display, slightly below vertical center, always on top. The default model is DeepSeek-V41-Flash at Max thinking.

Hover expands the panel, click pins it, and it collapses when the pointer leaves.
Drag moves the ball; release it after dragging about a fifth of it beyond the left or right screen edge and it docks into a thin gray tab — hover again to slide it back.
Right-click opens the menu: open the main window, floating-ball agent settings and background agent settings (each track picks its own model and thinking level), the selection-toolbar toggle, the coordinate-encoding toggle (millifraction on Windows, pixels on macOS, switchable either way), and quit DeepSeek Orb.
The panel carries the same conversation history as the main window, a composer that grows around the ball (Enter sends, Shift+Enter inserts a newline), the Access chip (view-only / workspace edits / full access, full by default, applying to the ball's commands and the background sessions it dispatches), History (the ball's Computer Use conversations), and New. When the agent asks you a question, the question card is answered right on the ball.
Drag-selecting text in any app pops up a toolbar: Search (opens Bing in your default browser), Translate (the result is written into the ball's current conversation), and Send to agent (the text sits by the input; Enter sends it together with your instruction).
The ball avatar can be replaced with a custom GIF / PNG / WebP (2 MB cap) in main-window Settings → Floating Ball.

Closing the main window does not quit the app; only "Quit DeepSeek Orb" in the right-click menu ends the process.

Computer Use

Every conversation on the ball runs Computer Use: the first message automatically attaches a screenshot of the frontmost app's visible windows, and another screenshot follows every action, so the model always sees the latest screen state. Screenshots automatically omit the ball, the expanded panel, the selection toolbar, and the observation border, and the overlay never blocks clicks while an operation runs. The observed window gets a glowing observation border around it, marking what the agent is looking at. Windows starts in 0–1000 millifraction encoding and macOS starts in pixels; switch either way in the ball's right-click menu or in main-window Settings → Floating Ball.

Tool list: click (single/double/right click, hold modifiers), input_text, scroll, hotkey, long_press, drag, wait, long_wait, screenshot (saved to the Desktop and copied to the clipboard), open_in_browser, open_in_finder, list_apps, open_app.

macOS: the first time you expand the panel you must grant Screen Recording and Accessibility permissions; the onboarding layer opens the matching System Settings pages and disappears once both are granted. Finder automation asks for authorization on first use.
Windows: no system-permission onboarding is needed; windows running as administrator refuse to be clicked or typed into.
Read the safety notice in SAFETY.md before running.

Platform support

Platform	Floating ball and Computer Use	Installers
macOS (Apple Silicon / Intel)	Fully supported; Screen Recording + Accessibility permissions required	Signed DMG / ZIP; local unsigned preview build
Windows x64	Fully supported; administrator windows refuse to be operated	NSIS installer (.exe); local unsigned build
Linux	No floating ball; the main window works, settings controls are disabled	Not a release target

Getting started

Prerequisites

Node.js ^22.19.0 || >=24.0.0, pnpm 11.28.5.
A DeepSeek API key: save it in the main window under Settings → Models after startup, or export DEEPSEEK_API_KEY=… before starting. Keys live in ~/.dsh/.credentials.yaml, shared with the dsh CLI.
The main window's input is available only after a workspace is selected; the floating ball always uses its own dsh_orb workspace, no configuration needed.

Run from source

git clone https://github.com/mini-yifan/deepseek-harness-orb.git
cd deepseek-harness-orb
pnpm install
pnpm run dev:desktop

dev:desktop builds the Host, clients, Web frontend, and the Electron shell, then launches the unpackaged app; once everything is built, pnpm run start:desktop skips the build. The main window shows a splash screen first, loads the Web UI when ready, and the floating ball appears at the screen edge.

Local packaging

Target	Command	Notes
macOS (Apple Silicon)	`pnpm run package:desktop:mac:arm64`	Signed release flow in MAC-RELEASE-PACK.md; unsigned preview build in UNSIGNED-MAC-PACK.md
Windows x64 (unsigned)	`pnpm run package:desktop:win:x64:unsigned`	Environment variables and tool cache in UNSIGNED-WIN-PACK.md; SmartScreen will block it — choose "Run anyway"

Packaging details and platform requirements: apps/desktop/README.md.

Relationship to DeepSeek Harness

This repository is an unofficial derivative of deepseek-ai/deepseek-harness, built on dsh 0.2.1-alpha.2 and not affiliated with DeepSeek AI. The main branch carries the DeepSeek Orb product and merges upstream updates continuously. dsh is DeepSeek AI's open-source everything-is-a-plugin agent harness; this product's sessions, plugins, tools, and Web UI are all driven by it. To go deeper:

Using the desktop app — the full user guide for the floating ball and background dispatch
Computer Use package — GUI tools, coordinate encoding, and permission details
apps/desktop/README.md — development variables, packaging, and updates
docs/architecture.md and packages/README.md — the underlying harness architecture and the package map

Known limitations

No voice input, no screen-region screenshot selection, and no per-click approval.
Only the floating-ball system is excluded from Computer Use screenshots; the main window can always be captured and clicked.
Computer Use is an experimental package shipped inside the app as a built-in runtime extra, not an npm dependency of the Desktop Host.
No floating ball on Linux; the local unsigned Windows installer is blocked by SmartScreen and must be allowed manually.

License

MIT, inherited from upstream DeepSeek Harness; third-party dependency licenses are disclosed in THIRD_PARTY_NOTICES.md.

Source 2 files

hooks/token-weather.mjs 88 lines

1// Token Weather, from "Getting started with Claude Code mods"
2// (https://claude.dev/blog/getting-started-with-claude-code-mods/, Anthropic, 2026-10-01).
3// The published module, unchanged.
4
5// Token Weather: a live forecast of the context window, above the prompt.
6
7const HISTORY = 12;
8const BARS = "▁▂▃▄▅▆▇█";
9const FORECAST = [
10  { upTo: 25, icon: "☀", word: "Clear", color: "yellow" },
11  { upTo: 50, icon: "☁", word: "Cloudy", color: "cyan" },
12  { upTo: 75, icon: "☂", word: "Showers", color: "blue" },
13  { upTo: 90, icon: "☇", word: "Storm", color: "magenta" },
14  { upTo: Infinity, icon: "↯", word: "Compact soon", color: "red" },
15];
16
17// Held by the host, so the history survives a hot reload of this file.
18const readings = { plugin: "token-weather", key: "readings" };
19
20export function register(on) {
21  on("session.start", async ($, e, next) => {
22    const result = await next(e);
23    await takeReading($);
24    return result;
25  });
26
27  on("turn.complete", async ($, e, next) => {
28    const result = await next(e);
29    if (!e.agentId) {
30      await takeReading($); // main-loop turns only, not subagents
31    }
32    return result;
33  });
34
35  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
36    const { value: history = [] } = await $.state.get(readings);
37    if (e.props.hasSurvey || history.length === 0) {
38      return next(e);
39    }
40    const { Box, Text } = $.ui.resolve(e);
41    return band(Box, Text, history, e.props.bodyColumns);
42  });
43}
44
45async function takeReading($) {
46  const { context } = await $.session.usage();
47  if (!context?.window) return;
48  const tokens = context.tokens ?? 0;
49  const percent = context.percent ?? Math.round((tokens / context.window) * 100);
50  const { value: history = [] } = await $.state.get(readings);
51  await $.state.set(readings, [...history, { tokens, window: context.window, percent }].slice(-HISTORY));
52}
53
54function band(Box, Text, history, columns) {
55  const now = history[history.length - 1];
56  const f = FORECAST.find((b) => now.percent < b.upTo);
57  const parts = [
58    Text({ color: f.color, bold: true, children: `${f.icon}  ${f.word}` }),
59    Text({ children: `  ${now.percent}% of context` }),
60    Text({ dimColor: true, children: `  ${short(now.tokens)} / ${short(now.window)}` }),
61  ];
62  if (columns >= 60) {
63    parts.push(Text({ dimColor: true, children: "   last turns " }));
64    parts.push(Text({ color: f.color, children: sparkline(history) }));
65    if (history.length > 1) {
66      parts.push(Text({ dimColor: true, children: trend(history) }));
67    }
68  }
69  return Box({ flexDirection: "row", paddingX: 1, children: parts });
70}
71
72function sparkline(history) {
73  const top = Math.max(...history.map((r) => r.tokens), 1);
74  return history.map((r) => BARS[Math.floor((r.tokens / top) * (BARS.length - 1))]).join("");
75}
76
77function trend(history) {
78  const delta = history[history.length - 1].tokens - history[history.length - 2].tokens;
79  if (delta === 0) return "  steady";
80  return delta > 0 ? `  ▲ +${short(delta)} last turn` : `  ▼ ${short(-delta)} last turn`;
81}
82
83function short(n) {
84  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(1)}M`;
85  if (n >= 1_000) return `${+(n / 1_000).toFixed(1)}k`;
86  return String(n);
87}
88

types/index.d.ts 11 lines

1// Token Weather's type contract, from https://claude.dev/blog/getting-started-with-claude-code-mods/
2// (Anthropic, 2026-10-01). The published file, unchanged.
3
4export type TokenWeatherReading = { tokens: number; window: number; percent: number }
5
6declare module 'claude-code' {
7  interface PluginState {
8    'token-weather': { readings: TokenWeatherReading[] }
9  }
10}
11