From c8e2ce339b8f5043f08e256ab6fc582b20ade05d Mon Sep 17 00:00:00 2001 From: vikingowl Date: Sun, 22 Feb 2026 08:43:00 +0100 Subject: [PATCH] docs: add project README --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..94ca14d --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# workflow-miner + +A Rust CLI + zsh plugin that automatically discovers recurring multi-step command workflows from your [Atuin](https://github.com/atuinsh/atuin) shell history. + +## The Problem + +Developers repeat multi-step command sequences daily — debug cycles, deploy flows, environment setup — but no tool detects or remembers them. Everything today is either single-command prediction (McFly) or manually authored runbooks (Just, Task, Make). The gap between "I keep doing this manually" and "I should write a script for this" remains wide open. + +## How It Works + +1. **Ingest** — Reads Atuin's SQLite history database (read-only) with full context: command, cwd, session, exit code, duration, timestamps +2. **Abstract** — Normalizes commands for pattern matching (`git commit -m "fix typo"` → `git commit -m `) +3. **Mine** — Applies [PrefixSpan](https://hanj.cs.illinois.edu/pdf/span01.pdf) sequential pattern mining to find recurring command sequences across sessions +4. **Score** — Ranks workflows by frequency, recency, consistency, and context specificity +5. **Surface** — Exports as Justfile recipes, JSON/YAML catalogs, interactive TUI dashboard, or inline zsh suggestions + +## Planned Features + +- `wfm scan` — Mine workflows from Atuin history +- `wfm list` — List discovered workflows, ranked by relevance +- `wfm show ` — Inspect a workflow in detail +- `wfm suggest` — Context-aware "what should I do next?" suggestions +- `wfm export justfile|json|yaml` — Export workflows as reusable recipes +- `wfm tui` — Interactive dashboard for browsing and managing workflows +- `wfm describe` — Optional LLM-powered naming and descriptions (fully local by default) +- **zsh plugin** — Inline suggestions via keybinding or ambient mode + +## Status + +Early design phase. See [docs/](docs/) for architecture and research notes. + +## Prior Art + +- [ShRec](https://arxiv.org/abs/2408.05592) (Huawei, 2024) — Proved sequential pattern mining on shell history extracts real workflows. Research only, not shipped as a tool. +- [Atuin](https://github.com/atuinsh/atuin) — Shell history storage layer this project builds on. +- [McFly](https://github.com/cantino/mcfly) — Neural net single-command prediction. No multi-step workflows. +- [PrefixSpan](https://hanj.cs.illinois.edu/pdf/span01.pdf) — The sequential pattern mining algorithm at the core. + +## License + +TBD