A persistent alignment score between you and Claude — visible in your statusline, queryable on demand, with study recommendations born from your own friction points.
⚡ Opus 4.7 │ 📁 ~/myproject │ 🌿 main │ ⏱ 12m │ 🔗 Sync: 88% 🟢 ↗ clean: refactored payment math
└──────────── added by claude-sync ────────────┘
This grew out of a single coaching agreement between me and Claude during a long session: every time we burn 2+ turns because of an ambiguous prompt, close with a "this is the prompt that would have nailed it on the first try" block, and track how aligned we are over time. It works for me. Take it if our way of working resonates with yours, fork it if it almost does, ignore it if it doesn't.
No warranty, no support timeline, MIT license.
Three small pieces that work together:
| Piece | What it does |
|---|---|
| A Claude Code skill | Activates when a task closes with friction. Asks Claude to add a structured coaching block — the "ideal prompt" that would have avoided the back-and-forth, plus a reusable template for similar future tasks. |
| A sync score | Persistent ~/.claude/sync_state.json that tracks every close: clean / coaching / loop1-3 / bug / reset. Score in [0, 100], recoverable, honestly heuristic. |
| A statusline wrapper | Wraps your existing Claude Code statusline and appends 🔗 Sync: NN% 🟢 ↗ <last event>. Doesn't replace your statusline — extends it. |
After Claude finishes a task that took 3 corrections to get right:
## Why we looped 3 times
| What you said | What I assumed | What you meant |
|---------------------|-----------------------------------|---------------------------------------------|
| "center this" | center within its grid column | center in the parent card, aligned to truck |
| "move it left" | flush to the column start | not stuck against the Detail button |
| "midpoint under …" | (finally clear) | ✓ |
## The ideal prompt would have been
> "I want the horizontal center of the stepper to be on the same vertical
> axis as the truck icon in the route card above. Trace a line down from
> the truck — it must hit the midpoint between 'Picked up' and 'In transit'."
Why this works:
- Identifies the two elements to align (truck above, stepper below)
- Specifies the relation (same vertical axis)
- Defines the anchor point (midpoint between steps 2 and 3)
- Gives a verifiable mental image
## Reusable template
For "anchor element A to element B" UI requests, use:
> "I want [A] aligned [vertically|horizontally] with [B] using
> [the center|the left edge|the first icon] as the anchor."And then in your statusline, the next turn:
🔗 Sync: 78% 🟡 ↘ loop3: ui alignment without visual reference
git clone https://github.com/jsry80/claude-sync.git
cd claude-sync
./install.shRequirements: jq, bash, Claude Code.
That's it. The installer is idempotent — re-run it after upgrades.
The skill auto-triggers on phrases like:
- "What is my sync?" → quick status line
- "How did this session go?" → session summary with counts
- "Give me recommendations" → analysis: friction domains, recurring vague vocabulary, study resources
- "Show history" / "Show UI history" → filtered table
Behind the scenes, Claude calls ~/.claude/scripts/sync_report.sh <mode> and reformats the output for you. You can also call it directly from your shell.
Example recommendation output (real session, lightly redacted):
🔗 Análisis y recomendaciones
Estado: 78% 🟡 ↘
━━ Domains where we struggled ━━
· ui: 3 loops, Δ -20
· math: 1 loops, Δ -5
━━ Recurring ambiguity patterns ━━
· no_reference: 2 times
· no_unit: 1 times
━━ Vague vocabulary observed ━━
· "center": 3 times — suggests anchoring it concretely before use
━━ Suggested study ━━
· [css-grid-fr]
CSS Grid `1fr` vs `minmax(0, 1fr)` vs `auto`
📚 https://css-tricks.com/snippets/css/complete-guide-grid/
- fr unit
- minmax(0, 1fr) to allow shrinking
- 1fr auto 1fr to center middle column
| Event | Δ | When |
|---|---|---|
clean |
+5 | Closed a task with zero corrections |
coaching |
+3 | Closed with the full coaching block above |
loop1 |
−5 | 1 minor clarification needed |
loop2 |
−10 | 2 corrections |
loop3 |
−15 | 3+ corrections, real friction |
bug |
−8 | Claude shipped a known-repeated bug from its memory |
reset |
100 | "Fresh start, please" |
Clamped to [0, 100]. Honest, heuristic, designed to be recoverable — every loop is a chance to ship a coaching block worth +3.
The skill ships with prompt templates for seven domains. Each gives the typical ambiguous prompt, what users usually mean, and the structured form that closes the gap:
| Domain | Example fix |
|---|---|
| UI / UX | "center this" → "align [A] with [B] using [anchor] as the reference" |
| DB / SQL | "update X" → "UPDATE [table] SET [col]=[val] WHERE [filter]; dry-run first, expect ~N rows" |
| Math / Financial | "calculate the total" → "Total = Σ items.[field] with Decimal(14,2), HALF_EVEN rounding, in USD" |
| Debugging | "doesn't work" → "I did X, expected Y, got Z. Logs: [...]. Commit: [sha]" |
| Refactor | "clean this up" → "Refactor [scope]; preserve [invariant]; existing tests pass unchanged" |
| Mass data | "delete the old ones" → "DELETE WHERE created_at < [exact date]; COUNT first; idempotent; backup?" |
| Performance | "optimize" → "Reduce [op] from [X]ms to ≤[Y]ms p95 without changing the output" |
See skills/prompt-quality-coaching/SKILL.md for the full table.
Not for surveillance — for a mutual nudge. When the statusline shows 🟢 88%, both Claude and I know we're in a good groove. When it drops to 🟠 65%, that's a signal to pause and ask "what's been costing us alignment lately?" — and the recommend mode answers literally that.
The score has zero authority over what Claude does. It's a thermometer, not a thermostat.
~/.claude/sync_resources.json is the brain of the recommendation engine. Each entry is a tech_gap key mapped to a study resource:
"css-grid-fr": {
"title": "CSS Grid `1fr` vs `minmax(0, 1fr)` vs `auto`",
"url": "https://css-tricks.com/snippets/css/complete-guide-grid/",
"key_concepts": ["fr unit", "minmax(0, 1fr) to allow shrinking", ...]
}When Claude logs a loop with --tech css-grid-fr, the next recommend surfaces this resource. Add your own entries as new gaps appear in your own usage — keep them tight, real URLs only.
PRs welcome to expand the seed catalog with high-quality, language-agnostic resources.
┌─────────────────────────────────────────────────────────────────┐
│ YOUR CLAUDE CODE SESSION │
│ │
│ You ask something → Claude works → Claude closes │
│ │ │
│ ▼ │
│ (if 2+ loops or coaching applicable) │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ Skill: prompt-quality-coaching │ │
│ │ • Diagnoses the loops │ │
│ │ • Writes the ideal prompt │ │
│ │ • Calls update_sync.sh with metadata │ │
│ └────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ ~/.claude/sync_state.json (persisted) │ │
│ │ • score, trend, history[] │ │
│ │ • per-event: domain, pattern, vocab, tech │ │
│ └────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
│ │ statusline │ │ sync_report.sh │ │ sync_resources│ │
│ │ wrapper │ │ (queries) │ │ .json (catalog│ │
│ │ shows badge │ │ now/session/task │ │ of tech gaps) │ │
│ │ │ │ /history/recom. │ │ │ │
│ └─────────────────┘ └──────────────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────────────────┘
- Honesty over objectivity. I (Claude) judge each close myself. If I'm wrong about a
loop2that you think was aloop1, just tell me and I'll fix it. sync_state.jsonis local. Nothing leaves your machine. The score is for you, not for Anthropic.- The recommend engine only knows what I tag. If I forget to pass
--domainor--techon a loop, the recommendation is poorer. The skill explicitly tells me to log these every time. - Heuristics, not magic. The score formulae (+5 / -10 / etc.) are tuned by intuition, not by data. Adjust to taste in
scripts/update_sync.sh. - Bash + jq dependency. macOS and Linux only out of the box. Windows users: WSL.
- Not a model evaluator. It doesn't measure Claude's quality — it measures our shared alignment.
- Not a productivity gamification thing. The score doesn't unlock anything, can't be shared/posted, and resets whenever you want.
- Not a replacement for memory/notes. Use Claude's memory features for facts; use this for working-style alignment.
Issues and PRs welcome. The two highest-value contributions are:
- New tech_gap entries in
sync_resources.jsonfor domains I missed. - New domain templates in
skills/prompt-quality-coaching/SKILL.mdfor prompt patterns you've found ambiguous in your own work.
Keep the tone honest and the URLs real.
- The skill itself was born from one specific conversation about UI alignment that took 3 turns to converge. The realization "we could have closed this in one turn if I had said X" was the seed.
- The statusline base used in the demo is pradeeppeddineni/claude-statusline — the wrapper extends, doesn't replace.
MIT — see LICENSE.