{"id":50084221,"url":"https://github.com/dioptx/weft","last_synced_at":"2026-06-17T14:04:11.024Z","repository":{"id":363279175,"uuid":"1203963793","full_name":"dioptx/weft","owner":"dioptx","description":"Deterministic workflow tracking for Claude Code — smart skills, template management, dashboard auto-refresh","archived":false,"fork":false,"pushed_at":"2026-05-12T17:50:09.000Z","size":678,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-08T09:04:29.060Z","etag":null,"topics":["claude-code","claude-plugin","developer-tools","event-sourcing","workflow"],"latest_commit_sha":null,"homepage":"https://github.com/dioptx/weft","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/dioptx.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-04-07T14:59:02.000Z","updated_at":"2026-06-08T03:56:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dioptx/weft","commit_stats":null,"previous_names":["dioptx/weft"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dioptx/weft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dioptx","download_url":"https://codeload.github.com/dioptx/weft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34451358,"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-17T02:00:05.408Z","response_time":127,"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-plugin","developer-tools","event-sourcing","workflow"],"created_at":"2026-05-22T18:00:36.857Z","updated_at":"2026-06-17T14:04:11.019Z","avatar_url":"https://github.com/dioptx.png","language":"Python","funding_links":[],"categories":["Plugins"],"sub_categories":["All Plugins"],"readme":"# weft\n\n**Deterministic workflow tracking for Claude Code — smart skills, template management, dashboard auto-refresh.**\n\n![weft pitch — agentic chain of skills with bounded loops + guards](docs/demos/pitch.gif)\n\nWeft turns ad-hoc agent sessions into auditable, event-sourced workflows. Define a template (plan → implement → verify, or an 11-step ticket-to-PR cycle), and weft enforces the order, blocks tools that violate the current step's guards, and refuses to let you `Stop` with steps still pending.\n\n## Why this exists\n\nMulti-step engineering work needs structure that survives compaction, retries, and the agent forgetting what step it's on. Weft solves three problems:\n\n- **Skills fire reliably** — `/wf-start`, `/wf-step`, `/wf-status` read state from disk, not memory.\n- **Templates apply consistently** — workflows live in JSON, version-controlled with your project.\n- **Hooks enforce the contract** — `PreToolUse`, `PreCompact`, and `Stop` block out-of-order actions or premature exits.\n\nState is an append-only event log under `.claude/weft/`, so every workflow is fully reconstructible.\n\n### Why not just use TODOs or Claude's task list?\n\nBuilt-in TODOs and ad-hoc checklists live in the agent's context window. They're advisory — the model can ignore them, lose them across compaction, or skip steps it judges unnecessary. They have no enforcement, no replay, no per-step guards. Weft is the opposite tradeoff: a small contract written to disk, enforced by hooks, with an event log you can audit after the fact. Use TODOs when \"the model probably remembers\" is good enough. Use weft when it isn't.\n\n## Requirements\n\n- **Python 3.10+** (stdlib only — no runtime dependencies)\n- **Claude Code** with plugin support\n- **macOS or Linux** (the dashboard uses `curses`; Windows is untested)\n\n## Quick Start\n\nWeft ships as a Claude Code plugin. Install via the marketplace:\n\n```\n/plugin marketplace add dioptx/weft\n/plugin install weft@dioptx-weft\n```\n\nOr, for development / hacking on weft itself:\n\n```bash\ngit clone https://github.com/dioptx/weft.git\nclaude --plugin-dir ./weft\n```\n\nThe plugin auto-registers four hooks (`SessionStart`, `PreToolUse`, `PreCompact`, `Stop`) and 11 skills via `.claude-plugin/plugin.json` and `hooks/hooks.json`. Restart Claude Code and the `/wf-*` commands become available.\n\n### First workflow\n\n```\n/wf-start generic        # plan → implement → verify\n/wf-status               # show current state\n/wf-step complete        # advance to the next step\n/wf-dashboard            # open the live TUI\n```\n\nRun `/wf-start` with no args for the guided template picker.\n\n![weft walkthrough — start, step, complete, audit](docs/demos/walkthrough.gif)\n\nSee [docs/demo.md](docs/demo.md) for an annotated end-to-end walkthrough, and [docs/demos/](docs/demos/) for the asciicasts and recording scripts behind every GIF in this README.\n\n## Compose your own workflow\n\nTemplates are JSON. You can author one inline and pipe it to `weft save-template` — no editor required, no scaffolder. The template lands in `.claude/weft/templates/` and is immediately available to `weft start`.\n\n![weft compose — heredoc → save-template → preview → start](docs/demos/compose.gif)\n\n```bash\ncat \u003e flow.json \u003c\u003c 'EOF'\n{\n  \"name\": \"site-audit\",\n  \"steps\": [\n    {\"name\": \"crawl\",  \"skill\": \"/perplexity\"},\n    {\"name\": \"review\", \"skill\": \"/staff-review\",\n     \"guards\": [{\"command_pattern\": \"git push\", \"message\": \"no push during review\"}]},\n    {\"name\": \"fix\",    \"skill\": \"/fix-polish\"},\n    {\"name\": \"verify\", \"loop_back_to\": \"review\", \"max_iterations\": 3,\n     \"exit_condition\": \"no high-severity findings\"}\n  ]\n}\nEOF\nweft save-template \u003c flow.json\nweft start site-audit\n```\n\nFor interactive composition based on what's in your current conversation, use `/wf-compose`.\n\n## Extend with your own skills\n\nWeft consumes Claude Code skills (`SKILL.md` files under `.claude/skills/`) as workflow steps. Drop a new skill in, reference it from a template via `skill: /\u003cname\u003e`, and weft picks it up.\n\n![weft extend — author SKILL.md, reference it from a template](docs/demos/extend.gif)\n\n```bash\nmkdir -p .claude/skills/site-audit\ncat \u003e .claude/skills/site-audit/SKILL.md \u003c\u003c 'EOF'\n---\nname: site-audit\ndescription: Crawl + audit a target site with lighthouse\nallowed-tools: [Bash, Read]\n---\n# Site Audit\nRun lighthouse against $URL, report findings.\nEOF\n\ncat \u003c\u003c'JSON' | weft save-template\n{\n  \"name\": \"audit-cycle\",\n  \"steps\": [\n    {\"name\": \"audit\", \"skill\": \"/site-audit\"},\n    {\"name\": \"fix\",   \"skill\": \"/fix-polish\"}\n  ]\n}\nJSON\n```\n\n## Features\n\n- **Event-sourced state machine** — append-only JSON log; rebuild state with `/wf-rebuild`\n- **Template system** — `generic` (3 steps) and `feature-workflow` (11 steps) bundled; add your own under `templates/` (project), `~/.weft/templates/` (user-global), or `WEFT_USER_TEMPLATES_DIR`\n- **Smart skills** — 11 slash commands (`wf-start`, `wf-step`, `wf-status`, `wf-abort`, `wf-preview`, `wf-rebuild`, `wf-dashboard`, `wf-new-template`, `wf-edit-template`, `wf-compose`, `ev-query`)\n- **Guard engine** — per-step `allowed-tools` and `blocked-commands` enforced via `PreToolUse` hook\n- **Stop gate** — refuses session exit while steps are incomplete (configurable via `on_fail: block|retry|skip`)\n- **Compaction-safe** — `PreCompact` hook writes a `context.md` projection so the next session resumes mid-workflow\n- **Live dashboard** — auto-refreshing TUI for monitoring active workflows\n- **Template management** — `/wf-new-template` and `/wf-edit-template` for creating and editing templates in-session\n\n## Auditable by design\n\nEvery workflow transition is an append-only event in `.claude/weft/events.jsonl`. The `state.json` snapshot is just a projection — delete it and weft will rebuild it from events alone.\n\n![weft audit — query events, raw jsonl, rebuild from log](docs/demos/audit.gif)\n\n```bash\nweft query                       # human-readable timeline\ntail -3 .claude/weft/events.jsonl  # raw structured events\nrm .claude/weft/state.json       # nuke the snapshot\nweft rebuild                     # reconstruct from events alone\n```\n\nUse `weft query --type wf.step_changed`, `--last 50`, or `--workflow \u003cid\u003e` to filter.\n\n## Repository Layout\n\n```\n.claude-plugin/   plugin.json — Claude Code plugin manifest\ncore/             Python event store, state machine, projections, CLI, dashboard\nhooks/            SessionStart / PreToolUse / PreCompact / Stop bash hooks + hooks.json\nskills/           11 SKILL.md files for the /wf-* and /ev-* slash commands\ntemplates/        generic.json, feature-workflow.json (workflow definitions)\ntests/            pytest suite covering event store, state machine, hooks, CLI, behaviors\n```\n\nThe Python core is dependency-free (stdlib only). The dashboard uses `curses`. Tests use `pytest`.\n\n## Custom templates\n\nWeft discovers templates from three locations, in order of precedence:\n\n| Tier | Path | Use for |\n|---|---|---|\n| Project-local | `\u003crepo\u003e/.claude/weft/templates/*.json` | Templates specific to one project, version-controlled with it |\n| User-global | `~/.weft/templates/*.json` (override with `WEFT_USER_TEMPLATES_DIR`) | Personal templates available across every project |\n| Bundled | `templates/*.json` inside the plugin | Defaults shipped with weft |\n\nSame-named template higher in the table overrides lower tiers, so you can shadow a bundled template with a project-specific variant.\n\n## Version\n\n**v0.3.0** — current. See [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to run tests, add templates, and propose changes.\n\n## License\n\n[MIT](LICENSE) © dioptx\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdioptx%2Fweft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdioptx%2Fweft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdioptx%2Fweft/lists"}