OpenOutreach: A Self-Hosted CLI That Finds B2B Leads and Explains Its Reasoning

What It Actually Solves

OpenOutreach addresses a specific gap in B2B outreach: the list building and the first-touch email are usually separate, manual, and full of guesswork. You either buy a list of contacts with no context, or you scrape social profiles and risk account bans. This tool takes a plain-language description of your product and target market, finds people from a licensed data provider, and returns a verdict per person explaining why they fit. The output is not a spreadsheet of names; it is a set of reasons you can read and dispute. If you disagree with a verdict, you correct the product description and re-run. That feedback loop is the core idea, and it is genuinely different from a typical lead database. The target user is someone who wants to test outbound sales without building a scraping infrastructure or manually qualifying hundreds of profiles. It is also aimed at developers and AI agents who prefer a command-line interface over a web dashboard.

Architecture: An Orchestrator Over Two Standalone Agents

OpenOutreach is not a monolith. The README describes it as an orchestrator that hosts two separate programs in one process: OpenOutFind handles discovery, qualification, enrichment, and the CRM, while OpenOutSend handles the mailbox and send guards. Each child is a standalone package with its own console script and configuration via environment variables. The bundle adds a wizard because the children are agent-first and remember no state, which is fine for scripts but not for humans. The contract between the two is a public pipe: `outfind find 50 --json | outsend` is a documented way to connect any producer to any receiver. The `openoutreach run` command uses the same JSON Lines boundary internally, just buffered in memory. The README explicitly says there is no privileged in-memory hand-off because that would make the public pipe a lie. That is a thoughtful design choice: it keeps the integration surface honest and testable. For an engineer, this means you can use OpenOutFind alone to generate leads as CSV, or pipe its output into your own sender. The components are not locked into the bundle.

Getting Started: One Install, One Command, No Browser

The quick start is genuinely minimal: `uv tool install openoutreach` followed by `openoutreach`. The first run triggers an onboarding wizard that asks every question needed, and nothing is spent during `init`. If you have long product and target descriptions, you can pass them as files: `openoutreach init --product-docs product.md --target target.md`. The CLI supports explicit goals: `openoutreach run 5` finds five leads with addresses and sends emails, at a maximum of five credits. You can also separate the phases: `openoutreach find 10` produces ten more qualified leads as CSV on stdout and is free, while `find 10 emails` costs one credit per lead with a verified work address. `send` mails what is already stored, and `status` shows what is configured, blocked, and counted. All state lives in `~/.openoutreach`, so stopping and starting loses nothing. The number you ask for is always 'more than you already have', which means re-running continues from where it left off. There is no daemon, no container, and no browser. For an engineer, this is a refreshingly small footprint. The CSV output columns are fixed: email, first_name, last_name, company, title, website, linkedin_url, reason, lead_id, qualified_at. That schema is the public contract for downstream tools.

The Reasoning Mechanism and How to Correct It

The key differentiator is that each lead comes with a written reason for why they fit your ICP. The README says the AI judges each person against the ICP it learned from your product description. That reason is part of the CSV output, so you can read it and decide whether to agree. If you do not agree, you correct the description and re-run. This turns lead qualification from a black box into an editable model. The quality of the reasoning depends entirely on how well you describe your product and target market. A vague description will produce vague reasons. The README does not specify which LLM is used, nor how the reasoning is generated, so you cannot verify the logic without running it. What is clear is that the output is designed for human review, not just for automated sending. That is a deliberate choice: the tool wants you to be able to disagree. The `find 0` command prints what you already have, which is a way to review stored leads without spending credits. This is a practical feature for auditing the qualification quality before you invest in email credits.

Costs, Credits, and the Free Path

Not everything in OpenOutreach is free. The `find` command without the 'emails' argument is free and cannot spend credits. Adding 'emails' costs one credit per lead that carries a verified work address. The `run` command with a number caps the spend at that number of credits. The README is explicit that `find 10 emails` costs credits, while `find 10` does not. This is a metered model tied to a licensed data provider. The exact price of a credit is not stated in the README, nor is the provider named. That is a gap you need to fill before relying on the tool for large-scale outreach. The free path is valuable for testing: you can run `find 10` and inspect the CSV, including the reasons, without any financial commitment. Only when you trust the qualification should you spend on verified addresses. The `send` command also has a guard: it sends until a certain number of conversations are open, and you can limit it with `send 5`. The README mentions 'send guards' but does not specify what they check. You should assume there are deliverability protections, but you cannot verify their effectiveness from the documentation alone.

Agent Integration and the Claude Code Plugin

OpenOutreach is designed to be driven by AI agents. The repository ships a Claude Code plugin that you install with `/plugin marketplace add eracle/OpenOutreach` and `/plugin install openoutreach@openoutreach`. The plugin includes a skill file at `skills/find-leads/SKILL.md` that teaches Claude when to run `find`, which flags cost credits, and how to interpret the CSV output. The skill is just a markdown file describing the CLI contract, so it works with Codex, Cursor, or any other agent. You can copy the skill folder into `~/.claude/skills/` if you prefer not to use the plugin. The README stresses that the skill never buys an address without being asked, never sends without being asked, and never accepts a legal notice on your behalf. That is a sensible safety boundary for an agent that has access to your mailbox. For an engineer, this means you can integrate lead generation into an existing agent workflow without writing custom glue code. The pipe between `outfind` and `outsend` is also agent-friendly because it is a standard Unix pipeline. If you are not on Claude Code, you can point any agent's instructions at the SKILL.md file and it will read the same rules. This is a practical approach to making a CLI agent-native without locking you into one platform.

Limitations and the Wrong Tool Scenarios

OpenOutreach is not a fit for every outreach strategy. First, it depends on a licensed data provider, and the README does not name that provider or disclose coverage. If your niche is obscure or outside major English-speaking markets, the provider may have few or no matching leads. You cannot verify this until you run `find` and see the CSV. Second, the cost model is per verified email address, which can make large-scale campaigns expensive. There is no mention of bulk discounts or a subscription tier. Third, the tool sends from your own mailbox, which means your domain's sender reputation is at stake. The README mentions 'send guards' but does not detail them, so you cannot assess whether they are robust enough for cold outreach at volume. If you are sending thousands of emails, you need a dedicated sending infrastructure, not a CLI that opens conversations from your primary mailbox. Fourth, the output is CSV, not a CRM sync. If your sales process requires lead routing, scoring, or integration with Salesforce or HubSpot, you will need to build that yourself. The pipe to `outsend` is only for sending, not for CRM updates. Finally, because the reasoning is generated by an LLM, it can be confidently wrong. The README encourages you to read and disagree with the reasons, but that manual review is a time cost that scales with lead count.

Alternatives and the Difference in Approach

The most common alternative is a cold-email sequencer like Instantly or Lemlist. Those tools require you to upload a list of contacts. OpenOutreach explicitly rejects that model: there is nothing to upload, and the input is a product description. The difference is where the qualification happens. In a sequencer, qualification is your job before you upload. In OpenOutreach, the AI does the qualification and gives you a reason. Another alternative is a lead database like Apollo.io, which returns rows of contacts that you filter by boolean criteria. OpenOutreach returns verdicts in plain language, not just rows. Apollo gives you many contacts and lets you filter; OpenOutreach gives you fewer contacts but with a written justification. If you prefer to control every filter and have access to a large contact database, Apollo is more flexible. If you want to describe your ideal customer in a sentence and get a shortlist with explanations, OpenOutreach is closer to that. The trade-off is control versus convenience. OpenOutreach also has no browser automation, so it avoids the ToS risk of scraping LinkedIn. That is a real advantage if you are concerned about account bans. However, it also means you are dependent on the licensed provider's data quality.

Maintenance, License, and Upgrade Considerations

The repository is under GPL-3.0, which means any derivative work you distribute must also be GPL-3.0. If you embed OpenOutreach in a commercial product that you ship to customers, you may need to release your source code. If you use it internally for your own sales, the license is unlikely to be a problem, but you should confirm with your legal team. The README does not mention a contribution guide or a roadmap, and there are no recent releases listed. The last push date is September 2026, which suggests active development, but without release tags you cannot pin a version for reproducibility. The installation via `uv tool install` pulls from PyPI, so you are at the mercy of the package version there. The state in `~/.openoutreach` means upgrades should preserve your configuration, but there is no documented migration path. If the data provider changes its API or pricing, the tool may break or become more expensive. The separation into two packages (OpenOutFind and OpenOutSend) means you can upgrade them independently, but you need to track the compatibility between them. The README shows a public pipe contract, but it does not state a version for that contract. That is a risk if you automate the pipe and one side changes its output format.

Editorial conclusion

Adopt OpenOutreach if you are a solo founder or small team that wants a self-hosted, scriptable lead generation pipeline without uploading lists or managing a browser. Do not adopt it if you need fine-grained control over email deliverability, if you cannot accept per-email credit costs, or if your outreach must integrate with a CRM beyond CSV. Before committing, verify the licensed data provider's coverage for your niche and confirm that the GPL-3.0 license fits your distribution plans. Start with `openoutreach find 0` to see what is already configured, then run `openoutreach find 10` without emails to test qualification quality at zero cost. Only after you trust the reasons should you spend credits on verified addresses and sending.

Official sources

1. eracle/OpenOutreach on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README