Building an Autonomous OSINT Agent with Python and Claude's Tool Use API

Introduction

Open-source intelligence (OSINT) is a critical skill for security researchers, journalists, and threat analysts. However, traditional OSINT workflows are fragmented: you manually copy data between tools, pivot across browser tabs, and keep the investigation logic in your head. When you close the terminal, the context vanishes. This article introduces OpenOSINT, an open-source Python framework that replaces this manual process with an AI agent powered by Claude's Tool Use API. You'll learn how to set up an autonomous OSINT agent that chains tools, executes real binaries, and generates structured reports—all while eliminating the risk of hallucination in tool results.

Why Manual OSINT Workflows Break Down

A typical OSINT investigation follows a predictable pattern: you start with a target email address, run holehe to detect registered platforms, note a username, then manually run sherlock across 300+ sites. Next, you switch to a browser for a HaveIBeenPwned check, open another tab for a WHOIS lookup, and repeat. Every tool is a silo, every pivot is manual, and the decision chain—what to run next, how to interpret results—resides entirely in your head.

This approach is time-consuming and error-prone. More importantly, it prevents automation at scale. An AI agent, by contrast, excels at executing step-by-step procedures and chaining tools dynamically based on intermediate findings.

What You'll Build: OpenOSINT

OpenOSINT is a modular framework with three interfaces:

• Interactive AI REPL – Type a target in natural language; the agent decides which tools to run.
• Direct CLI – Run individual tools without AI, ideal for scripting or batch operations.
• MCP Server – Expose all tools to Claude Code or Claude Desktop for seamless integration.

The agent uses Claude's Tool Use API to decide tool calls autonomously. A real session might look like:

$ openosint
openosint ❯ investigate target@example.com
  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365
  → search_username('target_user') ...

The agent saves a structured Markdown report, making the investigation reproducible and shareable.

Prerequisites

Before you begin, ensure you have:

• Python 3.9+ installed
• A Claude API key with access to the Tool Use API
• Basic familiarity with the command line
• Git installed

How Claude's Tool Use API Works

Claude's Tool Use API allows the model to call external functions (tools) during a conversation. Instead of generating text only, Claude can output structured JSON requests that trigger tool execution. The framework handles the loop: it sends user input to Claude, which may respond with a tool call; the framework executes the tool and returns the result to Claude; Claude then continues reasoning until it has enough information to answer the user.

This design makes hallucination structurally impossible for tool results—because the actual output comes from real binaries, not the model. Claude can only summarize or chain results; it cannot fabricate what a tool returns.

How to Install OpenOSINT

Clone the repository and install dependencies:

git clone https://github.com/your-org/openosint.git
cd openosint
pip install -r requirements.txt

Set your ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Then run the setup script to configure default tools:

python setup.py

How to Use the Interactive AI REPL

The REPL is the primary way to run autonomous investigations. Start it with:

python repl.py

You'll see a prompt like openosint ❯. Enter any natural language target, for example:

investigate example@example.com

The agent will decide which tools to call based on the input and intermediate results. You can also ask questions like:

show me the credentials found for that email

The REPL maintains conversation context, so you can iterate on findings without restarting.

How to Run Individual Tools from the CLI

For scripting or debugging, you can run tools directly:

python cli.py holehe email@example.com
python cli.py sherlock username
python cli.py whois example.com

Each tool outputs JSON to stdout, making it easy to pipe into other commands or log files.

How to Set Up the MCP Server

The MCP (Model Context Protocol) server exposes all OpenOSINT tools to Claude Code or Claude Desktop. Start the server:

python mcp_server.py

Then configure your Claude application to connect to http://localhost:8000. Now you can use Claude's natural language interface to run OSINT tools directly.

How the Agent Loop Works Under the Hood

The agent loop follows this sequence:

1. User input is sent to Claude with a system prompt describing available tools and their parameters.
2. Claude responds with either a final answer or a tool call in structured JSON (e.g., { "tool": "holehe", "arguments": { "email": "..." } }).
3. The framework executes the tool and returns the output to Claude.
4. Steps 2–3 repeat until Claude produces a final answer. The entire conversation and results are saved to a Markdown report.

This loop ensures that all tool results are real and verifiable. Claude never invents data—it only chains what the tools actually return.

Project Architecture

OpenOSINT is organized into three main modules:

• tools/ – Each OSINT tool (holehe, sherlock, whois, etc.) is a standalone Python script that accepts CLI arguments and returns JSON.
• agent/ – Contains the loop logic, prompt templates, and result aggregator.
• interfaces/ – Implements the REPL, CLI, and MCP server.

This separation makes it easy to add new tools or interfaces without affecting the core agent logic.

Conclusion

OpenOSINT transforms OSINT investigations from manual, siloed tasks into autonomous, reproducible workflows. By leveraging Claude's Tool Use API, you avoid hallucination in tool results and gain a scalable investigation framework. Whether you use the interactive REPL, the CLI, or the MCP server, you can now run complex OSINT chains with natural language commands. Start exploring today and let the agent do the heavy lifting.