@trailkeep/cli 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailkeep",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Injects your private repo notes and the current branch's effort file at session start, plus the effort skill.",
   "author": { "name": "Mario Širić" },
   "repository": "https://github.com/msiric/trailkeep",

package/README.md

@@ -2,7 +2,7 @@
 
 Context for coding agents that works the same in **Claude Code**, **Codex CLI** and **GitHub Copilot CLI**. It keeps three kinds of knowledge apart: what's always true about you, what's always true about a repo, and what matters only for the branch you're on. It also keeps an append-only log of why things were decided.
 
-It's a single POSIX shell script that needs only `git`. It never changes your repos' tracked files. In a repo with no notes, effort or log, it adds at most one hint line to a session, and none at all with `TRAILKEEP_HINT=0`.
+It's a single POSIX shell script that needs only `git`. It never changes your repos' tracked files. In a repo with no notes, effort or log, it adds one short capture rule to a session (about 110 tokens), and nothing at all with `TRAILKEEP_HINT=0`.
 
 ## Install (one command, once per machine)
 
@@ -10,7 +10,7 @@ It's a single POSIX shell script that needs only `git`. It never changes your re
 npm install -g @trailkeep/cli && trailkeep install
 ```
 
-Or without npm:
+Or without npm, or if your npm goes through a company mirror that doesn't carry the package (a 404 from a feed proxy):
 
 ```sh
 git clone https://github.com/msiric/trailkeep ~/.trailkeep && ~/.trailkeep/bin/trailkeep install
@@ -30,8 +30,9 @@ Later, `trailkeep update` gets the latest version the same way you installed it
 |---|---|---|---|
 | **Personal**: you, in every repo | `~/.agents/AGENTS.md` | you | every session, by all three agents |
 | **Repo**: true for every task here | the repo's own `AGENTS.md` (committed) | you and your team | natively by all three agents |
-| **Private repo notes**: things you can't commit | `~/.agents/repos/<repo>/NOTES.md` | you | at session start, by a hook |
-| **Effort**: this branch's goal, plan, progress, decisions | `.trailkeep/<branch>.md` in the worktree, ignored by git | the agent | at session start and after compaction, by a hook |
+| **Personal notes**: preferences the agent picked up | `~/.agents/NOTES.md` | the agent (`trailkeep note --all`) | at session start in every repo, by a hook |
+| **Private repo notes**: things you can't commit | `~/.agents/repos/<repo>/NOTES.md` | you, or the agent (`trailkeep note --repo`) | at session start, by a hook |
+| **Effort**: this branch's goal, plan, progress, decisions | `.trailkeep/<branch>.md` in the worktree, ignored by git | the agent (`trailkeep note` adds a decision, creating the file if needed) | at session start and after compaction, by a hook |
 | **Decision log**: why things happened, append-only | `~/.agents/repos/<repo>/log/YYYY-MM.tsv` | the session-end hook | never loaded; agents search it |
 
 `<repo>` comes from the origin URL, so every clone and worktree of a repo shares the same notes and log.
@@ -41,7 +42,7 @@ Later, `trailkeep update` gets the latest version the same way you installed it
 | When | What happens automatically |
 |---|---|
 | Any session starts in any repo | Notes and the branch's effort file are injected. A one-line pointer mentions the decision log if it has entries. Leftovers from a session that didn't exit cleanly are logged first. |
-| You're on a feature branch with no effort file | One line tells the agent it can run `trailkeep new` for multi-session work. Turn it off with `TRAILKEEP_HINT=0`. |
+| Any session starts in a repo | A short capture rule tells the agent to record decisions, user rules and dead ends the moment they come up, with `trailkeep note`. It doesn't wait for anyone to decide the task "spans sessions". Turn it off with `TRAILKEEP_HINT=0`. |
 | The agent works | It keeps the effort file current: plan ticks, a progress line per session, decisions and dead ends. That's the effort skill's job. |
 | Context gets compacted | The effort file is re-injected fresh. |
 | A session ends | New Decisions and Progress lines from every effort in the worktree go into the decision log, stamped with the commit, the branch's changed files, branch and session id. It takes under 0.1 s, well inside Codex's 3-second limit for this hook. Anything a killed session missed is picked up at the next start, in the background. |
@@ -76,6 +77,7 @@ The format is one event per line, tab-separated, one file per month: `id time ty
 
 ```sh
 trailkeep new        # start an effort for this branch (or ask the agent to)
+trailkeep note "..." # record a decision or dead end for this branch (--repo: whole repo, --all: every repo)
 trailkeep show       # exactly what agents get here at session start
 trailkeep list       # active efforts across all repos, with their last progress line
 trailkeep close      # archive the effort; lists decisions worth promoting
@@ -103,7 +105,7 @@ Files it edits are backed up to `~/.agents/backups/` first.
 - `~/.claude/CLAUDE.md` gets a 3-line block importing `~/.agents/AGENTS.md`; your own lines stay. HTML comments are stripped by Claude, so the markers cost nothing.
 - `~/.codex/AGENTS.md` and `~/.copilot/copilot-instructions.md` become symlinks to `~/.agents/AGENTS.md`. Existing files with content are left alone, with a warning.
 - Hooks go in through a Claude Code plugin (installed from the clone), `~/.codex/hooks.json` and `~/.copilot/hooks/trailkeep.json`. Hook files it didn't create are never edited; it prints what to add instead.
-- The `effort` skill is linked into `~/.agents/skills/`, which Codex and Copilot read. Claude Code gets it from the plugin, at about 60 always-on tokens.
+- The `effort` skill is linked into `~/.agents/skills/`, which Codex and Copilot read. Claude Code gets it from the plugin; its description costs about 75 tokens per session (measured, see `bench/results/stage0-injection.md`).
 - A copy of the tool goes to `~/.agents/trailkeep/`, and `trailkeep` is linked into `~/.local/bin`.
 
 `trailkeep uninstall` removes all of that. It leaves each agent a plain copy of your personal instructions, and keeps `~/.agents` and any `.trailkeep/` folders.
@@ -131,7 +133,7 @@ Live-session behavior can't be tested offline: hooks running, the Claude import
 
 - `TRAILKEEP_HOME` (default `~/.agents`)
 - `TRAILKEEP_MAX_CHARS` (default 9000, max 9500)
-- `TRAILKEEP_HINT=0` (no hint on branches without an effort file)
+- `TRAILKEEP_HINT=0` (no capture rule at session start)
 - `TRAILKEEP_EFFORT` (use a named effort instead of the branch)
 
 It also honours `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `COPILOT_HOME`. It works on Linux and macOS; on Windows, use WSL.
@@ -148,6 +150,8 @@ The workflow bumps the version in all three places, runs the tests, and only the
 
 From a clone, `sh scripts/release patch` (or `X.Y.Z`) does the bump, tests, commit and tag locally and pushes; the tag starts the same workflow, which checks the versions, tests again and publishes. Either way, no machine but GitHub's talks to npm.
 
-npm authentication works one of two ways:
+npm authentication:
 - **Trusted publishing (preferred):** on npmjs.com, open the package's Settings, then Trusted Publisher, then GitHub Actions. Enter owner `msiric`, repository `trailkeep`, workflow `release.yml`. No secret is needed. npm only offers this for packages that already exist.
-- **An `NPM_TOKEN` repository secret,** for the first release only: a granular token with read-and-write access to packages and a short expiry. Delete it once trusted publishing is set up.
+- **An `NPM_TOKEN` repository secret** was used for the very first publish only. The workflow no longer reads it; trusted publishing is set up for `@trailkeep/cli`.
+
+If a publish fails after the release commit and tag were pushed, run the workflow again with that exact version (`-f version=X.Y.Z`); it publishes the existing tag without bumping.

package/bin/trailkeep

@@ -5,7 +5,7 @@
 
 set -u
 
-VERSION="0.3.1"
+VERSION="0.4.0"
 PKG="@trailkeep/cli"
 MARKER="managed by trailkeep"
 
@@ -28,6 +28,7 @@ ROOT=$(cd "$(dirname "$SELF")/.." && pwd -P)
 
 TRAILKEEP_HOME=${TRAILKEEP_HOME:-$HOME/.agents}
 PERSONAL=$TRAILKEEP_HOME/AGENTS.md
+GLOBAL_NOTES=$TRAILKEEP_HOME/NOTES.md    # `note --all`: agent-written, injected everywhere
 REPOS=$TRAILKEEP_HOME/repos
 SKILLS_DIR=$HOME/.agents/skills          # read by Codex and Copilot
 BIN_DIR=${TRAILKEEP_BIN_DIR:-$HOME/.local/bin}
@@ -226,6 +227,12 @@ default_branch() {
   return 1
 }
 
+# One standing instruction, so capture doesn't depend on the agent deciding a
+# task "spans sessions" (it can't know). Measured cost: about 110 tokens.
+capture_rule() {
+  printf '%s\n' 'trailkeep: when something comes up that a later session must not lose (a decision and its reason, a rule or preference the user states, an approach that failed and why), record it right away: `trailkeep note "<what and why>"`. It is kept for this branch and shown at the start of the next session. Use `trailkeep note --repo` for a fact about the whole repo, or `--all` for a personal preference that applies in every repo.'
+}
+
 build_context() {
   in_repo || return 0
   KEY=$(repo_key) || return 0
@@ -238,18 +245,28 @@ build_context() {
   [ -n "$effort" ] && [ -s "$effort" ] && has_effort=1
 
   budget=$MAX_CHARS
+  if [ -s "$GLOBAL_NOTES" ]; then
+    piece "trailkeep: your notes for every repo" "$GLOBAL_NOTES" "$((budget / 4))"
+    budget=$((budget - $(chars "$GLOBAL_NOTES")))
+    [ "$budget" -lt $((MAX_CHARS / 2)) ] && budget=$((MAX_CHARS / 2))
+    printf '\n'
+  fi
   if [ "$has_notes" -eq 1 ]; then
     piece "trailkeep: private notes for this repository" "$notes" "$((budget / 3))"
     budget=$((budget - $(chars "$notes")))
     [ "$budget" -lt $((MAX_CHARS / 2)) ] && budget=$((MAX_CHARS / 2))
     printf '\n'
   fi
-  if [ "$has_effort" -eq 1 ]; then
-    printf 'trailkeep: this branch has an effort file. It is the source of truth for the current task. Keep it current as you work: tick Plan items, add one dated line under Progress before you stop, and record decisions and dead ends (start a line with "Dead end:" for approaches that failed).\n'
+  if [ "$has_effort" -eq 1 ] && ! grep -q '^## Plan' "$effort"; then
+    piece "trailkeep: notes for branch $b" "$effort" "$budget"
+    printf '\n'
+  elif [ "$has_effort" -eq 1 ]; then
+    printf 'trailkeep: this branch has an effort file. It is the source of truth for the current task. Keep it current as you work: tick Plan items and add one dated line under Progress before you stop.\n'
     piece "trailkeep: effort file for branch $b" "$effort" "$budget"
     printf '\n'
-  elif [ "${TRAILKEEP_HINT:-1}" != 0 ] && [ -n "$effort" ] && db=$(default_branch) && [ "$b" != "$db" ]; then
-    printf 'trailkeep: no effort file for branch %s. If this task spans more than one session, run `trailkeep new` and keep it current.\n' "$b"
+  fi
+  if [ "${TRAILKEEP_HINT:-1}" != 0 ] && [ -n "$effort" ]; then
+    capture_rule
   fi
   n=0
   for f in "$(log_dir "$KEY")"/*.tsv; do [ -f "$f" ] && n=$((n + $(lines "$f"))); done
@@ -391,7 +408,8 @@ harvest_file() { # FILE BRANCH SESSION TRANSCRIPT
       l = $0; sub(/^[[:space:]]*[-*][[:space:]]*/, "", l); gsub(/[\t\r]/, " ", l); sub(/[[:space:]]+$/, "", l)
       if (l == "" || l ~ /^\[[ xX]\]/ || (l in seen)) next
       seen[l] = 1; t = sec
-      if (l ~ /^([Dd]ead[ -]end|[Tt]ried |[Rr]ejected|[Rr]everted)/) t = "dead-end"
+      d = l; sub(/^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]:?[[:space:]]*/, "", d)
+      if (d ~ /^([Dd]ead[ -]end|[Tt]ried |[Rr]ejected|[Rr]everted)/) t = "dead-end"
       print t tab l
     }' "$1")
   [ -n "$new" ] || return 0
@@ -558,18 +576,79 @@ EOF
 cmd_new() {
   need_repo; need_branch
   f=$(effort_path "$KEY" "$BRANCH")
-  if [ -e "$f" ]; then
+  if [ -e "$f" ] && grep -q '^## Plan' "$f"; then
     say "Effort already exists: $f"
     return 0
   fi
   kind=branch; [ -n "${TRAILKEEP_EFFORT:-}" ] && kind=named
   ensure_effort_dir
-  effort_template "$BRANCH" "$KEY" "$kind" > "$f" || die "could not write $f"
+  if [ -e "$f" ]; then
+    # a notes-only file from `trailkeep note`: add the task sections, keep the notes
+    kept=$(section "$f" "Decisions and dead ends" | awk 'NF')
+    effort_template "$BRANCH" "$KEY" "$kind" > "$f" || die "could not write $f"
+    [ -n "$kept" ] && printf '%s\n' "$kept" | while IFS= read -r l; do append_to_section "$f" "Decisions and dead ends" "$l"; done
+  else
+    effort_template "$BRANCH" "$KEY" "$kind" > "$f" || die "could not write $f"
+  fi
   remember_repo
   say "Created $f"
   say "Fill in Goal, Done when and Plan (or ask your agent to, with the effort skill)."
 }
 
+# Append LINE at the end of a "## HEADING" section (adds the section if missing).
+append_to_section() { # FILE HEADING LINE
+  tmp=$(mktemp) || return 1
+  awk -v h="## $2" -v add="$3" '
+    function flush(  i) { for (i = 1; i <= n; i++) print buf[i]; print add; print ""; on = 0; done = 1; n = 0 }
+    $0 == h { print; print ""; on = 1; n = 0; blank = 0; next }
+    on && /^## / { flush() }
+    on { if (NF) { if (n) for (i = 0; i < blank; i++) buf[++n] = ""; blank = 0; buf[++n] = $0 } else blank++; next }
+    { print }
+    END { if (on) flush(); else if (!done) { print ""; print h; print ""; print add } }' "$1" > "$tmp" &&
+    cat "$tmp" > "$1"
+  st=$?; rm -f "$tmp"; return $st
+}
+
+cmd_note() {
+  scope=branch
+  case ${1:-} in
+    --repo) scope=repo; shift ;;
+    --all) scope=all; shift ;;
+    -h|--help|help|"") die 'usage: trailkeep note [--repo|--all] "what and why"' ;;
+  esac
+  [ $# -ge 1 ] || die 'usage: trailkeep note [--repo|--all] "what and why"'
+  text=$(printf '%s' "$*" | one_line)
+  [ -n "$text" ] || die "note: empty text"
+  case $scope in
+    branch)
+      need_repo; need_branch
+      f=$(effort_path "$KEY" "$BRANCH")
+      if [ ! -e "$f" ]; then
+        # Notes only: no empty Goal/Plan to inject; `trailkeep new` adds them.
+        kind=branch; [ -n "${TRAILKEEP_EFFORT:-}" ] && kind=named
+        ensure_effort_dir
+        printf '# %s\n\nBranch: %s · Repo: %s · Kind: %s · Created: %s\n\n## Decisions and dead ends\n\n' \
+          "$BRANCH" "$BRANCH" "$KEY" "$kind" "$(today)" > "$f" || die "could not write $f"
+        remember_repo
+      fi
+      append_to_section "$f" "Decisions and dead ends" "- $(today): $text" || die "could not write $f"
+      say "Noted for branch $BRANCH ($f)." ;;
+    repo)
+      need_repo
+      f=$(notes_path "$KEY")
+      { mkdir -p "$(dirname "$f")" && { [ -e "$f" ] || printf '# Private notes: %s\n\n' "$KEY" > "$f"; } &&
+        printf -- '- %s: %s\n' "$(today)" "$text" >> "$f"; } 2>/dev/null ||
+        die "could not write $f (a sandbox may block it; use a branch note instead)"
+      remember_repo
+      say "Noted for this repo ($(tilde "$f"))." ;;
+    all)
+      # Not ~/.agents/AGENTS.md: that file is yours, and agents only propose changes to it.
+      { mkdir -p "$(dirname "$GLOBAL_NOTES")" && printf -- '- %s: %s\n' "$(today)" "$text" >> "$GLOBAL_NOTES"; } 2>/dev/null ||
+        die "could not write $GLOBAL_NOTES (a sandbox may block it; ask the user to add it)"
+      say "Noted for every repo ($(tilde "$GLOBAL_NOTES"))." ;;
+  esac
+}
+
 cmd_path() {
   need_repo
   case ${1:-} in
@@ -1412,6 +1491,9 @@ Setup
 
 Per repo / branch (run inside a git repo)
   new               create the effort file for the current branch
+  note [--repo|--all] TEXT
+                    record a decision, rule or dead end: for this branch (default),
+                    the whole repo, or every repo
   show              print what agents get at session start here
   edit              open the effort file in \$EDITOR
   path [--notes|--repo|--dir]
@@ -1439,6 +1521,7 @@ case $cmd in
   doctor) cmd_doctor "$@" ;;
   verify) cmd_verify "$@" ;;
   new) cmd_new "$@" ;;
+  note) cmd_note "$@" ;;
   show) cmd_show "$@" ;;
   edit) cmd_edit "$@" ;;
   path) cmd_path "$@" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trailkeep/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared instructions, per-branch task context and a decision log for Claude Code, Codex CLI and GitHub Copilot CLI. POSIX sh + git.",
   "keywords": [
     "claude-code",

package/skills/effort/SKILL.md

@@ -25,7 +25,8 @@ directly with your file tools.
 - Add one line under **Progress** per session: `YYYY-MM-DD: what changed, what's next`.
 - Record decisions with their reason under **Decisions and dead ends**, one
   line each. Start a line with `Dead end:` for an approach that failed, and say
-  why, so no later session retries it.
+  why, so no later session retries it. `trailkeep note "<what and why>"` does
+  this in one step, and works before an effort file exists.
 - Keep the file under about 150 lines: fold old Progress lines into one summary line.
 
 Every new Decisions and Progress line is copied to the repo's append-only