explaingit

clickspider/icpfinder

★ 17TypeScriptAudience · pm founderComplexity · 2/5LicenseSetup · moderate

TLDR

A CLI and web tool that takes a one-line product description and returns three ideal customer profiles with verified email addresses in about 30 seconds, using AI to identify customer types and an email service to find real decision-makers.

Mindmap

mindmap
  root((icpfinder))
    What It Does
      Customer archetype generation
      Email verification
      Streaming results
    Tech Stack
      TypeScript
      Google Gemini
      Hunter.io
      Next.js
    Packages
      Core engine
      Provider adapters
      Web demo
    Use Cases
      Pre-launch validation
      Cold email prospecting
      Lead generation
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Paste your product idea into icpfinder and get three specific customer archetypes with verified email addresses to cold-email before writing any code

USE CASE 2

Swap out the default Gemini and Hunter.io providers for your preferred AI or email service without changing the core orchestration engine

USE CASE 3

Deploy the Next.js web package as a hosted lead-generation micro-tool with per-IP rate limiting and result caching

Tech stack

TypeScriptGoogle GeminiHunter.ioNext.js

Getting it running

Difficulty · moderate Time to first run · 30min

Requires a Google Gemini API key and a Hunter.io API key, each run costs roughly $1 mostly from email verification. A free stub mode is available for local testing.

MIT license, use, copy, modify, and distribute freely for any purpose, including commercial use, as long as you keep the copyright notice.

In plain English

icpfinder is a free, open-source command-line and web tool aimed at independent software builders who want to find their first paying customers before investing heavily in marketing. You paste a one-line description of your product idea, and the tool returns three types of potential customers (called archetypes) along with verified email addresses for real people at matching companies, all within about 30 seconds. Internally, the tool sends your product description to an AI model (Google Gemini by default) which identifies three distinct customer profiles, each with an industry, a job role, a pain point your product might address, and signals to look for when prospecting. For each profile it then queries an email verification service (Hunter.io by default) to find actual decision-makers and confirm their contact addresses. The whole process streams results back as they arrive rather than waiting until everything is finished. The codebase is split into three packages. The core package contains the orchestration logic and defines the interfaces any AI or email provider must implement. The providers package contains the default adapters for Gemini and Hunter.io. The web package is a Next.js application that exposes the tool as a hosted demo, with rate limits per IP address and optional caching to avoid repeat API calls for the same seed text. Using your own API keys for Gemini and Hunter.io costs roughly a dollar per run, mostly from the email verification lookups. A stub mode lets you run the demo locally for free without any keys, though the results will be placeholder data. The hosted demo is also free but caps usage per IP. The project is MIT-licensed and written in TypeScript. It is designed so that the underlying AI and email providers can be swapped without modifying the core engine, which makes it straightforward to substitute other services. With 17 stars on GitHub, it is a recent release at an early stage.

Copy-paste prompts

Prompt 1
Run icpfinder with the description 'a tool that automates employee onboarding paperwork' and show me the three customer archetypes and their pain points before any emails are looked up
Prompt 2
Swap icpfinder's default Google Gemini adapter for OpenAI GPT-4o by implementing the AI provider interface defined in the core package
Prompt 3
Deploy the icpfinder Next.js web package to Vercel with my own Gemini and Hunter.io API keys and set the per-IP rate limit to 3 runs per day
Prompt 4
Using icpfinder stub mode locally, explain what each field in a customer archetype output means, industry, job role, pain point, and prospecting signals
Open on GitHub → Explain another repo

← clickspider on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.