h4cker.app

h4cker.app is an AI-native Hacker News reading workspace.

Live app · Contributing · Security

It combines a fast Hacker News reader with a persistent Flue-powered Agent for research, personalized recommendations, reading memory, and scheduled digests.

Features

• Browse and search stories, comments, and every major Hacker News feed.
• Read nested discussions and use a Hacker News session to vote, comment, and reply without storing the HN password on the server.
• Translate titles, stories, and comments; summarize discussions; cluster viewpoints; generate deep reads; and judge whether an article is worth the time.
• Save stories and comments, manage a read-later queue, revisit reading history, compare items, review recurring topics, and export the library as Markdown.
• Continue persistent h4cker Agent conversations backed by Flue Runtime, typed product tools, Skills, and bounded research Subagents.
• Research Hacker News and linked pages, extract technical signals, and polish reply drafts with explicit human review before posting.
• Create a personalized First Brief, improve later recommendations through feedback and reading behavior, and control the Agent's memory and preferences.
• Schedule Agent Digest generation and Email delivery, inspect delivery status, unsubscribe safely, and revisit previous Digest editions.
• Use localized routes and interface translations across supported languages.

Project Structure

apps/web            TanStack Start web app
services/api        Cloudflare Worker API
services/agent      Flue-powered Cloudflare Agent Worker
packages/shared     Shared types
packages/api-client API client
migrations/d1       D1 database migrations
blueprints          Ordered implementation guides for AI coding agents

Architecture

flowchart TB
    User["Browser"] --> Web["Web Worker<br/>TanStack Start SSR"]
    User -->|"Privacy-bounded product analytics"| Flareboard["Flareboard<br/>events · funnels"]
    Web -->|"Service binding / HTTPS"| API["API Worker<br/>Hono"]

    subgraph AgentWorker["Agent Worker · one Hono application"]
        ProductFacade["Internal Product API facade<br/>/api/v1/agent/*"]
        FlueRuntime["Flue Runtime<br/>Agents · Workflows · Runs"]
        ContinuingAgent["h4cker continuing Agent"]
        Workflows["First Brief · HN Scout<br/>Agent Digest · Internal Research"]
        Capabilities["Typed tools · Skills<br/>bounded Subagents"]
        Scheduler["Cron · delivery queue"]

        FlueRuntime --> ContinuingAgent
        FlueRuntime --> Workflows
        ContinuingAgent --> Capabilities
        Workflows --> Capabilities
        Scheduler --> Workflows
    end

    API -->|"Agent Product APIs"| ProductFacade
    API -->|"Authenticated /api/v1/flue/*"| FlueRuntime
    Capabilities -->|"Normalized HN, library, and AI facades"| API

    API --> D1["Cloudflare D1<br/>canonical product data"]
    ProductFacade --> D1
    Workflows --> D1
    Scheduler --> D1
    FlueRuntime --> RuntimeState["Flue Durable Objects<br/>runtime state"]

    API --> HN["Hacker News · Algolia"]
    API --> Stripe["Stripe"]
    API --> Email["Cloudflare Email"]
    API --> Gateway["Cloudflare AI Gateway"]
    Scheduler --> Email
    ContinuingAgent --> Gateway
    Workflows --> Gateway
    Gateway --> Models["Model providers"]
    Capabilities --> BrowserRendering["Cloudflare Browser Rendering<br/>bounded fallback"]

Loading

The API Worker owns authentication, entitlements, billing, stable Product APIs, and authenticated Flue admission. The Agent Worker intentionally combines its internal Product API facade and generated Flue routes in one Hono application. D1 remains canonical for product records; Flue Durable Objects own runtime state, continuing conversations, Workflow execution, and run streams. Flareboard receives privacy-bounded browser analytics for product funnels; it does not replace D1 as the canonical product data store.

Executable follow-up work is maintained in development blueprints.

Prerequisites

• Node.js 22 or newer (below Node.js 25)
• pnpm 10
• A Cloudflare account only for remote resources and deployment

Local Development

Install dependencies:

pnpm install

Create local Worker variable files. The checked-in examples contain development-only placeholders:

cp services/api/.dev.vars.example services/api/.dev.vars
cp services/agent/.dev.vars.example services/agent/.dev.vars

Apply local D1 migrations:

pnpm db:migrate:local

Start the API and web app:

pnpm dev

pnpm dev starts the API, Agent, and web app together. To run only one service:

pnpm dev:api
pnpm dev:agent
pnpm dev:web

Default local URLs:

• Web: http://127.0.0.1:5173
• API: http://127.0.0.1:8789
• Health: http://127.0.0.1:8789/api/health
• Ready: http://127.0.0.1:8789/api/ready

Checks

pnpm typecheck
pnpm test
pnpm build
pnpm check

pnpm check is the same verification gate used by CI.

Deployment

The production app is designed for Cloudflare:

• Web: https://h4cker.app
• API: https://api.h4cker.app
• Agent: h4cker-agent Worker, service-bound from h4cker-api

Required production setup:

• Bind h4cker-web to h4cker.app.
• Bind h4cker-api to api.h4cker.app.
• Configure the API Worker D1 binding as DB.
• Configure AUTH_SECRET as a Wrangler secret for the API Worker.
• Configure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET as API Worker secrets. The GitHub OAuth callback URL is https://h4cker.app/api/auth/callback/github; the GitHub App must have read-only Email Addresses access.
• Configure STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRO_MONTHLY_PRICE_ID, and STRIPE_PRO_YEARLY_PRICE_ID for Web billing.
• Configure REVENUECAT_SECRET_API_KEY and REVENUECAT_ENTITLEMENT_ID=pro for native mobile subscription sync when iOS or Android in-app purchases are enabled.
• Configure AI Gateway auth and model vars for both the API and Agent Workers.
• Keep AUTH_EMAIL_DELIVERY=email for production.
• Enable Cloudflare Email Sending for the h4cker.app domain and configure both the API and Agent Workers with a send_email binding named EMAIL. The API uses AUTH_EMAIL_FROM for verification and password-reset messages; the Agent uses AGENT_EMAIL_FROM for Digest delivery.
• Configure AGENT_INTERNAL_TOKEN as a shared secret for the API and Agent Workers.
• Keep ALLOWED_ORIGINS=https://h4cker.app for the API Worker.
• Keep the Web Worker service binding API_WORKER -> h4cker-api.
• Keep the API Worker service binding H4CKER_AGENT -> h4cker-agent.
• Keep the Agent Worker service binding H4CKER_API -> h4cker-api.

Deploy everything:

pnpm deploy

Deploy separately:

pnpm db:migrate:remote
pnpm deploy:api
pnpm deploy:agent
pnpm deploy:web

Contributing

Bug reports and pull requests are welcome. Start with CONTRIBUTING.md, and report vulnerabilities through the private process in SECURITY.md.

License

h4cker is source-available under the PolyForm Noncommercial License 1.0.0. You may use, modify, and redistribute it for permitted noncommercial purposes. Commercial use is not permitted without a separate commercial license from the copyright holder.

Because this license restricts commercial use, it is not an OSI-approved open-source license.