{"id":50454347,"url":"https://github.com/benslimanh/claudestate","last_synced_at":"2026-06-01T01:30:51.616Z","repository":{"id":344700114,"uuid":"1182754315","full_name":"benslimanh/claudestate","owner":"benslimanh","description":"Token optimization.","archived":false,"fork":false,"pushed_at":"2026-03-16T00:52:28.000Z","size":32,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-16T10:51:18.695Z","etag":null,"topics":["agentic-engineering","ai","ai-agent","ai-agents","ai-memory","anthropic","api","claude","claude-ai","claude-code","claude-code-plugin","claude-skills","llm-tools","machine-learning","python","rust","tokenization","trending","vibe-coding","vscode"],"latest_commit_sha":null,"homepage":"","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/benslimanh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-03-15T23:19:57.000Z","updated_at":"2026-03-16T00:52:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/benslimanh/claudestate","commit_stats":null,"previous_names":["benslimanh/claudestate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/benslimanh/claudestate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benslimanh%2Fclaudestate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benslimanh%2Fclaudestate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benslimanh%2Fclaudestate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benslimanh%2Fclaudestate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benslimanh","download_url":"https://codeload.github.com/benslimanh/claudestate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benslimanh%2Fclaudestate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33756575,"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-05-31T02:00:06.040Z","response_time":95,"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":["agentic-engineering","ai","ai-agent","ai-agents","ai-memory","anthropic","api","claude","claude-ai","claude-code","claude-code-plugin","claude-skills","llm-tools","machine-learning","python","rust","tokenization","trending","vibe-coding","vscode"],"created_at":"2026-06-01T01:30:50.648Z","updated_at":"2026-06-01T01:30:51.610Z","avatar_url":"https://github.com/benslimanh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ClaudeState\n\n**Persistent memory layer for vibe coding with Claude Code.**\n\n[![PyPI](https://img.shields.io/pypi/v/claudestate)](https://pypi.org/project/claudestate/)\n[![Python](https://img.shields.io/pypi/pyversions/claudestate)](https://pypi.org/project/claudestate/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Tests](https://github.com/benslimanh/claudestate/actions/workflows/test.yml/badge.svg)](https://github.com/benslimanh/claudestate/actions)\n\n---\n\n## Why ClaudeState\n\nClaudeState keeps your project plan outside the model's short-term context so Claude can resume work without losing direction.\n\n- Keep one source of truth in `STATE.md`\n- Reduce wasted context loading each session\n- Track blockers and progress in a way AI can reliably follow\n\n## 30-Second Demo\n\n```bash\npipx install claudestate\ncd my-project\nclaudestate init --name \"my-project\" --goal \"Ship MVP fast\"\nclaudestate sync\nclaudestate checkpoint \"Initialise repository structure\"\n```\n\n## Vibe Coding Workflow\n\nUse this loop every session:\n\n1. `claudestate sync` to get the current briefing.\n2. Ask Claude to continue from `STATE.md`.\n3. Implement the task in small chunks.\n4. `claudestate checkpoint \"task\"` when done.\n5. Repeat.\n\nThis keeps coding momentum high while preventing context drift.\n\n---\n\n## The Problem\n\nWhen using AI coding assistants (Claude Code, Cursor, Aider) on real projects, three failure modes appear consistently:\n\n- **Token exhaustion** — the model rereads thousands of lines of code each session just to reconstruct where work left off\n- **Context loss** — after a long session, the model loses awareness of the original architecture and makes conflicting changes\n- **Development loops** — the model rewrites the same function repeatedly without converging on a solution\n\nEach session starts from zero. There is no memory of what was decided, what was completed, or what failed.\n\n## The Solution\n\nClaudeState introduces a single structured file — `STATE.md` — maintained at the project root. It acts as the project's external long-term memory: a phase-by-phase roadmap with task checklists, an architecture diagram, a token budget log, and a blocker registry.\n\nInstead of reloading the entire codebase, the model reads this one file and knows exactly where to begin.\n\n```\nclaudestate sync        # session briefing: what was done, what is next\nclaudestate context     # which files to load for the current task\nclaudestate checkpoint  # mark a task complete and commit to git\nclaudestate loop-check  # detect repetitive commit patterns\n```\n\n---\n\n## Features\n\n| Feature | Description |\n|---|---|\n| **Master Plan** | `STATE.md` with phases, task checklists, and current status |\n| **Lazy Context Loading** | Per-task file recommendations — load only what the current task needs |\n| **Auto Checkpointing** | Completing a task triggers a labelled `git commit` automatically |\n| **Live Architecture** | Mermaid.js diagram updated by the AI as the project structure evolves |\n| **Loop Detection** | Analyses git history for repetitive patterns and logs a blocker |\n| **Session Sync** | One command produces a concise briefing of project status |\n| **CLAUDE.md Integration** | Syncs a compact summary into `CLAUDE.md`, the file Claude Code reads natively at session start |\n\n---\n\n## Installation\n\n```bash\npip install claudestate\n```\n\nUsing [pipx](https://pipx.pypa.io/) for global installation (recommended):\n\n```bash\npipx install claudestate\n```\n\nSet your Anthropic API key:\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n\u003e **Offline mode:** `init`, `status`, `checkpoint`, and `blocker` work without an API key. `sync`, `context`, `loop-check`, and `arch-update` require one.\n\n---\n\n## Quick Start\n\n```bash\ncd my-project\n\n# Generate STATE.md — Claude writes the initial roadmap\nclaudestate init --name \"my-project\" --goal \"Build a REST API in Go\"\n\n# Print the current task checklist\nclaudestate status\n\n# Get a session briefing\nclaudestate sync\n\n# Ask which files to load for the next task\nclaudestate context\n\n# Mark a task complete and commit\nclaudestate checkpoint \"Initialise repository structure\"\n\n# Log a blocker\nclaudestate blocker \"Postgres connection fails in Docker on Apple Silicon\"\n\n# Check for development loops\nclaudestate loop-check\n\n# Regenerate the architecture diagram after a refactor\nclaudestate arch-update\n```\n\n---\n\n## Command Reference\n\n```\nclaudestate init          Generate STATE.md (AI-generated or offline template)\nclaudestate sync          Session briefing from Claude\nclaudestate status        Print task checklist — no API call required\nclaudestate checkpoint    Mark a task complete and create a git commit\nclaudestate blocker       Log a blocker to STATE.md\nclaudestate context       Recommend files to load for the current task\nclaudestate loop-check    Detect development loops from git history\nclaudestate arch-update   Regenerate the Architecture diagram\n```\n\nAll commands accept `--api-key` or read from `ANTHROPIC_API_KEY`.\nThe short alias `cs` is also available (e.g. `cs sync`).\n\n---\n\n## STATE.md Format\n\n```markdown\n# rust-json-parser — State File\n\n| Field        | Value                           |\n|--------------|---------------------------------|\n| Goal         | Zero-copy JSON parser with SIMD |\n| Language     | Rust                            |\n| Last Updated | 2025-01-22 14:30                |\n\n## Current Status\nActive Phase: Phase 2 — Core Parser\n\n## Roadmap\n\n### Phase 1 — Setup\n- [x] Initialise Cargo workspace\n- [x] CI with GitHub Actions\n\n### Phase 2 — Core Parser\n- [x] Lexer: tokenise JSON bytes\n- [ ] Parser: recursive descent        \u003c- active task\n- [ ] Zero-copy string slices\n\n## Architecture\n(Mermaid.js diagram — updated by `claudestate arch-update`)\n\n## Token Budget\n| Session    | Tokens | Task                     |\n|---|---|---|\n| 2025-01-22 | ~900   | Loaded src/lexer.rs only |\n\n## Blockers\n(none)\n```\n\n---\n\n## How Lazy Context Loading Works\n\nWithout ClaudeState, Claude loads the entire repository each session.\n\nWith ClaudeState:\n\n```bash\n$ claudestate context\nTask: Zero-copy string slices\n\nRelevant files:\n  src/parser.rs\n  src/types.rs\n  tests/string_tests.rs\n```\n\nThree files are loaded instead of forty. On a medium-sized project, this reduces token consumption by 60-80% per session.\n\n---\n\n## Language Support\n\nClaudeState detects the primary language from the repository structure and adjusts the initial roadmap accordingly. Detection is supported for:\n\n| Language   | Indicators |\n|---|---|\n| Python     | `*.py`, `pyproject.toml`, `setup.py` |\n| Rust       | `Cargo.toml`, `*.rs` |\n| Go         | `go.mod`, `*.go` |\n| JavaScript | `package.json`, `*.js` |\n| TypeScript | `tsconfig.json`, `*.ts` |\n| Solidity   | `hardhat.config.*`, `*.sol` |\n\nAny language is supported — detection determines the initial template only.\n\n---\n\n## Claude Code Hook\n\nRegister the session hook to have `CLAUDE.md` updated automatically before every Claude Code tool call:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"python3 claudestate-hook.py\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nAdd this to `~/.claude/settings.json`. A ready-to-use template is at `docs/claude-settings-template.json`.\n\nWith the hook active, Claude Code reads the current task, branch, and last commit at the start of every session without any manual prompting.\n\n---\n\n## CLAUDE.md Integration\n\nAfter each `checkpoint` or `arch-update`, ClaudeState writes a compact summary to `CLAUDE.md` — the file Claude Code loads natively at context start:\n\n```markdown\n# ClaudeState — Session Context\n\n**Branch:** main\n**Progress:** 7/12 tasks (58%)\n\n## Start Here\n\n- [ ] Parser: recursive descent for objects/arrays\n- [ ] Zero-copy string slices\n- [ ] Error types with byte-offset reporting\n```\n\nThe injected context stays under approximately 400 tokens.\n\n---\n\n## Companion Tools\n\nFor integration with non-Python build systems:\n\n| Tool | Language | Build |\n|---|---|---|\n| `claudestate` | Python CLI | `pip install claudestate` |\n| `claudestate-hook.py` | Python | drop-in Claude Code hook |\n| `go-companion/claudestate-go.go` | Go | `go build -o claudestate-go` |\n| `rust-companion/` | Rust | `cargo build --release` |\n\nThe Go and Rust companions read `STATE.md` and output JSON, suitable for Makefiles, CI pipelines, and `cargo` build scripts.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/benslimanh/claudestate\ncd claudestate\npip install -e \".[dev]\"\npytest\n```\n\nPlease open an issue before submitting a large pull request.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenslimanh%2Fclaudestate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenslimanh%2Fclaudestate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenslimanh%2Fclaudestate/lists"}