@threadcrumbs/threadgauge 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,34 @@
+# License
+
+Copyright (c) 2026 Threadcrumbs LLC. All rights reserved.
+
+This software is proprietary. Threadcrumbs LLC grants you a free, non-exclusive,
+non-transferable license to install and run it, as published by Threadcrumbs LLC, on computers
+you own or control, for your personal or internal business use.
+
+Paid features, such as Threadgauge Pro, are licensed to you only as your license key and
+subscription allow, under the terms you agreed to when you bought them.
+
+You may not:
+
+- copy, modify, merge, publish, distribute, sublicense, rent, or sell this software, in whole
+  or in part;
+- reverse engineer, decompile, or disassemble it, except where the law allows this despite
+  this restriction;
+- get around its license checks, or share a license key or paid content beyond what your
+  subscription allows.
+
+This license ends automatically if you break these terms. When it ends, you must stop using
+the software and delete your copies of it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NONINFRINGEMENT. TO THE FULLEST EXTENT THE LAW ALLOWS, IN NO EVENT SHALL THREADCRUMBS LLC BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Any other use needs a separate written agreement with Threadcrumbs LLC
+(hello@threadcrumbs.io).
+
+Portions of this software are third-party code used under their own licenses, which are
+reproduced in [NOTICES.md](NOTICES.md). Those licenses govern those portions.

package/NOTICES.md

@@ -0,0 +1,137 @@
+# Notices
+
+## Third-party
+
+Threadgauge includes the following third-party software, used under its own license.
+
+### Original source code
+
+Portions of Threadgauge are derived from source code released under the MIT License.
+
+```text
+MIT License
+
+Copyright (c) 2026 Jarren Rocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### Fonts
+
+The new interface includes these fonts as .woff2 files, from the @fontsource packages. Each is used under the SIL Open Font License, Version 1.1, which follows the list.
+
+- Inter and Inter Tight: Copyright 2016 and 2022 The Inter Project Authors (https://github.com/rsms/inter)
+- Barlow and Barlow Semi Condensed: Copyright 2017 The Barlow Project Authors (https://github.com/jpt/barlow)
+- IBM Plex Sans, IBM Plex Sans Condensed, and IBM Plex Mono: Copyright 2017 and 2019 IBM Corp.
+- Atkinson Hyperlegible Next: Copyright 2020-2024 The Atkinson Hyperlegible Next Project Authors (https://github.com/googlefonts/atkinson-hyperlegible-next)
+- Atkinson Hyperlegible Mono: Copyright 2020-2024 The Atkinson Hyperlegible Mono Project Authors (https://github.com/googlefonts/atkinson-hyperlegible-next-mono)
+- Fira Sans and Fira Sans Condensed: Copyright 2012-2015 The Mozilla Foundation and Telefonica S.A.
+- Fira Code: Copyright 2014-2020 The Fira Code Project Authors (https://github.com/tonsky/FiraCode)
+- Source Sans 3 and Source Code Pro: Copyright 2010-2020 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'
+- JetBrains Mono: Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+- Inconsolata: Copyright 2006 The Inconsolata Project Authors (https://github.com/cyrealtype/Inconsolata)
+
+```text
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+```

package/README.md

@@ -1,3 +1,423 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Threadgauge — live telemetry for your coding agents
+
+Threadgauge is a live dashboard of every coding agent working on this machine. It shows what each
+one is doing right now, how full its context window is, what it has cost, how much code it has
+changed, and how far through its plan it is.
+
+It reads each harness's own files on your machine. Nothing about your threads is uploaded, and
+there is no account to create. The only thing it ever sends is a Pro license key, and the
+license that key earns, to the Threadcrumbs license service. On its own, it never writes to a
+harness. Anything that would, such as adding a statusline or hooks to get data a harness doesn't
+save to disk, will be a setting you switch on.
+
+## Run it
+
+```bash
+npx @threadcrumbs/threadgauge
+```
+
+You need Node 22.13 or newer. This serves the dashboard on port 5274 and opens it in your browser at
+`http://localhost:5274`, the address Threadnauts links to, so your view settings are the same
+either way. If it's already running, it opens that copy instead of starting a second one. If
+something else holds the port, Threadgauge tries the next one, up to 20 ports, and tells you
+where it ended up.
+
+| Option | |
+| --- | --- |
+| `-p`, `--port <number>` | Serve on this port, or the next free one |
+| `--no-open` | Start without opening the browser |
+| `-v`, `--version` | Print the version |
+| `-h`, `--help` | Show the options |
+
+### Next to Threadnauts
+
+Threadnauts starts on 5274 too. Whichever app starts first gets 5274, and the other takes the
+next free port. Before taking a port, Threadgauge checks both `127.0.0.1` and `::1`, because a
+Vite dev server listens only on `::1`. If something answers on either, Threadgauge asks it what
+it is. `GET /api/about` answers `{ "app": "threadgauge", "version": … }`. Threadgauge uses that
+to recognize a copy of itself, and Threadnauts uses it to find the dashboard to open.
+
+### From a checkout
+
+```bash
+pnpm install && pnpm dev
+```
+
+You need [pnpm](https://pnpm.io/installation) too, and a checkout of
+[threadcrumbs/common](https://github.com/threadcrumbs/common) beside this one, as `../common`. The
+harness readers live there and are linked in.
+- `pnpm dev` runs everything in one process, with the API inside the Vite dev server.
+- `pnpm dev:demo` shows made-up demo threads instead of this computer's, for a look or a screenshot.
+- `pnpm check:layout` checks the dev server with the demo threads at several window sizes, for
+  sideways scrolling, overflow, clipped text, and console errors.
+- `pnpm test` runs the test suite.
+- `pnpm start` builds and serves the built version.
+- `pnpm serve` serves the built version if `dist/` already exists.
+
+## Free and Pro
+
+Everything Threadgauge shows is free. Seeing is free, and acting is Pro.
+
+| | What it includes |
+| --- | --- |
+| **Threadgauge** | Every harness and every thread, [older ones](#older-threads) included: [the list](#the-thread-list), [the table](#the-table), [each thread's details](#a-threads-details), usage limits, Open, screenshots, and the explanation behind every figure |
+| **Threadgauge Pro** | Arrives with Threadbare: answering, prompting, and messaging your agents from Threadgauge |
+
+- **Alerts** come next, and they're free too, since they only read.
+- **Nothing to buy yet:** Threadgauge Pro goes on sale when Threadbare's first piece ships. Until
+  then, the license row in Settings says so, and Respond in a thread's details says what's coming.
+- **Release dates:** each Pro feature will have one. A license opens the features released while
+  its owner paid, so someone who stops paying keeps those and misses only the ones released after.
+- **Development:** `pnpm dev` opens every Pro feature. Add `?free` to its address to see the free
+  tier.
+
+### Entering a license key
+
+Settings › Threadcrumbs › Threadgauge Pro has **Enter a key**, which opens the license box. Paste
+the Threadcrumbs license key from your Polar receipt (it starts with `THREADCRUMBS-`) and choose
+Activate.
+- **One key for every app:** the same key comes with Threadnauts Pro, Threadgauge Pro, and the
+  bundle of both. The license says which apps the plan includes, and Threadgauge opens Pro only
+  when it includes Threadgauge Pro. Switching plans in Polar's customer portal keeps the key.
+- **One activation per machine:** Threadgauge sends the key and this computer's device ID to the
+  Threadcrumbs license service, which checks it with Polar and returns a signed license. The
+  license and device ID go in one `license.json` that every Threadcrumbs app on this computer
+  shares, in `%APPDATA%\Threadcrumbs`, `~/Library/Application Support/Threadcrumbs`, or
+  `~/.local/share/threadcrumbs`. A key entered in Threadnauts counts here too, and the machine
+  uses one of the key's three device slots either way. Remove a computer in Polar's customer
+  portal to free its slot.
+- **Checked offline:** the license is checked against public keys built into Threadgauge, with
+  no network call. While Threadgauge is open, it renews the license about once a week. A
+  license that can't renew keeps working for two weeks past its own two-week life.
+- **Nothing is written** until you first activate a key.
+- **Where keys go:** a built copy uses the license service at `threadcrumbs.io/api`. `pnpm dev`
+  uses the one running from `../cloud` at `localhost:8787/api`, and `THREADCRUMBS_CLOUD_URL`
+  points either one somewhere else.
+
+## What it reads
+
+Sessions from the last 24 hours, plus every live one, from each harness on the machine, and
+[older threads](#older-threads) too. Threads you archived or deleted in the harness are left out:
+
+| Harness | What it shows |
+| --- | --- |
+| **Claude Code** (Anthropic) | ✅ Everything in the next table, from the desktop app and the CLI |
+| **Codex** (OpenAI) | ✅ Status, current tool, context, tokens, plan, subagents, lines counted from patches that applied, and its usage limits. No spend: Codex doesn't save it |
+| **OpenCode**, **Kilo Code** | ✅ Status, current tool, context, tokens, spend, lines, plan, and subagents. OpenCode 2.x doesn't record lines |
+| **Hermes** (Nous Research) | ✅ Status, current tool, context, tokens, spend, plan, and subagents. No lines |
+| **Cursor** | ✅ Status, the tool it last called, plan, and subagents. Cursor saves no tokens, context, model, or spend |
+| **Antigravity CLI** (Google) | ✅ Status and plan. Its transcript lands only after each turn, and it keeps tokens and context in a format that isn't read |
+
+Only Claude Code has been checked against a real install. The other readers were built from each
+harness's source code, or from the formats other open-source tools parse, and tested against fake
+installs. Where a harness doesn't record something, Threadgauge shows "—" or "Not recorded".
+
+For each Claude Code session it shows:
+
+| | Where it comes from |
+| --- | --- |
+| Status | The live process's own record (`~/.claude/sessions/*.json`), how its transcript ends, and the Claude app's own record of the thread: whether you've read it, whether its turn is waiting on you, and whether you archived it |
+| Tool running now, and for how long | A tool call in the transcript with no result yet |
+| Context fill | The last reply's input, cache, and output tokens, against the model's `max_input_tokens` in Claude Code's model catalog cache |
+| Tokens | Every reply's usage, counted once per message |
+| Spend | Every reply's tokens at Anthropic's API list prices, subagents included, the same way Claude Code's `/usage` computes its total. A Pro or Max plan covers this usage, so it's not what a subscriber pays |
+| Lines changed | Lines added and removed by Edit and Write, and by shell commands that changed files, subagents included |
+| Plan progress | `TodoWrite` and `update_plan` calls |
+| Subagents | `<session>/subagents/*.jsonl` transcripts still mid-turn |
+
+## The thread list
+
+The list down the left side holds every thread. Each row shows its organization and folder, the
+harness's initials, a status lamp, the title, and what it's doing now: the tool running and for
+how long, the subagents it's waiting on, or the question, command, or error it's stopped on.
+Beside that are its context used as a small gauge, its output, and its lines changed, and under it
+are its branch, worktree, model with effort bars, and plan ticks. Hold the pointer on a row for a
+moment to peek at its figures, and click it for its details.
+- **Status lamps** above the list count the threads in each status. Press one to show only that
+  status, or the total to show them all. The counts follow the repo filter and match Threadnauts'
+  for the same threads.
+- **Search,** with `/` or the magnifier, filters by title, repo, branch, model, and what a thread
+  asks. Ctrl+K lists threads and actions in the same field.
+- **The filter bar** says what's filtered, as in "4 of 22: Needs you in api", with Clear filters.
+- **The footer** totals the live agents, output, and lines changed for the threads shown, each
+  with a picture, and has a gauge for each usage limit a harness records. So far that's Codex's
+  5-hour and weekly limits, which it saves in its own files.
+- **The tab's title** counts the threads that need you, as in "(2) Threadgauge".
+
+### Settings
+
+The gear, or `?`, opens Settings in the list's place:
+- **Threads:** Group by Turn (Your turn, Agents' turn, Idle), Live (live, the last 24 hours, then
+  older), Repo, or State. Sort by Needs you first, Longest wait, Most recent, Context used, or
+  Title. Repo shows one repo's threads, with each repo's count in the menu.
+- **Look:** the font for text and the font for code.
+- **Connection:** each harness and whether it's watched, and every usage limit in full. The Live
+  button in the list header opens it too.
+- **Threadcrumbs:** the Threadgauge Pro license, and **Open Threadnauts colony** when Threadnauts
+  is running on this computer.
+- **Keys:** every key, as in [the table below](#keys).
+
+Your choices are remembered in this browser.
+
+### Organizations
+
+In the Repo grouping, each repo's header starts with its organization's name and a building icon,
+and repos without one come first.
+- **Where the name comes from:** the repo's own package name, such as `@threadcrumbs/site` in
+  `package.json`, or its Go module, Maven group, and the like. A thread working in a folder inside
+  a repo, like a crate in `math/engine`, uses the repo's package name. A repo with no package file
+  counts by its GitHub owner when another repo's package already names that organization.
+- **Not from folders:** the folders the repos sit in don't count.
+- **Same as Threadnauts:** this is `@threadcrumbs/common/orgs`, which Threadnauts uses too.
+
+## The table
+
+Close a thread on anything wider than a phone, and every thread fills the window as a table, under
+the status lamps: where it is, the thread (its lamp, title, and what it's doing now), plan, lines,
+context (a gauge and a sparkline), input, output, cache reads, prompts, and last active. Click a
+heading to sort by it, and click a row to open that thread beside the list again. As the window
+narrows, the table tightens and drops its sparklines and plan ticks before it ever scrolls
+sideways. On a phone, closing a thread goes back to the list.
+
+## Older threads
+
+Threads from before the last 24 hours are listed too, in an **Older** group in the Live grouping,
+and in their repos and states in the others.
+- **Quick read:** an older thread's row shows its status, title, repo, branch, and when it was
+  last active, from the same quick read Threadnauts does of every thread. Its figures aren't read
+  until you open it, so the table leaves them blank.
+- **Read when opened:** opening one reads that thread in full, so its details have everything a
+  recent thread's do. Claude Code is the only harness this works for so far; an older thread from
+  another harness says so.
+- **Kept current:** the list of older threads is refreshed once a minute, and when a thread leaves
+  the last 24 hours.
+
+## A thread's details
+
+Click a thread for its details beside the list. The list stays live, and clicking another thread
+switches. The address keeps the open thread (`#thread=…`), so a reload brings it back, and Back
+closes it. How it fits depends on the window:
+- **Side by side:** the list and the details share the window. Drag the handle between them, or
+  focus it and press Left or Right, to change the list's width, which is remembered. `[` collapses
+  the list to a narrow rail and shows it again.
+- **Phones:** a short list sits above the details, with a bar between them that steps to the
+  previous or next thread, or shows the whole list. The Conversation opens from a card at the
+  bottom.
+
+At the top are the thread's folder, branch, and worktree, the up and down arrows for the previous
+and next thread, ×, the title, and a state line with its status, what it's doing, and its
+harness's chip, which is the Open button. Under them:
+- **The ask block** shows what a thread is stopped on: the question with its options, the command
+  waiting for approval, or the error and how many times it retried. It also shows the command
+  running now and the subagents and threads it's waiting on, each a link. Its buttons are Respond,
+  which says what Threadgauge Pro will add, and Open in the harness.
+- **Latest prompt,** with Show all for a long one.
+- **The Conversation,** which `R` or the button on the right edge opens: the thread's prompts and
+  replies, with the ask block's buttons on a card for anything that needs you.
+
+The sections sit in up to four columns, Progress, Activity, Changes, and History, as the window
+allows. Each one shows its main figure when it's collapsed, with a small picture beside it:
+
+| Section | What it shows |
+| --- | --- |
+| Plan | Every step, with what's done and what's current, finished when the thread is done |
+| Subagents | Every subagent it started, newest first, with its type, model, output, and what it's doing now. Finished ones stay listed, dimmed. For Claude Code, click one to see its own activity, tools, files, prompts, and context |
+| Thoughts | The thinking the harness recorded, with the newest thought and when it came |
+| Activity | The newest 100 tool calls: when each started, its target (a file, command, or search), how long it took, and whether it failed. A running call counts up live. Expand one for its full command or input and a failed call's own error output. Filter by tool, by failures, or by a reply's time on the context chart |
+| Errors | API errors and failed turns, open by default when the thread's last turn failed |
+| Files changed | Lines added and removed per file. Expand a file to see the agent's own changes as a diff, newest first, with line numbers where the harness records them. A note names any other thread from the last day that changed the same file, and links to it |
+| Tools | Calls, time, and failures per tool, over the whole thread. Click a tool to show only its calls in Activity |
+| Context | A gauge with the room left, what fills the window (messages, system prompt, built-in tools, MCP tools, skills, memory files, the space kept free for compacting, and free space, like Claude Code's `/context`), and context after every reply against the model's limit, with its compactions. Hover or click a reply on the chart for its value, and show that reply's calls in Activity |
+| Prompts | Every prompt, newest first, with its time. Expand a long one to read all of it |
+| Session | The session id, the command that resumes it in a terminal, its folder, project, branch, worktree, models and their spend, effort, duration, start time, and the file it was read from |
+
+What each harness records differs:
+- **Claude Code and Codex** fill in every section, except that Codex has no compactions or spend.
+- **OpenCode and Kilo** have no compactions, Kilo has no per-file lines, and OpenCode 2.x has no files.
+- **Hermes** has no per-reply history or files.
+- **Cursor** saves no times or results for its tool calls, and no tokens.
+- **Antigravity** has a step log, prompts, the plan, and errors.
+
+A section a harness doesn't record says "Not recorded", and a note at the end says what's
+missing and why. Every figure and section label opens a tip that says what it means for that
+thread's harness, with a larger picture and links to the harness's own docs where they help.
+
+### Copy and open
+
+- **Copy:** anything you'd copy has a copy button: the session id, the resume command, branch
+  and worktree names, a call's command or input, its error, a prompt, and an error message.
+- **Paths:** every file and folder path has two buttons, one to copy its full path and one to
+  open it.
+  - **Files** open in your editor at the line the agent last changed, or at the line it read.
+    "Open files in", in Files changed, picks VS Code, Cursor, Windsurf, Zed, or the default app,
+    and is remembered in this browser.
+  - **Folders** open in Explorer, Finder, or your file manager.
+- **What it will open:** Threadgauge opens only files and folders that thread touched: the files
+  it changed or named in a tool call, its folders, its Markdown memory files, and its transcript.
+- **Nothing runs:** with "Default app" chosen, a file Windows or macOS would run instead of open,
+  such as a script, a program, a shortcut, or an installer, is shown selected in File Explorer or
+  Finder instead.
+
+## Keys
+
+| Key | What it does |
+| --- | --- |
+| N | Goes to the next thread waiting on you: first the ones that need you, then finished ones, newest first, and opens its details |
+| J, K | Next and previous thread, in the list's order |
+| Enter | Opens the thread in its harness, unless a button or field has focus |
+| Esc | Steps back: closes a tip, Settings, or a subagent, then the thread |
+| P | Saves a screenshot |
+| ? | Opens Settings |
+| [ | Collapses the list, or shows it again |
+| R | Opens or closes the Conversation |
+| / | Searches threads |
+| Ctrl+K | Searches threads and actions |
+
+Keys do nothing while you're typing or with Ctrl, Alt, or Cmd held, except Ctrl+K.
+
+## Opening a thread
+
+The harness chip in a thread's state line, and Open in its ask block, hand the thread to the
+harness it came from, the same way Threadnauts does.
+- **A thread running in a terminal:** that terminal's window comes to the front.
+- **Claude Code:** the desktop app opens on the thread.
+- **Other harnesses:** their own deep link.
+- **Linux with no desktop app:** the harness's CLI resumes the thread in a new terminal.
+- **When nothing on the computer opens the link:** Claude Code first tries VS Code's Claude Code
+  extension and says so. Otherwise a dialog names the app that's missing, with a link to download
+  it and to any other app that would do, and offers to open the thread in a terminal instead when
+  the harness's CLI is installed.
+
+A message in the corner says what happened. Cursor has no link to a single thread, so its Open
+opens the repo in Cursor and says so. Hermes threads have no Open, because Hermes has nothing to
+link to.
+
+## Threadnauts
+
+If Threadnauts is running on this computer, Settings › Threadcrumbs shows **Open Threadnauts
+colony**, which opens it in its own tab, reusing that tab after the first time. Threadgauge looks
+for it every 30 seconds and whenever its window gets focus, on ports 5274 to 5293, the same way
+Threadnauts finds Threadgauge.
+
+## Screenshots
+
+The camera button in the list header, or P, saves a PNG of the window as it looks right now,
+named `threadgauge-<date>-<time>.png`. It's at the screen's own resolution, so a 1440 × 900 window
+on a 2× display makes a 2880 × 1800 image, with the fonts drawn in. The open details, where each
+list is scrolled to, and any message in the corner are all in it. The page draws it itself, so the
+browser never asks to share your screen, and its tabs and toolbar aren't in the picture.
+
+## What moves
+
+Anything happening right now moves:
+- **Live threads:** a working thread's status lamp moves, and so does a running tool call's line in
+  Activity.
+- **The context chart:** a ring pings from the newest point while the thread is live.
+
+Anything that changes flashes once: figures and totals, a status that changes, and rows that
+change, such as a call that finishes or a plan step that moves on. New rows fade in.
+
+With reduced motion turned on in the operating system, none of it moves.
+
+Each status uses the same color as in Threadnauts, and they're listed in this order, most urgent
+first:
+
+| Status | Means |
+| --- | --- |
+| Needs you | Stopped on a question or permission prompt only you can answer, or, for Claude Code, a turn the Claude app marked as waiting on you |
+| Error | The last turn failed |
+| Done | It's your turn: the turn ended in the last 30 minutes, or earlier and you haven't read the reply. Codex, Hermes, and OpenCode 2.x record when you read a thread, so for them only that counts |
+| Working | Running right now |
+| Waiting on agents | Its own work is paused until the subagents it started finish or, for Claude Code, until another session it asked to hear from goes quiet. The row names them: "Waiting on 2 subagents" or "Waiting on Threadnauts main", and the details link to each one |
+| Idle | Nothing is running for it, and you've seen its last reply |
+
+## How it stays live
+
+The server watches the harness folders and sends changes to the page with
+[server-sent events](https://developer.mozilla.org/docs/Web/API/Server-sent_events).
+- **Reading:** a transcript is read in full once, and after that only the bytes added since the
+  last read.
+- **Batching:** bursts of file events are grouped into one scan every quarter second.
+- **Heartbeat:** a scan every 5 seconds catches anything the file watcher missed, such as a
+  process that has exited.
+
+## Keeping it local
+
+These work the same way as in Threadnauts:
+- **Loopback only:** the server binds to `127.0.0.1`.
+- **Host check:** it refuses any request whose `Host` isn't this machine, which stops DNS
+  rebinding.
+- **Origin check:** a request that names an `Origin` is answered only when it's this server's own
+  page, with the same host and port, so a page on another port of this machine is refused too. A
+  request with no `Origin`, such as Threadnauts' server reading `/api/sessions`, may only read.
+- **JSON only:** every POST needs `Content-Type: application/json`, which a form or a plain-text
+  request from another page can't send without asking first.
+- **Why it's strict:** `/api/sessions` and the stream carry each thread's current command line,
+  clipped, and the question or command it's stopped on, not just titles.
+- **Content-Security-Policy:** the built page only runs its own script, can't be framed, and
+  only talks to this server. The server, not the page, talks to the license service.
+
+`THREADGAUGE_HOST` changes the address it binds to. `THREADGAUGE_ALLOWED_HOSTS` adds extra host
+names that pass the checks, separated by commas. Anyone who can reach the port can see every
+session title, folder, and branch, so only widen it on a network you trust.
+
+## Layout
+
+```
+bin/threadgauge.mjs   the `threadgauge` command: picks a port and opens the browser
+server/
+  lib/                port search, the local-request check, opening a URL
+  monitor.mjs         watches every harness, keeps the current sessions, reports changes
+  threads.mjs         the quick read of every thread, for older threads
+  history.mjs         older threads, and reading one in full when it's opened
+  api.mjs             /api/about, /api/entitlements, /api/sessions, /api/sessions/<id> (and its
+                      /hunks and /subagents/<id>), /api/history, /api/stream, /api/threadnauts,
+                      POST /api/open, POST /api/open-path, POST /api/license
+  details.mjs         the details' data: details without diff lines, other threads that changed the
+                      same files, and the resume command
+  paths.mjs           opens a file or folder the thread touched, in an editor or the file manager
+  license.mjs         reads the shared license, activates and renews it with the license service
+  open.mjs            finds a thread's ref through its harness adapter, opens it, and writes its
+                      resume command
+  threadnauts.mjs     finds a running Threadnauts for Settings' link
+  http-server.mjs     serves the built page, with the API and security headers
+src/
+  main.js             the boot screen, then the app
+  live.js             the page's end of the event stream, the details fetch, and Open
+  arrange.js          grouping, sorting, and filtering threads
+  tiers.js            the Pro features and their release dates, shared with the server
+  format.js           numbers, money, durations, times, model names
+  next/               the app: the list, table, details, Conversation, Settings, keys, and layout
+  pictures/           the gauges and small charts, as SVG strings
+  theme/              colors, type, spacing, status colors, and the fonts
+  ui/                 shared parts: the mark, editors, the "?" text, screenshots, the license box
+tools/
+  demo/               the demo threads that `pnpm dev:demo` serves
+  audit/, layout-audit.mjs   `pnpm check:layout`
+test/                 node --test
+site/                 the threadgauge.io website, HTML and CSS plus copy.js for the copy buttons
+```
+
+`site/` is deployed and previewed with the other Threadcrumbs sites;
+[threadcrumbs/site](https://github.com/threadcrumbs/site)'s README has both.
+
+The telemetry readers themselves, one per harness, are in `@threadcrumbs/common/telemetry`. Their
+contract and tests live in the common repo, beside the session readers Threadnauts uses:
+
+```
+../common/telemetry/  one telemetry reader per harness (README.md is the contract)
+```
+
+## Publishing a release
+
+Write the release notes as a `## <version>` entry in `../threadgauge-community/CHANGELOG.md` and
+commit them. Then, from this folder, run `pnpm auto-publish` with `patch`, `minor` or `major`, or
+with nothing to publish the version already in `package.json`. Add `--dry-run` first to see the
+plan. It publishes `@threadcrumbs/common` first if it changed, then tests, builds, publishes, tags,
+and pushes, which deploys threadgauge.io. The whole sequence is described in
+`../common/README.md`.
+
+## License
+
+Proprietary. See [LICENSE.md](LICENSE.md). Portions are derived from MIT-licensed source code, whose
+notice is in [NOTICES.md](NOTICES.md).