Metadata-Version: 2.4
Name: consensus-osint
Version: 0.4.8
Summary: Expert-maintained username, email and phone intelligence with 7,900+ standardised lookup modules 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 7,900+ modules 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></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="7,900+ lookup modules" 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>
</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 list 12,356 modules and rules including overlaps; expert review tests, improves, standardises and deduplicates candidates before 7,989 enabled modules and rules enter Consensus. Experts aim to review sources weekly; the latest completed review is dated below. 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>02 October 2026</strong> &middot; Latest intake: <strong>1,181 modules + 668 site rules added</strong></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>

<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">Update<br>frequency</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">02&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">Every&nbsp;2&nbsp;days</td><td align="center"><a href="https://github.com/soxoj/maigret/commit/3d2b613cfd9a18bebc9d65bb22bcf8af13aa18ef">25&nbsp;Sep&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">Every&nbsp;1&nbsp;day</td><td align="center"><a href="https://github.com/kaifcodec/user-scanner/commit/8f4de8e7b3e68672c50ba318b2d15a9d2b4617e9">29&nbsp;Sep&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">Every&nbsp;3.5&nbsp;days</td><td align="center"><a href="https://github.com/WebBreacher/WhatsMyName/commit/062bcfe48df79fa618e96edc79dc9673f3fe5643">16&nbsp;Sep&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 and see 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). Settings changes the default for this session; each search can override it. 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.** Interactive launches notify you about new releases. Use `consensus update` with your existing installation; installer-managed copies also support automatic installation, repair and rollback.

### 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.
- **Save your investigation.** Keep named investigations with multiple saved searches, notes and relevant/unrelated decisions. Storage is local and explicit; optional recent-search history is separate.

### Reports and integrations

- **Reports and evidence graphs.** Export HTML, PDF, CSV or JSON; 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** and press **Enter**. Consensus saves both an HTML report and an interactive graph, with a separate link to open each in your browser.

## 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.

### 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 or view changes. Choose **8 Investigations** from the main menu to save searches and notes together. Newly discovered profiles are not necessarily newly created accounts; an unavailable result does not prove deletion.

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>

## Update Consensus

Run `consensus update`, or choose **Settings → Installation & updates → Install update**. The command uses your existing installer, pip, pipx, uv tool, or clean Git checkout—no migration required. It retains installed optional capability groups and verifies the updated version and catalogue signature. The interactive 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.

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://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>
