Skip to content

feat(tui): near-instant dashboard refresh via PostToolUse sentinel - #26

Merged
kinncj merged 4 commits into
kinncj:mainfrom
bernard-code-lab:feat/tui-refresh-sentinel
Sep 13, 2026
Merged

kinncj merged 4 commits into
kinncj:mainfrom
bernard-code-lab:feat/tui-refresh-sentinel

Conversation

@bernard-code-lab

@bernard-code-lab bernard-code-lab commented Sep 13, 2026 •

Copy link
Copy Markdown
Collaborator

What is this PR doing?

Harness hooks write .claude/state/.tui-refresh and the dashboard polls that signal at 400ms, so it reloads the moment a harness writes state instead of waiting out the 2s tick.

Type of change

  • Feature
  • Bug fix
  • Refactor
  • Docs
  • Spike

Story / Issue

Closes #15

All three harnesses

Harness Mechanism
Claude Code PostToolUse hooks — post-write.sh, post-bash.sh, 1 line each
OpenCode .opencode/plugins/tui-refresh.js on tool.execute.after, writing via node:fs so it costs no subprocess per tool call
Copilot hooks.toolCall registered in .github/copilot.json, filtered to phase == "after"

Correction on my earlier claim: I said Copilot had no post-tool hook. That was wrong — hooks.toolCall exists and works at the project level. It's wired here.

Notes

Poll, not fsnotify. A read gets the same result without a new direct dependency or inotify's watch limits — see the discussion on the issue.

tickMsg is untouched. My first attempt sped it up and made reload() conditional; TestGateClearNudgesHarness caught it, since tickMsg also drives the gate-clear nudge. The signal gets its own poll instead, so both existing cadences (2s local, 60s network) are unchanged and this is purely additive.

The signal includes file content, not just mtime. A bare touch collapses a burst of writes into one on filesystems with 1s mtime granularity — exactly the case this feature exists for.

Heads-up on template/.gitignore. The new line means maple update will flag .gitignore as Changed for already-initialised projects and overwrite it, since only Makefile gets the incremental patch (scaffold/update.go:70). Pre-existing behaviour — any edit to that file would do it — but worth knowing. Happy to open a separate issue for treating .gitignore as append-only.

Checklist

  • Tests added or updated — dashboard reload path, stale-signal baseline, plus structure tests that run the OpenCode plugin and drive the Copilot hook on both phases
  • All existing tests pass — bash tests/run_all.sh 6 suites / 0 failures; go test ./app/internal/... 219 passing across 17 packages
  • SDLC gates green
  • No secrets committed
  • shellcheck clean on modified shell files

The dashboard only saw harness writes on its 2s local tick. The PostToolUse
hooks now touch .claude/state/.tui-refresh, and the dashboard stats that
sentinel every 400ms and reloads the moment it moves.

A stat is cheap; reload() reads stories, sessions, tests, design and logs and
is not — so the sentinel gets its own poll instead of speeding up tickMsg,
which always reloads and also drives the gate-clear nudge. Both existing
cadences (2s local, 60s network) are untouched.

fsnotify would need a new dependency for the same result; a stat at 400ms is
already well under the perceptible threshold the issue asks for.

A sentinel left behind by an earlier session only establishes the baseline, so
opening the TUI in a stale worktree does not fire a spurious reload.

Closes kinncj#15

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

OpenCode and Copilot lack the hook registrations required by issue #15.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds sentinel-based dashboard refreshes while preserving existing polling cadences.

Changes:

  • Polls .tui-refresh every 400ms.
  • Updates Claude Code hooks to touch the sentinel.
  • Adds tests, ignore rules, and changelog documentation.
File summaries
File Description
app/internal/tui/dashboard/model.go Adds sentinel polling and reload handling.
app/internal/tui/dashboard/model_test.go Tests fresh and stale sentinels.
.claude/hooks/post-write.sh Signals refresh after writes.
.claude/hooks/post-bash.sh Signals refresh after commands.
template/.claude/hooks/post-write.sh Mirrors the write hook in scaffolds.
template/.claude/hooks/post-bash.sh Mirrors the Bash hook in scaffolds.
template/.gitignore Ignores the runtime sentinel.
CHANGELOG.md Documents the feature.
Review details
  • Files reviewed: 8/8 changed files
  • Comments generated: 1
  • Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread app/internal/tui/dashboard/model.go Resolved
The model was stat'ing .claude/state/.tui-refresh directly, against the Store
invariant in CLAUDE.md — it only worked because main.go passes state.NewFS("."),
so any other root silently never fired. The read moves to Store.RefreshSignal()
and the tests drive the fake store instead of chdir'ing into a temp dir.

The signal now includes file content, not just mtime: a bare touch collapses a
burst of hook writes into one on filesystems with 1s mtime granularity, which is
exactly the case this feature exists for.

Comments cut to the project style (why only, no multi-line docstrings). Adds the
.tui-refresh channel to the Shared State Protocol table, and drops the CHANGELOG
claim about OpenCode and Copilot — only the Claude Code hooks are wired.
Issue kinncj#15 asks for the signal on Claude Code, OpenCode and Copilot. OpenCode
exposes tool.execute.after through its plugin API, so a plugin in
.opencode/plugins/ writes the same sentinel the Claude Code hooks do. It writes
with node:fs rather than shelling out, so it costs no subprocess per tool call.

Copilot has no post-tool hook to attach to, so that third of the issue stays
open — this covers the two harnesses that can carry the signal.

test_structure.sh now asserts both harnesses target the same sentinel, and
actually runs the plugin to prove it writes a value that changes per call —
a grep alone would pass on a plugin that throws.
Completes the three harnesses issue kinncj#15 asks for. Copilot CLI does expose a
post-tool hook — `hooks.toolCall` in settings.json, project-level via
.github/copilot.json — and its stdin carries a `phase` field, so the hook fires
on both sides of the call and the before phase is dropped.

The structure test drives the script on both phases: a hook that signalled on
`before` would reload the dashboard ahead of the change it is meant to show.
@kinncj
kinncj merged commit aa47ddb into kinncj:main Sep 13, 2026
14 checks passed
@bernard-code-lab
bernard-code-lab deleted the feat/tui-refresh-sentinel branch September 13, 2026 21:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PostToolUse hooks for near-instant TUI refresh

3 participants