@trailkeep/cli 0.3.2 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailkeep",
-  "version": "0.3.2",
+  "version": "0.5.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)
 
@@ -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,8 @@ 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`, and to pick the scope: this branch, the whole repo (`--repo`) or every repo (`--all`). It doesn't wait for anyone to decide the task "spans sessions". Turn it off with `TRAILKEEP_HINT=0`. |
+| You're on a branch with no notes yet | The last few decisions recorded on other branches are shown, each labelled with its branch, so repo-wide rules saved on one branch aren't lost on the next. Once the branch has its own notes, only those are shown. |
 | 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 +78,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 +106,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 +134,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.

package/bin/trailkeep

@@ -5,7 +5,7 @@
 
 set -u
 
-VERSION="0.3.2"
+VERSION="0.5.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,27 @@ 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 with its reason. Pick the scope: `trailkeep note --repo "..."` for a rule about this codebase that holds on every branch, `trailkeep note "..."` for something specific to this branch'"'"'s task, `trailkeep note --all "..."` for a personal preference in every repo. Notes are shown at the start of the next session.'
+}
+
+# Decisions recorded on other branches, newest first: effort files in this
+# worktree (their latest lines may not be in the log yet), then the log.
+other_decisions() { # CURRENT_BRANCH KEY -> up to 5 lines "- (branch) text"
+  {
+    for f in $(ls -t "$(effort_dir)"/*.md 2>/dev/null); do
+      br=$(effort_branch "$f"); [ -n "$br" ] && [ "$br" != "$1" ] || continue
+      section "$f" "Decisions and dead ends" |
+        awk -v br="$br" -v tab="$TAB" 'NF { l = $0; sub(/^[[:space:]]*[-*][[:space:]]*/, "", l); a[++n] = br tab l } END { for (i = n; i > 0; i--) print a[i] }'
+    done
+    log_events "$2" | awk -F "$TAB" -v OFS="$TAB" -v b="$1" '($3 == "decision" || $3 == "dead-end") && $4 != b { print $4, $7 }'
+  } | awk -F "$TAB" '!seen[$2]++ && $2 !~ /^\[[ xX]\]/ {
+        t = $2; if (length(t) > 240) t = substr(t, 1, 237) "..."
+        printf "- (%s) %s\n", $1, t; if (++c >= 5) exit }'
+}
+
 build_context() {
   in_repo || return 0
   KEY=$(repo_key) || return 0
@@ -238,18 +260,34 @@ build_context() {
   [ -n "$effort" ] && [ -s "$effort" ] && has_effort=1
 
   budget=$MAX_CHARS
+  if [ -s "$GLOBAL_NOTES" ]; then
+    piece "trailkeep: your preferences for every repo; apply them unless the user says otherwise" "$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))"
+    piece "trailkeep: rules and notes for this repository; follow them unless the user says otherwise" "$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: decisions recorded for branch $b; follow them unless the user says otherwise" "$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 [ "$has_effort" -eq 0 ] && [ -n "$effort" ]; then
+    od=$(other_decisions "$b" "$KEY" 2>/dev/null)
+    if [ -n "$od" ]; then
+      printf 'trailkeep: branch %s has no notes yet. Recent decisions from other branches of this repo, newest first. Rules about the codebase as a whole probably hold here too; ones tied to another branch'"'"'s task may not:\n%s\n\n' "$b" "$od"
+    fi
+  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 +429,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 +597,80 @@ 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"'
+  # drop a date the agent wrote itself; the note gets today's date below
+  text=$(printf '%s' "$*" | one_line | sed 's/^[-* ]*[0-9]\{4\}-[0-9][0-9]-[0-9][0-9]:\{0,1\}[[:space:]]*//')
+  [ -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 +1513,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 +1543,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.2",
+  "version": "0.5.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