Quickstart

1. Install + set a key (or go keyless)

Install metalworks with a provider SDK, then set one key — any provider works:

pip install "metalworks[research,openai]"     # or [research,google], [research,anthropic]
export OPENAI_API_KEY=...                      # or ANTHROPIC_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEY

No API key? Run keyless on your Claude Code login instead — install metalworks[research,claude-code] and run with nothing set; the chat model and web search use your Claude Code session (slower, but zero setup). Embeddings need no separate key: a Google or OpenAI key is used when present, otherwise a small local model (bundled with [research]) is downloaded once — so a single chat key, Anthropic or OpenRouter included, is enough. See Installation.

2. Your first report

/demand-report an affordable, jitter-free focus supplement for developers

from metalworks import Metalworks

mw = Metalworks()                  # provider inferred from the env key
research = mw.research(
    "an affordable, jitter-free focus supplement for developers",
    subreddits=["Nootropics", "Supplements"],   # omit to let it pick
)
report = research.demand

print(report.demand_summary)                    # the demand-strength summary
for cluster in report.ranked_clusters:
    print(cluster.claim, "—", cluster.distinct_author_count, "people")
    for quote in cluster.quotes:                # the real comments behind it
        print("  ", quote.source_url, "→", quote.text[:80])

Every cluster is a real demand theme, and every quote is a verbatim comment you can open — nothing is invented. That report is the input to everything else: positioning, a design system, a build spec, launch copy. See the end-to-end walkthrough.

3. Or use the CLI / MCP / plugin

The same engine, language-agnostic:

# CLI
metalworks research run --question "an affordable focus supplement for developers"
metalworks research list                     # the report id every other command takes
metalworks build init <report-id> --dest ./my-startup

# MCP server (Claude Code, Cursor, any MCP host)
metalworks mcp serve                         # stdio; the data tools need no keys

Or install the Claude Code plugin and ask in chat:

/plugin marketplace add Lab2A/metalworks
/plugin install metalworks@lab2a

Then /demand-report <your idea>. Requires uv on your PATH.

Get started

Build a startup

Your project

Research

Design

Build

Distribution

How it works

1. Install + set a key (or go keyless)

2. Your first report

3. Or use the CLI / MCP / plugin

Next

Build a startup, end to end

Demand research

Why you can trust the output

Configuration

​1. Install + set a key (or go keyless)

​2. Your first report

​3. Or use the CLI / MCP / plugin

​Next

Build a startup, end to end

Demand research

Why you can trust the output

Configuration

1. Install + set a key (or go keyless)

2. Your first report

3. Or use the CLI / MCP / plugin

Next