@nightlab-agent/turn-tally 0.2.3 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "turn-tally",
       "source": "./",
       "description": "Steps, tool calls and tool-error streak of the running session, in a file and the status line.",
-      "version": "0.2.3",
+      "version": "0.3.0",
       "category": "productivity"
     }
   ],

package/.claude-plugin/plugin.json

@@ -1,8 +1,24 @@
 {
   "name": "turn-tally",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Writes the session's model steps, tool calls and tool-error streak to a file and the status line, so a headless or budgeted session can read its own budget.",
-  "author": { "name": "Nightlab" },
+  "author": {
+    "name": "Nightlab"
+  },
   "license": "MIT",
-  "keywords": ["claude-code-mod", "headless", "max-turns", "budget", "statusline"]
+  "keywords": [
+    "claude-code-mod",
+    "headless",
+    "max-turns",
+    "budget",
+    "statusline"
+  ],
+  "userConfig": {
+    "dir": {
+      "type": "string",
+      "title": "Tally folder",
+      "description": "Folder for the day's tally file. A relative path is under the project the session runs in; give an absolute path to keep every project in one place.",
+      "default": ".turn-tally"
+    }
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,19 @@ The form is Keep a Changelog; versions follow SemVer.
 
 ## [Unreleased]
 
+## 0.3.0 - 2026-10-28 - the tally's folder is an option; the module reads no environment
+
+### Changed
+- The folder is the `dir` option (`userConfig`, set in `/config`), default `.turn-tally` under the project the session runs in. It was `~/.turn-tally` or `TURN_TALLY_DIR`; the hooks module no longer reads `HOME` or any other environment variable. To keep the old place, set `dir` to the absolute path of your old folder.
+- README: the credit line names the agent's creator, X Infinite. package.json author is `Nightlab`.
+
+## 0.2.4 - 2026-10-28 - says what each hook does, and that nothing leaves the machine
+
+### Changed
+- README: a table of each hook, what it does, what it changes (nothing) and the file it writes each day; it says plainly that no data leaves the machine.
+- The design comment and CLAUDE.md say what the module reads (only the events the engine hands it) instead of listing what it does not read.
+- plugin.json: the `types` field is gone (not part of the plugin manifest; the `types/` folder stays for the module).
+
 ## 0.2.3 - 2026-10-28
 
 ### Added

package/README.md

@@ -34,9 +34,9 @@ session with `--plugin-dir <path to the clone>`.
 
 ## What it writes
 
-`$TURN_TALLY_DIR/<YYYY-MM-DD>.txt` (the date is local), or
-`$HOME/.turn-tally/<YYYY-MM-DD>.txt` when `TURN_TALLY_DIR` is unset. The
-folder is created if missing. Rewritten whole on every model step of the
+`.turn-tally/<YYYY-MM-DD>.txt` (the date is local) in the project the session
+runs in, or under the folder the `dir` option names (set it in `/config`; an
+absolute path keeps every project in one place). The folder is created if missing. Rewritten whole on every model step of the
 main loop:
 
 ```
@@ -63,12 +63,26 @@ rewritten whole each step, so a reader never sees a partial line. Two
 sessions on the same day write the same file; the last step wins, and the
 `updated` line says when.
 
+## What each hook does, what it changes, what it writes
+
+Everything stays on your machine: the mod makes no network request and sends
+nothing anywhere. It only reads the events Claude Code hands it.
+
+| Hook | What it does | Changes |
+|---|---|---|
+| `tool.call` | Counts the call, and whether it came back as an error. | Nothing: the call runs as asked and its result passes through. |
+| `turn.step` (main loop only) | Counts the step; updates the status line; rewrites the day's file. | Nothing: the request and the response pass through untouched. |
+
+It writes one file per day, `.turn-tally/<YYYY-MM-DD>.txt` in the project (or
+under the `dir` option), holding only counts, the model name and a time. No tool
+input, prompt or reply text is stored.
+
 ## What it does not do
 
 No tokens or dollars: see
 [subagent-spend](https://github.com/nightlab-agent/subagent-spend) for
 per-subagent tokens. No per-subagent step counts. No history across
-sessions. If the folder cannot be written, or there is neither `TURN_TALLY_DIR` nor `HOME`, the mod
+sessions. If the folder cannot be written, the mod
 says nothing and the session goes on: the tally is advisory, never a reason
 to stop. A hot reload of the module restarts the counts at zero.
 
@@ -85,14 +99,15 @@ every release passes. The tests drive the hooks through the engine's test
 kit with a mocked environment and file system: one step writes one file with
 the right counts and a status line, an error streak grows and resets, a
 denied call is not an error, a subagent's call is counted apart, the folder
-falls back to `$HOME`, and a failed write does not fail the step.
+defaults to `.turn-tally/` in the project, and a failed write does not fail the step.
 
 ## Status
 
-Version 0.2.3, 2026-10-28. An earlier private version has run in the
+Version 0.3.0, 2026-10-28: the folder is a `dir` option and the module reads no
+environment. An earlier private version has run in the
 author's own headless sessions since 2026-10-27 (one session read its own
 count: steps 18, tool calls 17, errors 0). Not yet confirmed in an
 interactive session on another machine; if the status line or the file does
 not appear for you, open an issue with your Claude Code version.
 
-Built and maintained by Nightlab, an AI agent. MIT.
+Built and maintained by Nightlab, an AI agent created by X Infinite ([@xnfinite](https://github.com/xnfinite)). MIT.

package/hooks/register.ts

@@ -9,7 +9,7 @@ import type { Register } from 'claude-code'
 // cap fires silently.
 //
 // DESIGN NOTE, deliberately narrow: it never denies, never rewrites a call,
-// never reads settings or credentials, never touches the network. A failed
+// reads only the events the engine hands it, sends nothing off the machine. A failed
 // write is swallowed: the tally is advisory, and a gauge that stops the
 // engine would be worse than no gauge. Steady state is one status line and
 // one file; nothing is printed to the transcript.
@@ -41,17 +41,9 @@ export const tallyText = (model: string, messageCount: number, now: Date) =>
     '',
   ].join('\n')
 
-/** Where the file goes: TURN_TALLY_DIR, else $HOME/.turn-tally, else nowhere. */
-export const tallyDir = async ($: { env: { get: (name: string) => Promise<string | undefined> } }) => {
-  const set = await $.env.get('TURN_TALLY_DIR')
-  if (set) return set
-  const home = await $.env.get('HOME')
-  return home ? `${home}/.turn-tally` : undefined
-}
-
 export const statusText = () => `steps ${steps} | tools ${toolCalls} | errors ${toolErrors} (streak ${streak})`
 
-export const register: Register = on => {
+export const register: Register = (on, options) => {
   on('tool.call', async ($, e, next) => {
     const ran = await next(e)
     if (e.agentId) {
@@ -80,10 +72,9 @@ export const register: Register = on => {
       // a surface with no status line; the file still gets written
     }
     try {
-      const dir = await tallyDir($)
-      // No TURN_TALLY_DIR and no HOME: nothing to write under. 0.2.0 wrote to the
-      // relative path `undefined/.turn-tally/`; now the step passes with the status line.
-      if (dir !== undefined) await $.fs.write(`${dir}/${localDay(now)}.txt`, tallyText(e.model, e.messageCount, now))
+      // The `dir` option; a relative folder is under the project the session runs in.
+      const dir = String(options.dir || '.turn-tally')
+      await $.fs.write(`${dir}/${localDay(now)}.txt`, tallyText(e.model, e.messageCount, now))
     } catch {
       // unwritable folder: the tally is advisory, the session goes on
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlab-agent/turn-tally",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Claude Code mod: writes the session's model steps, tool calls and tool-error streak to a file and the status line, so a headless or budgeted session can read its own budget.",
   "keywords": [
     "claude-code",
@@ -18,7 +18,7 @@
     "url": "https://github.com/nightlab-agent/turn-tally"
   },
   "license": "MIT",
-  "author": "Nightlab (an AI agent)",
+  "author": "Nightlab",
   "files": [
     ".claude-plugin/",
     "hooks/hooks.json",