Metadata-Version: 2.4
Name: consensus-osint
Version: 0.4.11
Summary: Expert-maintained username, email and phone intelligence with 9,700+ lookup checks from 19 open-source projects.
Author: OSINT Experts Society
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://osint.ngo
Project-URL: Repository, https://github.com/OSINT-Experts-Society/Consensus-OSINT
Project-URL: Documentation, https://github.com/OSINT-Experts-Society/Consensus-OSINT#readme
Project-URL: Issues, https://github.com/OSINT-Experts-Society/Consensus-OSINT/issues
Keywords: osint,username,email,phone,reverse-lookup,sherlock,maigret,holehe,whatsmyname
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.txt
License-File: licenses/Apache-2.0.txt
License-File: licenses/aliens_eye-LICENSE.txt
License-File: licenses/findme-LICENSE.txt
License-File: licenses/linkook-LICENSE.txt
License-File: licenses/maigret-LICENSE.txt
License-File: licenses/marple-LICENSE.txt
License-File: licenses/nexfil-LICENSE.txt
License-File: licenses/sherlock-LICENSE.txt
License-File: licenses/sherlockv2-LICENSE.txt
License-File: licenses/sherlockv2-NOTICE.txt
License-File: licenses/sreg-LICENSE.txt
License-File: licenses/telespotter-LICENSE.txt
License-File: licenses/userjoo-LICENSE.txt
License-File: licenses/vesper-LICENSE.txt
License-File: licenses/wmn-LICENSE.txt
License-File: consensus_osint/vendor/holehe/LICENSE
License-File: consensus_osint/vendor/ignorant/LICENSE
License-File: consensus_osint/vendor/numint/LICENSE
License-File: consensus_osint/vendor/socialscan/LICENSE
License-File: consensus_osint/vendor/user_scanner/LICENSE
Requires-Dist: httpx[http2,socks]<1,>=0.28
Requires-Dist: rich>=13.0
Requires-Dist: prompt-toolkit<4,>=3.0.51
Requires-Dist: phonenumbers>=8.13
Requires-Dist: dnspython>=2.6.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: PyYAML>=6.0
Requires-Dist: beautifulsoup4>=4.12
Provides-Extra: modules
Requires-Dist: aiohttp>=3.14.3; extra == "modules"
Requires-Dist: trio>=0.27; extra == "modules"
Requires-Dist: lxml>=6.1.0; extra == "modules"
Requires-Dist: curl_cffi>=0.15.0; extra == "modules"
Requires-Dist: socid-extractor>=0.0.27; extra == "modules"
Requires-Dist: requests>=2.33.0; extra == "modules"
Requires-Dist: termcolor>=2.0; extra == "modules"
Requires-Dist: colorama>=0.4; extra == "modules"
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0; extra == "pdf"
Requires-Dist: pillow>=12.3.0; extra == "pdf"
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.28.1; extra == "mcp"
Requires-Dist: PyJWT[crypto]>=2.15.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: consensus-osint[browser,mcp,modules,pdf]; extra == "all"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-wordmark-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-wordmark-light.svg">
    <img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-wordmark-light.svg" width="460" alt="Consensus">
  </picture>
</p>

<h3 align="center">Usernames. Emails. Phone Numbers. 19 Projects. One Tool.</h3>

<p align="center">By the <a href="https://osint.ngo">OSINT Experts Society</a></p>

<p align="center">A unified lookup tool combining 9,700+ modules and site rules from 19 open-source projects, maintained by our experts, with a weekly review target.</p>

<p align="center"><a href="#install"><strong>Install</strong></a> &middot; <a href="#see-consensus-in-action">See it in action</a> &middot; <a href="#key-features">Features</a> &middot; <a href="#compare">Compare</a> &middot; <a href="#updates">Updates</a></p>

<p align="center">
  <a href="#compare"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-projects.svg" alt="19 projects combined" height="24"></a>
  <a href="#key-features"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-modules.svg" alt="9,700+ lookup modules and site rules" height="24"></a>
  <a href="#why-consensus"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-review.svg" alt="Expert review: weekly target" height="24"></a>
  <a href="#tested-platforms"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-windows.svg" alt="Tested on Windows" height="24"></a>
  <a href="#tested-platforms"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-linux.svg" alt="Tested on Linux" height="24"></a>
</p>

<p align="center">
  <a href="https://osint.ngo"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-website.svg" alt="Visit the OSINT Experts Society website" height="24"></a>
  <a href="https://x.com/i/communities/1830313810718015507"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-x.svg" alt="Join the OSINT Experts Society X community" height="24"></a>
  <a href="https://www.linkedin.com/groups/13047129/"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-linkedin.svg" alt="Join the OSINT Experts Society LinkedIn group" height="24"></a>
  <a href="https://www.reddit.com/r/OSINTExperts/"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-reddit.svg" alt="Join the OSINT Experts Society Reddit community" height="24"></a>
</p>

<p align="center">
  <a href="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-home-redacted.png"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-home-redacted.png" width="920" alt="Consensus application start screen with username, email, phone and bulk search options"></a>
</p>

## Why Consensus

<p align="center">
  <picture>
    <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-process-dark-mobile.svg">
    <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-process-light-mobile.svg">
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-process-dark.svg">
    <img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-process-light.svg" width="920" alt="How Consensus works: 19 source projects feed expert review, testing and integration. Consensus has 9,778 enabled modules and site rules in the 16 October inventory; the source-count snapshot is dated 3 October. Default searches select relevant modules, remove duplicate routes and present unified results.">
  </picture>
</p>

<!-- maintenance-summary:start -->
<p align="center"><sub>Last expert review: <strong>16 October 2026</strong> &middot; Latest accepted intake: <strong>13 modules + 1,782 site rules added</strong> &middot; 11 module and 161 site candidates remain disabled with specific acceptance holds</sub></p>
<!-- maintenance-summary:end -->

## Compare

<p><strong>Combined coverage. Maintained modules. Consistent results.</strong> One installation and update process replaces managing separate tools and reconciling their results.</p>

<details open>
<summary><strong>Full comparison: Consensus and its 19 source projects</strong></summary>

<p align="center">
<sub>Counts are a documented snapshot from 3 October 2026. Scroll the table horizontally on smaller screens.</sub>
</p>

Lookup activity for **User Scanner, Maigret and WhatsMyName** was rechecked for **17 September–16 October 2026 (30 complete UTC days)**. Their entries count distinct days with non-merge changes to lookup files, not releases or a promised update schedule. Other frequency figures retain the six-month snapshot ending 3 October; they are historical median gaps, not commitments.

<div align="center">
<table align="center">
  <thead>
    <tr><th align="left">Tool</th><th align="center">Username</th><th align="center">Email</th><th align="center">Phone</th><th align="center">Duplicate<br>ratio</th><th align="center">Observed lookup<br>update activity</th><th align="center">Last&nbsp;module<br>update</th></tr>
  </thead>
  <tbody>
    <tr><td align="left"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-wordmark-dark.svg"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-wordmark-light.svg" width="120" alt="Consensus"></picture><br><strong>Combined solution</strong></td><td align="center"><strong>7,782</strong></td><td align="center"><strong>205</strong></td><td align="center"><strong>2</strong></td><td align="center"><strong>Deduplicated</strong><br><sub>default searches</sub></td><td align="center"><strong>Weekly review<br>target</strong></td><td align="center">16&nbsp;Oct&nbsp;2026</td></tr>
    <tr><td align="left"><a href="https://github.com/soxoj/maigret/tree/b6642744988e7e6c2d21f75db60ec3093019ba25">Maigret</a></td><td align="center">5,483</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>40.8%</strong><br><sub>5,482/5,483&nbsp;mapped</sub></td><td align="center">8 update days<br><sub>in the 30-day window</sub></td><td align="center"><a href="https://github.com/soxoj/maigret/commit/ec2d90ce19ffd419a4467997edf6c0e9cdf14e1f">10&nbsp;Oct&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/kaifcodec/user-scanner/tree/780d077a468035c6afd6b4a0f987317db651528b">User Scanner</a></td><td align="center">2,511</td><td align="center">211</td><td align="center">—</td><td align="center"><strong>68.9%</strong><br><sub>2,575/2,722&nbsp;mapped</sub></td><td align="center">13 update days<br><sub>in the 30-day window</sub></td><td align="center"><a href="https://github.com/kaifcodec/user-scanner/commit/3518f8430219570f2717e305e1787ab34040918e">15&nbsp;Oct&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/arxhr007/Aliens_eye/tree/b1316648fe0e648469d30512bb0535ebc8c4bbc7">Aliens Eye</a></td><td align="center">840</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>65.4%</strong><br><sub>837/840&nbsp;mapped</sub></td><td align="center">Too few updates</td><td align="center"><a href="https://github.com/arxhr007/Aliens_eye/commit/eb10623492e1e171ff2d7d9cfc043a4a0a0e493a">10&nbsp;Jun&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/WebBreacher/WhatsMyName/tree/062bcfe48df79fa618e96edc79dc9673f3fe5643">WhatsMyName</a></td><td align="center">716</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>60.8%</strong><br><sub>716/716&nbsp;mapped</sub></td><td align="center">3 update days<br><sub>in the 30-day window</sub></td><td align="center"><a href="https://github.com/WebBreacher/WhatsMyName/commit/ec273f81aa1b8728a932589dcba71c6894001acc">15&nbsp;Oct&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/sherlock-project/sherlock/tree/e40a45ec2a074b90703b3b4b842c8a3adbd6ada3">Sherlock</a></td><td align="center">481</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>98.5%</strong><br><sub>479/481&nbsp;mapped</sub></td><td align="center">Too few updates</td><td align="center"><a href="https://github.com/sherlock-project/sherlock/commit/dca64e35d36217335fb45373cde4891226aae182">28&nbsp;Apr&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/0xSaikat/findme/tree/85a860357f9b6a0df2dfb16ccd495fef93a5dfa1">FindMe</a></td><td align="center">412</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>99.8%</strong><br><sub>410/412&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/0xSaikat/findme/commit/ce2d34c54ed109f56fe798cda6171ce1f93b331d">14&nbsp;Jan&nbsp;2025</a></td></tr>
    <tr><td align="left"><a href="https://github.com/Yvesssn/DetectDee/tree/551817c911ddf3a25eba9d4addb56df1e15b8f2b">DetectDee</a></td><td align="center">375</td><td align="center">3</td><td align="center">4</td><td align="center"><strong>82.5%</strong><br><sub>380/382&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/Yvesssn/DetectDee/commit/6f54e661f2afdfe2a297dd54ee7d7cbab476dbca">19&nbsp;Jul&nbsp;2023</a></td></tr>
    <tr><td align="left"><a href="https://github.com/thewhiteh4t/nexfil/tree/c540238dd510b865daac1eb59a328f8fa68b1ce5">Nexfil</a></td><td align="center">328</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>89.3%</strong><br><sub>327/328&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/thewhiteh4t/nexfil/commit/f1249e15baf453bb807fff03f75c73b993b71210">14&nbsp;Aug&nbsp;2023</a></td></tr>
    <tr><td align="left"><a href="https://github.com/ibnaleem/gosearch/tree/8c41d1e7f0fad9cb4bf9fb11f5bb096c90ac9027">GoSearch</a></td><td align="center">306</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>92.6%</strong><br><sub>306/306&nbsp;mapped</sub></td><td align="center">Every&nbsp;47&nbsp;days</td><td align="center"><a href="https://github.com/ibnaleem/gosearch/commit/8c41d1e7f0fad9cb4bf9fb11f5bb096c90ac9027">30&nbsp;Sep&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/krishpranav/vesper/tree/6f861692d7a37b5d001ce188477fc65854566043">Vesper</a></td><td align="center">299</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>96.6%</strong><br><sub>298/299&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/krishpranav/vesper/commit/0f08adab6485fcce8f4d74f638cde56127746a3b">20&nbsp;Jun&nbsp;2021</a></td></tr>
    <tr><td align="left"><a href="https://github.com/n0tr00t/Sreg/tree/ed11d094d490b4732239ad8715f3734bfd7e91a7">Sreg</a></td><td align="center">51</td><td align="center">50</td><td align="center">50</td><td align="center">Not comparable</td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/n0tr00t/Sreg/commit/64a831ea412b911971eaa4a7732a2527ddb0d244">23&nbsp;Mar&nbsp;2015</a></td></tr>
    <tr><td align="left"><a href="https://github.com/megadose/holehe/tree/14da70f588538936b20d238783c5e28a0772a2b3">Holehe</a></td><td align="center">—</td><td align="center">123</td><td align="center">—</td><td align="center"><strong>28.5%</strong><br><sub>123/123&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/megadose/holehe/commit/04efb43b9106a04b7afe80b2e5480cc4ef921710">24&nbsp;Jul&nbsp;2024</a></td></tr>
    <tr><td align="left"><a href="https://github.com/JackJuly/linkook/tree/1c893599886656c17bf4fe0dadfc1e2deb5c6b28">Linkook</a></td><td align="center">64</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>96.9%</strong><br><sub>64/64&nbsp;mapped</sub></td><td align="center">Too few updates</td><td align="center"><a href="https://github.com/JackJuly/linkook/commit/ffd9f2a33a6ad740ec062c30b099cfe7a6d00298">30&nbsp;Sep&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/ar33s0/UserJoo/tree/01036cff670e5ddd197bc6fbcf25d45a810a2503">UserJoo</a></td><td align="center">29</td><td align="center">—</td><td align="center">—</td><td align="center"><strong>6.9%</strong><br><sub>29/29&nbsp;mapped</sub></td><td align="center">Every&nbsp;4&nbsp;days</td><td align="center"><a href="https://github.com/ar33s0/UserJoo/commit/b41f685cff4ec8ae5aacb8ed8fc29e14f50ea2c0">03&nbsp;Sep&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/iojw/socialscan/tree/5ae42d0f82b0ebd717b3ae52b693b4ececa902b1">Socialscan</a></td><td align="center">6</td><td align="center">6</td><td align="center">—</td><td align="center"><strong>91.7%</strong><br><sub>12/12&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/iojw/socialscan/commit/87a4512deb30d1ffd84584acca40168e5c10f203">21&nbsp;Jan&nbsp;2024</a></td></tr>
    <tr><td align="left"><a href="https://github.com/whoamitang/numint/tree/9186c35ad0836e8094bfa1a0e264fe6e01a82823">Numint</a></td><td align="center">—</td><td align="center">—</td><td align="center">5</td><td align="center"><strong>60.0%</strong><br><sub>5/5&nbsp;mapped</sub></td><td align="center">Too few updates</td><td align="center"><a href="https://github.com/whoamitang/numint/commit/ac36acb6b7a0a3ff0cc7778389184333a31e2230">12&nbsp;Jul&nbsp;2026</a></td></tr>
    <tr><td align="left"><a href="https://github.com/megadose/ignorant/tree/40b3eb734ef3d55e6d16eb314e49dbf520fa1f64">Ignorant</a></td><td align="center">—</td><td align="center">—</td><td align="center">3</td><td align="center"><strong>100.0%</strong><br><sub>3/3&nbsp;mapped</sub></td><td align="center">No updates<br>in 6 months</td><td align="center"><a href="https://github.com/megadose/ignorant/commit/b646cf086e8542ccfbeda951aee38fdd15d758a0">24&nbsp;Mar&nbsp;2021</a></td></tr>
    <tr><td align="left"><a href="https://github.com/hanyxd/sherlockV2">SherlockV2</a></td><td align="center" colspan="3">Unverified (repository unavailable)</td><td align="center">Unverified</td><td align="center">Unverified</td><td align="center">Unverified</td></tr>
    <tr><td align="left"><a href="https://github.com/sharsil/mailcat/tree/7f61a59b68c594ea894bfc364517f08d23b07752">Mailcat</a></td><td align="center" colspan="3">26 mailbox-provider checks</td><td align="center">Not comparable</td><td align="center">Too few updates</td><td align="center"><a href="https://github.com/sharsil/mailcat/commit/7f61a59b68c594ea894bfc364517f08d23b07752">05&nbsp;Sep&nbsp;2026</a></td></tr>
  </tbody>
</table>
</div>

</details>

## Key features

### Coverage and maintenance

- 🛠️ **Expert-maintained coverage.** Our team aims to review all 19 source projects weekly and evaluates new OSINT projects as they emerge. The latest completed review is dated above. Suitable modules are tested, improved and integrated; broken modules are retired.
- 🔄 **Keep investigations current.** Search newly added lookup sources, or recheck saved identifiers with the original limit and filters. Compare newly discovered matches, changed details and inconclusive results.
- 🎛️ **Choose your search size.** Guided username and email searches offer **Quick** (up to 300 checks), **Custom** (enter a number) and **Full** (all eligible checks). Use settings once, or choose **Settings → Save these preferences as my defaults** for future sessions. Eligible enrichment stays enabled, and email domain analysis is separate.
- ⚖️ **Balanced limited searches.** `--top 500` and Quick aim for 50/50 site checks and modules, filling unused slots from the other group. Limits apply per username/email after exclusions; email's module-only plan uses the available modules. Stored ranks order each group, not verified current popularity. Modules do not guarantee returned enrichment. Continue the full search to add remaining coverage, or use `--full`.
- 🔔 **Automatic update checks.** See new-release notices inside Consensus and update with your existing installation. See [Updates](#updates).

### Investigation workflow

- 🔀 **Follow new leads automatically.** Enable recursive search to investigate usernames, email addresses and linked accounts discovered in your results, expanding your search without entering each new lead yourself.
- 👤 **Enriched results.** Go beyond found/not found with available profile details, including names, biographies and linked accounts. Inspect the returned information, see source coverage and compare details across results.
- 📋 **Bulk search and advanced controls.** Process lists, generate username variations, filter sites and categories, and use proxies.
- 🔁 **Retry unsuccessful checks.** Retry errors, blocks and inconclusive responses without repeating completed checks. Rate-limited checks cool down first. A proxy may help some access blocks, but is not a guaranteed fix or a reason to bypass rate limits.
- 💾 **Save your investigation.** Keep named investigations, notes and review decisions. Saved/unsaved status and exit prompts help protect results. Storage is local and explicit; recent-search history is optional.
- 🩺 **Check your setup.** **Settings → Setup / health** shows local installation details, optional dependencies, missing keys and report locations without contacting providers.

### Reports and integrations

- 📂 **Reports and evidence graphs.** Choose a format when saving: HTML, PDF, CSV, JSON and more. Explore connections visually, with XMind and Neo4j exports also available.
- 🤖 **AI integration.** Optional MCP support connects compatible assistants to Consensus lookups and results.

## See Consensus in action

Follow a search from query to evidence. Click any image to enlarge. Console screenshots have personal details redacted; report and graph examples use fictional data.

<p align="center"><strong>Try the output before installing:</strong> <a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/raw/refs/heads/main/consensus_osint/templates/consensus-example-outputs.zip">Download the example report and interactive graph (.zip)</a><br><sub>Extract the ZIP and open either HTML file in your browser. Both use fictional profiles and work offline.</sub></p>

<table>
  <tr>
    <td width="50%" valign="top">
      <strong>1. Start a search</strong><br>
      <sub>Username, email, phone and bulk searches from one menu.</sub><br><br>
      <a href="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-home-redacted.png"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-home-redacted.png" width="440" alt="Consensus console home screen with search options and personal details redacted"></a>
    </td>
    <td width="50%" valign="top">
      <strong>2. Follow your search</strong><br>
      <sub>See progress, matches and enrichment; preview, pause or stop at any time.</sub><br><br>
      <a href="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-search-redacted.png"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-search-redacted.png" width="440" alt="Consensus username search in progress, showing progress and result counts with personal details redacted"></a>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <strong>3. Review the report</strong><br>
      <sub>Search findings, profile details and source coverage.</sub><br><br>
      <a href="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-demo-report.png"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-demo-report.png" width="440" alt="Actual Consensus HTML report showing fictional profile findings, filters and returned details"></a>
    </td>
    <td width="50%" valign="top">
      <strong>4. Explore the evidence graph</strong><br>
      <sub>Follow connections and inspect the supporting evidence.</sub><br><br>
      <a href="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-demo-graph.png"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-demo-graph.png" width="440" alt="Actual Consensus interactive graph showing fictional query, result and source-site nodes with an evidence panel"></a>
    </td>
  </tr>
</table>

After a search, choose **Save report**, select a format, then confirm the location. The default **HTML report + graph** saves two files, with a separate link to open each in your browser. All outcomes are saved, including those hidden by display filters.

## Install

The Windows install bundle is recommended for most users. It sets up Python and the required dependencies automatically.

### Windows quick install — no coding needed

1. 📥 **Download:** open [Releases](https://github.com/OSINT-Experts-Society/Consensus-OSINT/releases), find **Assets**, and save the `Consensus-<version>.zip` installer to your Downloads folder.
2. 📦 **Extract it:** right-click the ZIP, select **Extract All**, then **Extract**.
3. ⚙️ **Install:** open the extracted folder, double-click **Install.cmd**, and wait for installation to finish. Keep your internet connection on.
4. 🚀 **Open Consensus:** choose **Launch Consensus** when prompted, or press the Windows key, type **Consensus**, and open the Start menu shortcut.
5. 🔎 **Start searching:** choose **Username**, **Email** or **Phone**, then enter what you want to look up.

### Tested platforms

The published **0.4.10** release was tested on **Windows and Linux**, including installation/update checks. Native macOS testing was not completed for that release; macOS installation instructions are available, but it is not labelled as tested. Platform tests do not guarantee that every external provider is available.

### Other installation options

For macOS, Linux, PyPI or a terminal-based installation, use the options below.

| Platform | Double-click installer | Bundle from terminal | Install from PyPI | Install from source |
| --- | --- | --- | --- | --- |
| **Windows** | **Install.cmd** | Run `.\Install.cmd` in CMD or PowerShell. | [Python + PyPI instructions](#install-from-pypi) | [Git + Python instructions](#install-from-source) |
| **macOS / Linux** | Use the terminal option. | Run `sh install.sh`. | [Python + PyPI instructions](#install-from-pypi) | [Git + Python instructions](#install-from-source) |

Both bundle options set up Python and dependencies for you. Run terminal commands from the extracted folder. Internet access is required.

After a bundle install, open a new terminal:

```console
consensus
```

### Install from PyPI

Already have Python 3.10 or newer? Install Consensus with its lookup modules and PDF reporting:

```console
python -m pip install "consensus-osint[modules,pdf]"
consensus
```

Use `py` instead of `python` on Windows, or `python3` on macOS/Linux, if required.

## Start searching

1. Choose **Username**, **Email**, **Phone** or **Bulk search**.
2. Enter your query. Include the country code for phone numbers.
3. Review matches, open enriched details, then **Save report**, **Filter results** or **Search again**.

Choose **I Follow up** in results to continue a full search, search new sources, recheck, retry unsuccessful checks or view changes. Choose **8 Investigations** to save searches and notes together. Newly discovered profiles are not necessarily newly created accounts; an unavailable result does not prove deletion. Follow-ups retain starting identifiers and filters, but do not repeat recursive expansion or optional web-search/mailbox discovery.

Press **Esc** or **S** to stop an interactive scan; type `exit` to quit. Enable **Recent searches** in Settings to keep up to 10 searches locally. History is off by default.

<details>
<summary>Command-line examples</summary>

```console
consensus user "YOUR_USERNAME"
consensus email "YOUR_EMAIL"
consensus phone "+COUNTRY_CODE_AND_NUMBER"
consensus user "YOUR_USERNAME" -o reports/username.html
```

Explore more with `consensus --help` or `consensus examples`.

</details>

<a id="update-consensus"></a>

## Updates

🔔 **Check inside Consensus.** On launch, Consensus checks for a new version in the background and shows an update notice when one is available. **(latest)** beside the version means a recent successful check confirmed it. You can also open **Settings → Installation & updates → Check now**; offline or proxy-restricted checks may leave the latest version unknown.

⬆️ **Get the latest version from your command line.** Close Consensus, then run this in **Command Prompt or PowerShell** on Windows, or **Terminal** on macOS/Linux—not at the `consensus>` prompt:

```console
consensus update
```

Alternatively, choose **Settings → Installation & updates → Install update**. Updates use your existing installer, pip, pipx, uv tool, or clean Git checkout—no migration required. Installed optional capabilities are retained. The interface asks before closing so you can save results first.

Restart Consensus after updating. Source updates fast-forward the checkout's configured branch; installed source copies are reinstalled in the same environment. Local edits, pins, locked projects and OS-managed Python are protected: if an automatic update is unsafe, the command explains what needs attention rather than forcing it.

If a Consensus scan proxy or Tor default is configured, update checks and downloads will not silently connect directly. Manual updates explain this limitation; use your existing installation tool with its own proxy configuration. Installer-managed rollback remains available locally.

Interactive launches show public-release notices and one-time new-version summaries. Installer-based copies retain automatic updates by default; other installations update only when requested. Checks run in the background, use a one-hour cache and stay off for redirected output, proxy/Tor sessions or `--no-update-check`.

<details>
<summary><strong>Repair, rollback and update controls</strong></summary>

Open **Settings → Installation & updates** to check versions and install updates. Restart, repair, rollback and bundle selection require an installer-managed copy with saved environments.

To update from an installer ZIP, extract it, then select **Choose bundle** in Settings and choose the extracted folder, or run its installer. Restart to apply changes.

| Command | Action |
| --- | --- |
| `consensus update --repair` | Repair the installed version. |
| `consensus update --rollback` | Restore the previous version and pause automatic upgrades. |

A manual update resumes upgrades after rollback. Set `CONSENSUS_AUTO_UPDATE=0` for notifications only, or `CONSENSUS_NO_UPDATE_CHECK=1` to disable startup checks.

**Moving from a source install?** Choose **Switch to managed installation** in the Updates screen and select the extracted bundle. Your configuration and report locations are preserved.

</details>

## Advanced installation

### Install from source

Requires [Python 3.10+](https://www.python.org/downloads/) and [Git](https://git-scm.com/downloads).

```console
git clone https://github.com/OSINT-Experts-Society/Consensus-OSINT.git
cd Consensus-OSINT
python -m venv .venv
```

**Windows**

```console
.\.venv\Scripts\python.exe -m pip install ".[modules,pdf]"
.\.venv\Scripts\consensus.exe
```

**macOS / Linux**

Use `python3` above if required, then:

```console
.venv/bin/python -m pip install ".[modules,pdf]"
.venv/bin/consensus
```

Add `mcp` to the extras for AI integration, for example `".[modules,pdf,mcp]"`. PDF support is included in managed installs.

## Use Consensus with AI assistants

<details>
<summary><strong>Connect an assistant using Model Context Protocol (MCP)</strong></summary>

Install the MCP extra in your Python environment:

```console
python -m pip install --upgrade "consensus-osint[modules,pdf,mcp]"
```

For clients using an `mcpServers` configuration, add:

```json
{
  "mcpServers": {
    "consensus": {
      "command": "consensus",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}
```

Use the full path to the installed `consensus` executable if your assistant cannot find it. Client configuration screens vary; select a local stdio server and use the same command and arguments.

The server provides username, email and phone lookups, paginated results and detailed evidence. Example request: **“Use Consensus to search my username YOUR_USERNAME across up to 20 sources, then summarise the matches and inconclusive results.”** Lookups contact external services; review your assistant's tool permissions before running them. Returned profile text is evidence, not instructions.

</details>

## Common questions

**What does Consensus search?** Usernames, email addresses and phone numbers using the installed lookup catalogue. Coverage varies by identifier type, enabled modules and available provider access.

**How are the 19 projects combined?** Their lookup modules and rules are standardised into one catalogue. Default searches reconcile overlapping lookup routes before presenting unified results; Consensus does not simply run 19 complete searches.

**Are results just found or not found?** Available evidence can include profile names, biographies and linked accounts, alongside each result's status. A match is a lead, not proof of a person's identity; errors and inconclusive responses do not establish absence.

**How do I install and update it?** Choose the [installer or PyPI](#install), then follow the [update instructions for your installation](#update-consensus).

## Join the community

<p align="center"><strong>Want your OSINT project evaluated for inclusion?</strong><br><a href="https://osint.ngo">Contact the OSINT Experts Society</a></p>

<p align="center">
  <a href="https://osint.ngo"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-website.svg" alt="Visit the OSINT Experts Society website" height="24"></a>
  <a href="https://x.com/i/communities/1830313810718015507"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-x.svg" alt="Join our X community" height="24"></a>
  <a href="https://www.linkedin.com/groups/13047129/"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-linkedin.svg" alt="Join our LinkedIn community" height="24"></a>
  <a href="https://www.reddit.com/r/OSINTExperts/"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-reddit.svg" alt="Join our Reddit community" height="24"></a>
</p>

<p align="center">
  <a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/blob/main/CONTRIBUTING.md"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-prs.svg" alt="PRs welcome" height="24"></a>
  <a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/OSINT-Experts-Society/Consensus-OSINT/main/consensus_osint/templates/consensus-badge-license.svg" alt="Licence: GPL-3.0-or-later" height="24"></a>
</p>

<p align="center"><a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/issues">Report an issue</a></p>

> [!IMPORTANT]
> Use responsibly. Shared details are leads, not proof of identity; verify important matches at their source.

<p align="center"><sub><a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/blob/main/THIRD_PARTY_NOTICES.txt">Third-party credits</a> &middot; <a href="https://github.com/OSINT-Experts-Society/Consensus-OSINT/blob/main/LEGAL.md">Legal &amp; privacy</a></sub></p>
