Metadata-Version: 2.4
Name: hype-launch
Version: 0.3.0
Summary: Announce your OSS project like you know what you're doing
Author: DjinnFoundry
License: AGPL-3.0-only
License-File: LICENSE
Keywords: announcements,cli,devtools,launch,opensource
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: ai
Requires-Dist: anthropic>=0.30; extra == 'ai'
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: atproto>=0.0.50; extra == 'all'
Requires-Dist: praw<8,>=7.7; extra == 'all'
Provides-Extra: bluesky
Requires-Dist: atproto>=0.0.50; extra == 'bluesky'
Provides-Extra: dev
Requires-Dist: anthropic>=0.30; extra == 'dev'
Requires-Dist: atproto>=0.0.50; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: praw<8,>=7.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: reddit
Requires-Dist: praw<8,>=7.7; extra == 'reddit'
Description-Content-Type: text/markdown

```
 ██╗  ██╗██╗   ██╗██████╗ ███████╗
 ██║  ██║╚██╗ ██╔╝██╔══██╗██╔════╝
 ███████║ ╚████╔╝ ██████╔╝█████╗
 ██╔══██║  ╚██╔╝  ██╔═══╝ ██╔══╝
 ██║  ██║   ██║   ██║     ███████╗
 ╚═╝  ╚═╝   ╚═╝   ╚═╝     ╚══════╝
```

### announce your OSS project like you know what you're doing

Launching OSS is a 14-hour day of copy-pasting into HN, Reddit, X, Bluesky, Dev.to, and Product Hunt — half of which you'll get wrong, half of which you'll mistime, and one of which will get you shadowbanned. `hype` is a CLI that runs the coordinated 24-hour blitz from a single `launch.toml`: it generates platform-specific copy with Claude, scores it before posting, runs pre-flight checks against your accounts, and executes the timed sequence so you can sit back and watch the spike. Then it listens for the spike.

[![build](https://img.shields.io/badge/build-passing-success)](https://github.com/djinnfoundry/hype/actions)
[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/djinnfoundry/hype)
[![pypi](https://img.shields.io/badge/pypi-v0.3.0-blue)](https://pypi.org/project/hype-launch/)
[![license](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
[![python](https://img.shields.io/badge/python-3.12+-yellow)](https://www.python.org/)

---

## Demo

```console
$ hype launch new --schedule auto

  hype v0.3.0 — coordinated launch sequencer
  project: hype
  mode:    new
  brief:   ./launch.toml

  ▶ pre-flight ───────────────────────────────────────────────
  [PASS]  X            account active, write scope confirmed
  [PASS]  Reddit       847d old, 2,341 karma — eligible for all subs
  [WARN]  Reddit       r/programming karma 2,341 < recommended 5,000
  [PASS]  HN           account karma 1,204
  [PASS]  Bluesky      handle resolved
  [PASS]  Dev.to       API key valid
  [PASS]  Timing       Sun 11:14 UTC — low-competition HN window
  [PASS]  Content      HN title 82/100, X hook 87/100

  Continue with 1 warning? [y/N] y

  ▶ copy generation (claude-sonnet-4-6) ─────────────────────
    18 completions · 3 variants each · 9.2s · $0.31

  ▶ scheduled sequence ──────────────────────────────────────
    12:01 AM PT  →  Product Hunt    (guided)
    12:30 AM PT  →  X thread        (auto)
     1:00 AM PT  →  Show HN         (guided)
     3:00 AM PT  →  Bluesky         (auto)
     6:00 AM PT  →  Reddit wave 1   (auto, 60s stagger)
     2:00 PM PT  →  Reddit wave 2   (auto, 60s stagger)
     6:00 PM PT  →  Dev.to          (auto)

  Proceed? [y/N] y
```

---

## Features

- **Coordinated blitz** — one `launch.toml`, six platforms, one tightly-timed sequence. Scatter-posting is strictly worse than the spike.
- **Pre-flight layer** — account health, karma age, rate-limit windows, timing window, content scoring. Catches the failure before it costs you a launch.
- **AI copy generation** — Claude turns your project brief into platform-specific copy: HN titles (3 scored variants), Reddit posts (per-subreddit framing, never identical), X threads, Bluesky, Dev.to articles, PH listings.
- **Content scoring** — HN title scorer (specificity, hype-word penalty, corpus similarity vs top-100 Show HNs). X hook scorer (9 signals: hook strength, link placement, hashtag count, CTA clarity).
- **Anti-AI-slop pipeline** — every generated variant is scrubbed (em-dashes rewritten to commas/semicolons, invisible unicode watermarks stripped) and scored against a 38-pattern AI banlist (`delve`, `leverage`, `robust`, `tapestry`, `not just X but Y`, etc.) plus passive-voice, vague-word, conversational, and specificity signals. Variants below the WARN threshold (70/100) flag in the review UI; below BLOCK (50/100) the review refuses to ship them. `CopyResult.best` picks the highest-humanity variant instead of trusting the LLM's stated order.
- **signal listen** — post-launch monitoring across HN Algolia, Reddit PRAW, and X. Alerts on point velocity, comment surges, notable mentions. Terminal bell, desktop notification, JSONL log.
- **signal research** — pre-launch positioning workflow. Pulls 30/60/90-day corpus from HN, Reddit, X, then runs a multi-pass Claude pipeline that returns a competitive landscape, audience profile, positioning angles, per-platform messaging hooks, and a draft of `launch.toml` hints. Pass `--no-positioning` for raw signal only.
- **Launch executor** — `hype launch resume` dispatches to platform adapters automatically (X, Bluesky, Reddit, Dev.to) and prompts for manual platforms (HN, Product Hunt). Timed scheduling sleeps until each step is due. `--one` for step-by-step control.
- **Resumable sequences** — Ctrl-C anytime, `hype launch resume` picks up where you left off. State saved after every step.
- **Press materials** — `hype launch press` generates a `press-release.md` and `outreach-template.md` from your project brief via Claude.
- **Config mutation** — `hype config set platforms.x.api_key <value>` sets any config value via dotted key path. Creates sections if missing, redacts secrets in output.

---

## Install

```bash
pip install hype-launch
```

Or with `uv` (recommended):

```bash
uv tool install hype-launch
```

Then:

```bash
hype config init        # interactive credential wizard
hype config validate    # confirm everything works
hype config set platforms.x.api_key "your-key"  # or set individual values
```

---

## Quick start

```bash
# 1. install
uv tool install hype-launch

# 2. set up credentials (one-time, per machine)
hype config init

# 3. drop a launch.toml in your project repo
cd ~/src/myproject
hype config edit launch.toml      # writes a starter file

# 4. dry run the whole thing
hype launch new --dry-run

# 5. ship it
hype launch new --schedule auto
```

That's the complete loop.

---

## Platform support

| Platform     | Read              | Write                        | Automation     | Notes |
| ------------ | ----------------- | ---------------------------- | -------------- | ----- |
| X / Twitter  | x-reader          | OAuth 1.0a                   | full auto      | ~$0.01/post (pay-per-use since Feb 2026) |
| Reddit       | PRAW              | PRAW                         | full auto      | OAuth app approval required (1-3 days) |
| Hacker News  | Algolia           | clipboard + browser (manual) | guided         | Bots banned — hype copies title and opens submit page |
| Bluesky      | AT Protocol       | AT Protocol                  | full auto      | |
| Dev.to       | REST              | REST                         | full auto      | |
| Product Hunt | GraphQL           | browser (you fill the form)  | guided         | |
| Lobste.rs    | none              | none                         | manual + copy  | |

Full automation where the platform allows it. Guided submission where it doesn't — HN bans automated posting, so hype copies your title to clipboard and opens the submit page in your browser.

---

## `hype signal`

### Research a topic before launch

```bash
hype signal research "rust tui frameworks"
hype signal research "OSS launch strategy" --days 90 --depth deep
hype signal research "bun vs node" --platforms hn,reddit --output ./research.md
hype signal research "rust tui frameworks" --no-positioning   # raw only
```

`signal research` is now a positioning workflow, not just raw signal collection. After the concurrent HN/Reddit/X sweep, it runs a multi-pass Claude pipeline that produces a structured strategy report:

- **Summary, sentiment, top concerns, opportunities** — Pass 1, the original synthesis.
- **Competitive landscape** — named alternatives mentioned in the corpus, with strengths/weaknesses and rough mention counts.
- **Audience profile** — per-platform experience level, stack, motivations, and language style.
- **Positioning angles** — 2-4 sharp angles that exploit the gaps in the competitive landscape, each with evidence and a risk note.
- **Per-platform messaging hooks** — concrete one-liner examples for HN, Reddit, X, and Bluesky, plus what to avoid.
- **Suggested `launch.toml` hints** — tagline options, problem/solution statements, a differentiator, and target subreddits you can paste straight into your `launch.toml`.

Strategy sections render before the raw post lists so you read conclusions first. Pass `--no-positioning` if you only want the raw signal sweep.

### Listen to your launch in real time

```bash
hype signal listen "hype" --hn-id 43789012 --notify
hype signal listen "hype" --log ./launch-events.jsonl &
```

```console
[HN]      item/43789012  43 pts / 12 comments  rank ~#24  +7 pts  ← SPIKE
[Reddit]  r/rust          89 pts / 23 comments  +12 pts  ← SPIKE
          New comment (user_foo): "How does this compare to..."
[X]       14 mentions since launch  +3 new  ← SPIKE
          Notable: @importantdev (12k followers): "Just tried hype..."
```

Alerts on: point velocity, comment surges, controversy ratios (`comments > points` is a death spiral), milestones (100/200/500 points), notable mentions from accounts >5k followers.

---

## `hype launch`

Four modes for four levels of "is this a real launch":

| Mode             | Default platforms                       | Use it for                |
| ---------------- | --------------------------------------- | ------------------------- |
| `launch new`     | PH, HN, Reddit (3 subs), X, Bluesky, Dev.to | Initial launch            |
| `launch update`  | X, Bluesky, Reddit, Dev.to              | v2.0, major release       |
| `launch minor`   | X, Bluesky                              | Quick feature drop tweet  |
| `launch press`   | none — file output                      | Press release + outreach template |

```bash
hype launch new                                      # interactive, optimal-window auto-schedule
hype launch new --dry-run                            # generate everything, post nothing
hype launch new --platforms "hn,reddit:rust,x" --media demo.mp4
hype launch new --variants 5 --no-confirm            # agent / CI mode

hype launch update --version v2.0.0 --changelog CHANGELOG.md
hype launch update --dry-run

hype launch minor --note "added --json flag to all commands"
hype launch minor --dry-run

hype launch press                                    # generates press-release.md + outreach-template.md
hype launch press --output ./press/

hype launch resume                                   # execute all pending steps
hype launch resume --one                             # execute one step then stop
hype launch resume --no-execute                      # view status only
```

---

## Pre-flight output

Pre-flight runs before any post leaves your machine. Three severity levels: `BLOCK` (cannot proceed), `WARN` (confirm to proceed), `INFO` (FYI). Exit code reflects the worst outcome — wire it into CI if you're into that.

```console
$ hype preflight new

  ▶ pre-flight checks ────────────────────────────────────────

  [PASS]  X            credentials valid, write scope confirmed
  [PASS]  Reddit       account 847d old, karma 2,341 — eligible
  [WARN]  Reddit       r/programming karma 2,341 < recommended 5,000
  [BLOCK] HN           queue has 8 posts in last 15min — wait 12 min
  [PASS]  Bluesky      handle resolved, app password valid
  [PASS]  Dev.to       API key valid
  [PASS]  Timing       Sun 11:14 UTC — optimal HN low-competition window
  [PASS]  HN title     82/100  (specificity 18/20, hype-words 15/15)
  [PASS]  X hook       87/100  (hook 18/20, link placement 10/10)

  Result: 1 BLOCK, 1 WARN, 7 PASS — cannot proceed.

  exit 2
```

Exit codes: `0` all clear · `1` warnings · `2` blocking issues.

---

## Config — the two-file model

`hype` uses two config files. One has secrets and lives on your machine. One has the brief and lives in your repo.

**`~/.config/hype/config.toml`** — credentials. Never committed. One per machine. Written by `hype config init`.

**`./launch.toml`** — the project brief. Committed to your repo. No secrets. Reviewable by collaborators.

```toml
[project]
name    = "hype"
tagline = "announce your OSS project like you know what you're doing"
repo    = "https://github.com/djinnfoundry/hype"
version = "0.3.0"
license = "AGPL-3.0-only"
stack   = ["python", "cli", "devtools"]

[project.brief]
problem = """
Launching OSS requires the same announcement across 10+ communities
with different formats, timing, and norms. Most developers do it manually.
"""
solution = """
hype generates platform-optimized copy from one brief, scores it before posting,
and executes a coordinated timed sequence.
"""
differentiator = """
Pre-flight layer: account health, karma, timing, content scoring checked
before any post goes out. One brief → Claude → platform-specific copy.
"""
install         = "pip install hype-launch"
personal_story  = "Built after manually posting a launch to 12 communities in one day."

[launch]
scheduled_at = "auto"
subreddit    = "python"
platforms    = []             # empty = all configured platforms
```

See [`launch.toml.example`](launch.toml.example) for all fields with documentation.

Environment variable overrides (`HYPE_PLATFORMS__X__API_KEY=...`) for CI and agents.

---

## Why hype?

The coordinated 24-48 hour blitz is the mechanic that makes OSS launches work. HN + GitHub release + X simultaneous, then Reddit waves through the morning — that's what creates the spike that triggers GitHub Trending, which triggers more eyes, which triggers more stars, which is the entire point.

Scatter posting across different days is **strictly worse**. Posting to HN at the wrong hour is strictly worse. Forgetting to check your Reddit karma against the subreddit minimum is strictly worse. Generating identical copy for r/rust and r/programming is strictly worse — it's also a great way to get filtered.

`hype` operationalizes the mechanic. It's not a social media scheduler. It's not a marketing platform. It generates no landing pages, no email sequences, no analytics dashboards. It does one thing: run the launch you would have run manually, except it actually starts on time, the copy is scored, the windows are optimal, the karma is checked, the rate limits are respected, and you get to watch it happen instead of executing it.

Speed is not the goal. Quality is. Every guardrail in `hype` exists to protect you from getting flagged.

---

## Alternatives

| Tool | What it does | What it doesn't |
|------|-------------|----------------|
| **Postiz** | 34-platform social scheduler, open-source | No HN, no Product Hunt, no launch orchestration |
| **Buffer / Hootsuite** | Social media schedulers | No HN, no Reddit, no Dev.to, no developer focus |
| **Crier** | Cross-posting CLI | No HN, no Reddit, no Product Hunt, no timing/scoring |

hype's edge: launch orchestration (timing, pre-flight, scoring), HN + Product Hunt coverage, CLI-first workflow for developers.

---

## Contributing

PRs welcome. The bar:

1. Fork, branch, test (`pytest`), open PR.
2. Ruff-clean, mypy-clean, no decrease in coverage.
3. Behavior changes need a `CHANGELOG.md` entry.
4. Don't add platforms that require paid APIs unless you've tested the auth flow end-to-end.

Tests run on every PR. Coverage is enforced. We have zero tolerance for red tests.

```bash
git clone https://github.com/djinnfoundry/hype
cd hype
uv sync
uv run pytest
```

---

## License

AGPL-3.0-only from `v0.3.0` onward. `v0.2.0` was published under MIT and
remains available under that license. See [LICENSE](LICENSE).

Built by [djinnfoundry](https://github.com/djinnfoundry). `hype` launched itself with `hype`. If it couldn't, it would be broken.
