npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@win.sh/win

v0.1.2

Published

Open-source business improvement loops, terminal harness, and win.sh connector contracts for AI agents.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

romainsimonromainsimon

Keywords

win.shagentscodexclaude-codebusiness-automationloops

Readme

win.sh business loops for AI agents

win

CI npm license

Open-source business improvement loops for Codex, Claude Code, and hosted win.sh.

win turns business signals into repeatable agent runs: watch the signal, decide if action is worth it, write a scoped brief, let an agent execute, capture proof, verify the outcome, update the journal, and schedule the next useful run.

It is not another chat wrapper. It is the operating memory around AI agents so they can improve products, growth, support, and operations over time.

npm install -g @win.sh/win
win list

Local-first. Markdown-native. Hosted-ready.

When working from a source checkout before the package is installed globally, use node bin/win-loops.js in place of win.

What It Does

Most automations are fixed cron jobs with a fixed prompt. Real business work is a loop.

| Cron task | win loop | | --- | --- | | Runs at a fixed time | Chooses the next useful run time after every execution | | Runs the same script every time | Uses a readable SKILL.md that can adapt to the current signal | | Usually fire-and-forget | Records briefs, artifacts, approvals, outcomes, and journals | | Hard to inspect later | Stores everything as files in the target repo | | Good for mechanical jobs | Built for business cases where judgment matters |

Examples:

| Loop | Watches | Produces | | --- | --- | --- | | bug-autofix | Sentry/log errors, impacted customers, GitHub context | scoped fix brief, agent handoff, PR/test proof | | seo-growth | Google Search Console, page metadata, competitors | content or technical SEO action with verification window | | feedback-to-fix | support threads, revenue at risk, analytics, issues | bug/feature/docs decision plus reply draft | | conversion-optimizer | funnel metrics and benchmarks | test hypothesis, implementation brief, outcome check | | ads-budget-guard | spend, CAC, creative performance | pause/scale/test decision with approval boundary |

Why Teams Use It

  • Give Codex or Claude Code business context, not just one-off tasks.
  • Keep every agent decision inspectable in Markdown and JSONL.
  • Add approval boundaries before agents merge code, publish content, spend money, or contact customers.
  • Run locally with your own agent subscription, then move the same loop contracts to hosted win.sh when you need scheduling, connectors, dashboards, and team governance.
  • Build custom loops as readable files instead of opaque workflow graphs.

Open Source vs Hosted

| Use this repo when you want... | Use hosted win.sh when you want... | | --- | --- | | local files, local agent execution, and full inspectability | no install, managed scheduling, and team dashboards | | Markdown loop packs you can edit and commit | OAuth connectors and hosted connector snapshots | | Codex or Claude Code running in your own repo | managed execution and approval queues | | JSONL state, append-only journals, and terminal workflows | email/mobile approvals, shared history, and central governance |

The loop logic stays open and portable. Hosted win.sh is the managed operating layer around the same contracts.

Quick Start

From npm:

npm install -g @win.sh/win
win list

From source:

git clone https://github.com/win-sh/win.git
cd win
npm install
npm run check
node bin/win-loops.js list

Install a loop into an app repo:

win install bug-autofix --repo /path/to/app --agent codex

Create a run from a realistic connector snapshot:

win run bug-autofix \
  --repo /path/to/app \
  --connector-fixture loops/bug-autofix/examples/connector-snapshot.json

Ask what the operator or agent should do next:

win status --repo /path/to/app
win next --repo /path/to/app
win exec --repo /path/to/app --agent codex --dry-run

Execute and capture output:

win exec --repo /path/to/app --agent codex --run <run-id>

Accept proof suggested from the execution log:

win artifact suggestions --repo /path/to/app
win artifact accept <suggestion-id> --repo /path/to/app

What You Get

  • 50 readable loop packs across engineering, SEO, growth, ads, customer, sales, finance, product, and ops.
  • Production-grade starter loops for bug-autofix, seo-growth, and feedback-to-fix.
  • A terminal dashboard with enabled state, current status, next run time, countdown, and last run.
  • Adaptive scheduling: cron can wake the process, but each loop decides when it is useful to run again.
  • Append-only loop journals.
  • Run briefs under .win/runs/.
  • Execution logs under .win/executions/.
  • Artifact suggestions parsed from agent output.
  • Approval and outcome tracking.
  • Connector snapshot contracts for hosted win.sh.
  • Browser-based terminal auth for hosted win.sh API tokens.

Terminal Dashboard

win status --repo /path/to/app

Example:

Loop         State     Status      Next run                  Countdown      Last run
-----------  --------  ----------  ------------------------  -------------  ------------------------
bug-autofix  enabled   diagnosing  2026-06-16T14:00:00.000Z  4h 30m         2026-06-16T08:00:00.000Z
seo-growth   disabled  watching    -                         not scheduled  -

Operator queue:

win inbox --repo /path/to/app
win next --repo /path/to/app

Scheduler tick:

win tick --repo /path/to/app

tick creates run briefs only for enabled loops whose adaptive nextRunAt is due. It also resumes approved actions before normal scheduled work.

Production Loops

Bug Autofix

Turns Sentry/log errors and GitHub context into scoped fix briefs.

win run bug-autofix \
  --repo /path/to/app \
  --connector-fixture loops/bug-autofix/examples/connector-snapshot.json

The adapter normalizes Sentry issue metadata, sample events, impacted paying users, stack frames, affected routes, GitHub codeowners, and recent commits.

SEO Growth

Turns GSC, page, competitor, and repo context into one SEO action.

win run seo-growth \
  --repo /path/to/site \
  --connector-fixture loops/seo-growth/examples/connector-snapshot.json

The adapter normalizes GSC page/query metrics, target page metadata, competitor SERP patterns, candidate website files, and the verification window.

Feedback To Fix

Turns support threads, customer value, analytics, and GitHub context into a fix, issue, docs change, or reply draft.

win run feedback-to-fix \
  --repo /path/to/app \
  --connector-fixture loops/feedback-to-fix/examples/connector-snapshot.json

The adapter normalizes representative user quotes, classification, affected paying users, revenue at risk, existing issues, candidate files, and customer reply drafts.

Local State

Installing a loop writes inspectable state into the target repo:

.win/
  loops/<loop-id>/LOOP.md
  loops/<loop-id>/journal.md
  loops/<loop-id>/state.json
  runs/<run-id>.md
  executions/<execution-id>.log
  state/runs.jsonl
  state/executions.jsonl
  state/artifacts.jsonl
  state/artifact-suggestions.jsonl
  state/outcomes.jsonl
  state/approvals.jsonl

.agents/
  skills/win-<loop-id>/SKILL.md

.claude/
  skills/win-<loop-id>/SKILL.md

AGENTS.md
CLAUDE.md

Nothing is hidden. You can inspect, diff, commit, back up, or migrate every important decision.

AGENTS.md makes the loop visible to Codex and Codex Automations. CLAUDE.md plus .claude/skills makes the loop visible to Claude Code and Claude Code recurring tasks.

Hosted win.sh

Local mode is the open harness. Hosted win.sh adds:

  • OAuth connectors
  • hosted scheduling
  • team approvals
  • loop dashboards
  • mobile/email approval flows
  • centralized journals
  • managed execution

Connect the CLI:

win auth login
win auth status

Browser approval flow:

  1. CLI starts a localhost callback server.
  2. CLI opens https://win.sh/settings/api-tokens/cli.
  3. User approves a scoped API token.
  4. win.sh redirects back to the local callback.
  5. CLI stores the token at ~/.config/win-loops/auth.json with file mode 0600.

Manual token fallback:

win auth login --token <token> --workspace <workspace>

Fetch a hosted connector snapshot:

win snapshot fetch bug-autofix --output .win/snapshots/bug-autofix.json

Then run it locally:

win run bug-autofix \
  --repo /path/to/app \
  --connector-fixture .win/snapshots/bug-autofix.json

Core Commands

win list
win inspect <loop>
win install <loop> [--repo <path>] [--agent codex|claude-code]
win run <loop> [--repo <path>] [--trigger manual|signal] [--signal <text>] [--signal-file <path>] [--fixture <path>] [--connector-fixture <path>]
win status [--repo <path>]
win inbox [--repo <path>]
win next [--repo <path>]
win exec [--repo <path>] [--agent codex|claude-code] [--run <run-id>] [--dry-run]
win tick [--repo <path>]
win enable <loop> [--repo <path>]
win disable <loop> [--repo <path>]
win journals [--repo <path>]
win journal <loop> [--repo <path>]

Reporting:

win artifact attach <run-id> [--repo <path>] [--kind <kind>] [--url <url>] [--path <path>] [--title <text>] [--summary <text>]
win artifact suggestions [--repo <path>]
win artifact suggest <execution-id> [--repo <path>]
win artifact accept <suggestion-id> [--repo <path>]
win outcome record <run-id> [--repo <path>] --status <status> [--metric <metric>] [--summary <text>] [--evidence <text>]
win approval request <run-id> [--repo <path>] --action <text> --reason <text> [--risk low|medium|high] [--approver <text>]
win approval approve <approval-id> [--repo <path>] [--by <text>] [--note <text>]
win approval reject <approval-id> [--repo <path>] [--by <text>] [--note <text>]

Hosted auth and snapshots:

win auth login [--token <token>] [--workspace <name>] [--app-url <url>] [--api-url <url>] [--config-dir <path>] [--no-open] [--print-url]
win auth status [--config-dir <path>]
win auth token [--config-dir <path>]
win auth logout [--config-dir <path>]
win snapshot fetch <loop> [--config-dir <path>] [--api-url <url>] [--token <token>] [--output <path>]

Loop Format

Each loop pack lives under loops/<loop-id>/:

LOOP.md
SKILL.md
journal.md
examples/input.json
examples/run-brief.md
evals/contract.json

LOOP.md is the business contract. SKILL.md is the executor workflow. journal.md is append-only loop memory.

Quality Gates

npm run check
npm run pack:dry

Current coverage includes loop parsing, catalog validation, installation into target repos, run brief creation, adaptive scheduling, connector snapshots, terminal auth, hosted snapshot fetching, operator queues, executor dry-runs, execution capture, artifact suggestions, approvals, outcomes, and journal writes.

Release Status

Current main is package-ready for @win.sh/[email protected]. The existing v0.1.0 and v0.1.1 tags predate the final automation compatibility changes, so they are left untouched; use v0.1.2 for the first final npm publish candidate after the win.sh npm org has either trusted publishing configured for GitHub Actions or a temporary NPM_TOKEN with publish access.

Hosted API docs are live at win.sh/docs/api. Hosted snapshot calls require an API token, and full browser-approved CLI auth requires a signed-in win.sh session.

Documentation

License

MIT