vibesift

Scope. Sift. Ship. One CLI. One HTML page per agent session. Read-only. Auto-committed.

Research preview. v0.1 is the first public cut. Shape, defaults, and CLI surface are still moving. Open for feedback and contributors — open an issue or send a PR.

brainstorm.md, spec.md, plan.md, implementation.md. Your AI sessions generate dense, structured thinking and ship it as walls of markdown nobody on your team opens. vibesift takes the same content and renders it as one HTML page per session: every constraint, option, and decision is a collapsible record. The page reads at a glance, every detail one click away.

npx vibesift bootstrap                                    # one-time per repo
npx vibesift init my-feature --title "Build the thing"
npx vibesift scope my-feature add-constraint "must work offline"
npx vibesift advance my-feature
# … each command auto-commits to your current branch

---

Why

The brainstorm/spec/design/implementation flow from agentic toolchains (Anthropic superpowers, GitHub Spec Kit, Kiro, TaskMaster, BMAD) produces gold content and ships it as .md files nobody reads. The information is there, structured, well-reasoned. It just lives behind a wall of prose that mobile reviewers swipe past.

vibesift is the smallest possible thing that fixes that:

• The artifact is HTML, not markdown. Open it in any browser, on any phone.
• Every constraint, option, and decision is a <details> block. Closed by default; click to expand. One page reads at a glance; every supporting detail is one click away.
• State (the structured JSON) lives inside the HTML in a <script> tag. Single source of truth. No sidecar files.
• Each CLI command auto-commits to the current branch. Git log IS the audit trail; every constraint, every option, every task is its own commit.
• Pure Node 20+ CLI, zero runtime dependencies, inline CSS, one inline script block (theme toggle + copy-as-prompt export).
• One canonical skill markdown installs globally into Claude Code, Codex, OpenCode, and Gemini CLI; Cursor via a per-project rule file.

Thariq from the Claude Code team made the same case in detail in "The Unreasonable Effectiveness of HTML": "I tend to not actually read more than a 100-line markdown file." vibesift is the productized form of that pattern for terminal-driven agent flows — same thesis, structured around scope/sift/ship phases.

Install

npm (any platform with Node 20+)

npm install -g vibesift
# or run on demand:
npx vibesift <command>

Homebrew (macOS / Linux)

brew install neurot1cal/tap/vibesift   # planned for v0.2

Scoop (Windows)

scoop bucket add vibesift https://github.com/neurot1cal/scoop-vibesift   # planned for v0.2
scoop install vibesift

From source

git clone https://github.com/neurot1cal/vibesift.git
cd vibesift
npm test
node src/cli.js --help

Quick start

# in any repo with git initialized
vibesift bootstrap                          # creates docs/sessions/
vibesift install                            # detects + wires every agent harness

# scope phase
vibesift init blue-widget \
  --title "Build a blue widget" \
  --problem "Users need a widget that does X"
vibesift scope blue-widget add-constraint "must work offline"
vibesift scope blue-widget add-constraint "under 50KB total"
vibesift decide blue-widget --phase scope --text "go static, no backend"
vibesift advance blue-widget                 # → sift

# sift phase
vibesift sift blue-widget add-option "vanilla JS"
vibesift sift blue-widget add-option "Preact"
vibesift sift blue-widget rationale "vanilla keeps the bundle smallest"
vibesift decide blue-widget --phase sift --text "vanilla JS"
vibesift advance blue-widget                 # → ship

# ship phase
vibesift ship blue-widget task add "scaffold index.html"
vibesift ship blue-widget task add "wire color picker" --agent worktree-A
vibesift ship blue-widget task add "color contrast tests" --parent 2 --agent worktree-A
vibesift ship blue-widget task done 1
vibesift deploy blue-widget                  # mark deployed; pipeline updates
vibesift status blue-widget                  # print current state
vibesift list                                # list every session in this repo

The session HTML carries a 5-stage pipeline graphic at the top (Idea → Scope → Sift → Ship → Deployed) and an SVG tree inside the Ship section that shows parent → child task relationships and agent attribution at a glance. A "Copy as prompt" button in the header exports the session as a structured plaintext primer ready to paste into a new Claude session.

Enable GitHub Pages on /docs of your default branch and the page is live at https://<owner>.github.io/<repo>/sessions/blue-widget/ within a minute.

This is the beginning of the README. Read the rest at the original. Read the full README ↗