puffer-feed

One line connects everyone to ThePuffer build tracker. Hermes, Claude Code, Claude Desktop, a CI job, a git hook — anything — can push a progress update to the tracker by calling one tool (or one shell command). No more hand-editing data.json.

It's an MCP server + a CLI + an opt-in hook, all funneling through one locked, git-safe write-core so concurrent writers can never clobber each other (the exact bug that bit us when two agents wrote data.json at once).

puffer-feed/
├── src/write-core.mjs   ← the ONLY thing that mutates data.json + pushes (lock + rebase + atomic write)
├── src/secrets.mjs      ← rejects secrets / internal hosts before they hit the public page
├── mcp-server.mjs       ← stdio MCP server (6 tools) — add one line to any MCP client
├── bin/puffer.mjs       ← CLI for non-MCP callers (CI, cron, git hooks, shell)
├── hooks/puffer-autofeed.mjs ← opt-in Claude Code Stop hook (off by default)
└── test-core.mjs        ← concurrency regression test (npm test)

Mental model: logging IS publishing. A write goes live on the partner-facing site in ~15s. Keep it to one entry per BIG step, plain and non-technical — a business partner reads it, not engineers.

---

Install (once)

git clone https://github.com/ElSalvatore-sys/puffer-feed.git ~/Developer/puffer-feed
cd ~/Developer/puffer-feed && npm install

It writes to a local clone of the tracker repo. Point it there with PUFFER_DIR (defaults to ~/Developer/puffer-tracker). You need push rights on that repo.

git clone https://github.com/ElSalvatore-sys/puffer-tracker.git ~/Developer/puffer-tracker

---

Connect a client (the "one line")

Claude Code — ~/.claude.json (global mcpServers, or a project's mcpServers)

"puffer": {
  "command": "node",
  "args": ["/Users/you/Developer/puffer-feed/mcp-server.mjs"],
  "env": { "PUFFER_DIR": "/Users/you/Developer/puffer-tracker" }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json → mcpServers

(same block; restart Claude Desktop to load)

"puffer": {
  "command": "node",
  "args": ["/Users/you/Developer/puffer-feed/mcp-server.mjs"],
  "env": { "PUFFER_DIR": "/Users/you/Developer/puffer-tracker" }
}

Hermes — ~/.hermes/config.yaml under the existing mcp_servers:

mcp_servers:
  puffer:
    command: node
    args:
    - /Users/you/Developer/puffer-feed/mcp-server.mjs
    enabled: true
    env:
      PUFFER_DIR: /Users/you/Developer/puffer-tracker

(Hermes has mcp_reload_confirm: true — it asks you to approve the reload once.)

CLI / CI / cron / git hooks (no MCP)

cd ~/Developer/puffer-feed && npm link   # exposes `puffer` on PATH
PUFFER_DIR=~/Developer/puffer-tracker puffer log bloghead "Stripe payouts wired end to end"

Once connected, an agent just calls the tool: "log a step on bloghead: payments are live."

---

Tools (MCP) / commands (CLI)

Tool	What it does
log_step	Append one big-step entry. project, title required; detail/status/mins/progress/push/redact optional. 90% of usage.
get_recent	Read-only. Last n entries — call before logging to avoid duplicates.
list_projects	Read-only. Keys, names, phases, % and step counts.
set_project_field	Set phase / minor / roadmap (structural — gated, see below).
set_week_highlight	Replace the "This week" banner (gated).
add_audit_chapter	Append a narrative chapter to a project's audit (gated).

puffer log thebarapp "Digital menu module shipped" --detail "owner editor + public page" --mins 300 --status done --progress 86
puffer recent 10
puffer projects
puffer log dehgo "Drafted onboarding copy" --no-push    # commit locally, push on next call

Structural tools (set_project_field, set_week_highlight, add_audit_chapter) are off unless PUFFER_ALLOW_STRUCTURAL=1 — keep them to the owner's machine; everyone else just logs steps.

---

Auto-feed hook (opt-in, off by default)

hooks/puffer-autofeed.mjs is a Claude Code Stop hook that does nothing unless PUFFER_AUTOFEED=1 and the session explicitly staged a step via a sentinel (.puffer-pending JSON in the repo, or PUFFER_LOG="project|title|detail"). It never fires per-turn. To enable, add to ~/.claude/settings.json:

{ "hooks": { "Stop": [ { "hooks": [
  { "type": "command", "command": "PUFFER_AUTOFEED=1 PUFFER_DIR=/Users/you/Developer/puffer-tracker node /Users/you/Developer/puffer-feed/hooks/puffer-autofeed.mjs" }
] } ] } }

The core enforces an anti-spam guard on hook-fed entries (min meaningful title, dedupe, 1-per-project-per-20-min throttle). Recommended posture: leave it off and let the agent call log_step deliberately.

---

Auto-log rule (drop into your CLAUDE.md)

The most reliable "hands-free" path isn't a dumb trigger — it's a one-paragraph rule that tells the agent to call log_step at every big step. The canonical copy lives in CLAUDE-RULE.md — paste it into your global ~/.claude/CLAUDE.md (covers every project at once) and/or each project's CLAUDE.md. It defines what counts as a "big step", the project keys, and the partner-facing writing style.

---

Why one locked write-core

Every writer — MCP, CLI, hook, even the screenshot agent (commitPaths()) — funnels through withLock() → fetch → rebase → derive id AFTER rebase → validate → atomic write → git add data.json (never -A) → commit → push (rebuild + retry on non-fast-forward, never force-push). That:

• serializes concurrent writers via an atomic link()-based lockfile in .git/ (pid-liveness stale-steal, ownership-checked release) — fixes the clobber bug directly;
• derives the new id after rebase so two writers never pick the same id;
• writes atomically (tmp + fsync + reparse + rename) so a reader never sees a torn file;
• pathspec-scoped commit (git commit -- data.json) so a pre-staged file in your tracker clone can never be swept into the public push;
• scans every published field for secret shapes before publishing (reject by default — rotate, don't "edit", since git history is permanent). Add your own internal hosts/IPs to block with PUFFER_INFRA_HOSTS="10.0.0.5,api.internal.example" (kept out of this repo);
• returns a truthful result — callers say "live in ~15s" only when pushed === true.

Run the regression test (spawns 8 parallel writers against a throwaway local clone):

npm test

License

MIT © 2026 ThePuffer / EA Solutions