{"id":50801792,"url":"https://github.com/goldenwo/claude-state-drift","last_synced_at":"2026-06-12T21:01:12.937Z","repository":{"id":364360463,"uuid":"1265684718","full_name":"goldenwo/claude-state-drift","owner":"goldenwo","description":"State-tracking + drift-mitigation plugin for Claude Code — keeps long agent sessions anchored to your project's objective. /plugin marketplace add goldenwo/claude-state-drift","archived":false,"fork":false,"pushed_at":"2026-06-12T18:33:00.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T19:17:55.599Z","etag":null,"topics":["claude-code","claude-code-plugin","drift-mitigation","state-tracking"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goldenwo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T02:00:43.000Z","updated_at":"2026-06-12T18:27:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/goldenwo/claude-state-drift","commit_stats":null,"previous_names":["goldenwo/claude-state-drift"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/goldenwo/claude-state-drift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenwo%2Fclaude-state-drift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenwo%2Fclaude-state-drift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenwo%2Fclaude-state-drift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenwo%2Fclaude-state-drift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goldenwo","download_url":"https://codeload.github.com/goldenwo/claude-state-drift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenwo%2Fclaude-state-drift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34262157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugin","drift-mitigation","state-tracking"],"created_at":"2026-06-12T21:00:51.236Z","updated_at":"2026-06-12T21:01:12.927Z","avatar_url":"https://github.com/goldenwo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-state-drift\n\n[![ci](https://github.com/goldenwo/claude-state-drift/actions/workflows/ci.yml/badge.svg)](https://github.com/goldenwo/claude-state-drift/actions/workflows/ci.yml)\n[![version](https://img.shields.io/badge/version-v0.1.7-blue)](https://github.com/goldenwo/claude-state-drift/releases)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nState-tracking and drift-mitigation for [Claude Code](https://docs.claude.com/en/docs/claude-code).\nEvery session opens with your project's actual state — not a cold start:\n\n```\n=== WHERE YOU ARE ===\nProject: my-api\nVersion: 1.4.0 | Objective: Ship the v2 billing pipeline with usage-based invoicing\nFocus:   Webhook retry queue done; now wiring the invoice-preview endpoint\nIn progress: invoice-preview-endpoint\nDeferred:    csv-export (until billing v2 ships)\nRecent: 3 commits today, last: \"Add retry backoff to webhook queue\"\n```\n\nLong agent sessions measurably lose the plot: models retrieve worst from the middle of\nlong inputs ([Liu et al., TACL 2024](https://arxiv.org/abs/2307.03172)), grow\nunreliable as inputs lengthen ([Chroma, 2025](https://www.trychroma.com/research/context-rot)),\nand drift from their goal as context grows ([Arike et al., 2025](https://arxiv.org/abs/2505.02709)).\n`claude-state-drift` keeps a small, human-readable `.claude/state.json` per project and\ncontinuously re-surfaces it so the goal never depends on what's still in context.\n\n## Highlights\n\n- **Orientation on every session start** — the \"WHERE YOU ARE\" block above, generated\n  from your project's real state.\n- **Drift checks while you work** — the objective and current focus are re-injected\n  every few prompts, so the goal never fully leaves context.\n- **Staleness nudges** — get flagged when `state.json` looks out of date relative to\n  recent work, or when a commit looks like it finished a deliverable.\n- **Zero workflow change** — all of the above is automatic, driven by hooks. You\n  never have to remember to invoke anything; the [commands](#commands) exist for\n  when you *want* manual control.\n\n## Install\n\n```\n/plugin marketplace add goldenwo/claude-state-drift\n/plugin install claude-state-drift\n```\n\nThen drop a starter `.claude/state.json` into your project — copy one from\n[SCHEMA.md](SCHEMA.md) — and start a session. Uninstall any time with\n`/plugin uninstall claude-state-drift`.\n\n## How it works\n\nFour hooks — all automatic — and three optional commands, all reading one file:\n\n```mermaid\nflowchart LR\n    S[(\".claude/state.json\")] --\u003e|SessionStart| O[\"WHERE YOU ARE\u003cbr/\u003eorientation block\"]\n    O --\u003e W[\"you + Claude work\"]\n    W --\u003e|\"every N prompts\"| F[\"focus-check\u003cbr/\u003ere-injects the objective\"]\n    F --\u003e W\n    W --\u003e|\"commit lands\"| C[\"state-track-commit\u003cbr/\u003espots deliverable transitions\"]\n    W --\u003e|\"session ends\"| Z[\"state-staleness\u003cbr/\u003eflags stale state\"]\n    C --\u003e U[\"update-state command\u003cbr/\u003ereviewed edit, never auto-writes\"]\n    Z --\u003e U\n    U --\u003e S\n```\n\n- A `SessionStart` hook prints the orientation block.\n- A `UserPromptSubmit` hook (`focus-check`) re-injects the objective on a cadence you\n  can tune per project (`.claude/hooks-config.json`).\n- A `Stop` hook flags stale state; a `PostToolUse` hook notices commits whose subject\n  suggests a deliverable transition and points you at the `update-state` command.\n- Everything is computed from local files and local git.\n\nNone of this needs you to do anything: install, drop in a `state.json`, and the\nhooks run on every session from then on. Claude also invokes the update and\nre-anchor skills on its own when it detects a finished deliverable or drift.\n\n## Commands\n\nFor when you want to check or change state deliberately rather than waiting for\na hook. Plugin commands are always namespaced in the Claude Code CLI — type\n`/claude-state-drift:` and tab-complete:\n\n| Command | What it does |\n|---|---|\n| `/claude-state-drift:where-am-i` | Print the orientation block on demand — objective, focus, deliverable statuses, recent commits. |\n| `/claude-state-drift:update-state` | Draft an update to `state.json` from recent work and show the diff. Never auto-writes — you approve every change. |\n| `/claude-state-drift:re-anchor` | Audit the current session against the objective and report alignment: on-track, mild drift, or significant drift. |\n\nOutside the CLI (e.g. the desktop app), typed plugin commands aren't supported —\njust ask in plain words (\"where am I?\", \"update the project state\", \"are we still\non track?\") and Claude invokes the matching skill.\n\n## With and without\n\nNo magic — just the difference between state that lives in a file and state that\nlives in a scrolling context window:\n\n| Moment | With claude-state-drift | Without |\n|---|---|---|\n| Session start | Orientation block from your real project state | Cold start; you re-explain or the agent re-derives |\n| 40 prompts in | Objective re-injected on a cadence; still in context | Goal relies on whatever survived context compaction |\n| After a milestone commit | Nudge to record the transition in `state.json` | Project state lives only in git archaeology |\n| Next week's session | Picks up exactly where the file says you left off | Reconstruction from memory and scrollback |\n\n## Built with itself\n\nThis plugin's own release pipeline was built while running the plugin — every\nsession opened by its orientation block, drift-checked by its own `focus-check`.\nThe receipts, as of June 2026: **50 deliverables tracked (49 shipped) and 69\ncommits across the six-phase milestone** that produced this repo, June 6–11 2026:\n\n```mermaid\ntimeline\n    title Six phases in six days — tracked in state.json the whole way\n    2026-06-06 : Curation build engine : Content transforms + gates\n    2026-06-07 : Emitted-cut validation : Clean-install acceptance\n    2026-06-10 : Public repo + regeneration-drift CI\n    2026-06-11 : v0.1.0 published\n```\n\nThat's heavy real-world use, not a controlled study — a measured with/without\ncomparison is planned, and this section will carry the results when they exist.\n\n## The `state.json` model\n\nThe whole system revolves around one file, `.claude/state.json`:\n\n- `objective` — the master vision; rarely changes.\n- `current_focus` — one sentence on what you're doing right now.\n- `deliverables[]` — units of work, each with a `status` (`done` / `in_progress` /\n  `deferred` / `blocked`).\n\nSee [SCHEMA.md](SCHEMA.md) for the full schema, a copy-paste starter file, and the\nper-project `.claude/hooks-config.json` knobs.\n\nThe plugin also bundles a few CLI tools, all on the Bash tool's `PATH` in any\nsession while the plugin is enabled — just ask Claude to run them:\n\n- `state-validate` — schema-check a `state.json` (exit `0` = valid).\n- `where-am-i` — print the orientation block on demand (`--history \u003cid\u003e` shows a\n  deliverable's transition log).\n- `state-history` — append an entry to the per-project transition log.\n- `workflows` — a cross-repo board: one row per project with a `state.json`\n  (walks `~/dev` by default; override with `$WORKFLOWS_ROOT`).\n\n## Requirements\n\n- Claude Code with plugin support.\n- `bash`, `git`, `jq`, and Python 3 (found automatically as `py`, `python3`, or\n  `python` — no configuration needed).\n- CI-verified on Linux and Windows (git-bash). macOS is expected to work (the hooks\n  are POSIX bash) but is not currently CI-covered.\n\n## Troubleshooting\n\n- **No orientation block at session start?** Your project has no `.claude/state.json`\n  (the plugin stays silent rather than nagging) or the file is invalid — ask Claude\n  to run `state-validate` (bundled, on the Bash `PATH` while the plugin is enabled).\n- **Focus-check fires too often / not often enough?** Set the cadence in\n  `.claude/hooks-config.json` — see [SCHEMA.md](SCHEMA.md).\n- **Does anything leave my machine?** No. All signals are computed from local files\n  and local git; there is no network access, and nothing is sent anywhere.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## About this repo\n\n**File issues here — they're read and acted on.** This repo is generated: every\nbyte is built from a pinned source commit (see `.build-provenance`) and verified\nbyte-for-byte by CI on every push. Fixes land in the source and ship in the next\nrelease, which is why pull requests can't be merged directly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldenwo%2Fclaude-state-drift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoldenwo%2Fclaude-state-drift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldenwo%2Fclaude-state-drift/lists"}