Automating OSINT Investigations with a Python AI Agent and Claude's Tool Use API

Open Source Intelligence (OSINT) manually involves juggling multiple tools, copying outputs, and making decisions on the fly — a process that's error-prone and mentally exhausting. This tutorial introduces OpenOSINT, an open-source Python framework that uses Claude's Tool Use API to create an autonomous OSINT agent. The agent chains tools logically, executes real binaries, and produces structured Markdown reports without hallucinating results. Below, we answer the key questions about building and using this system.

Why do traditional OSINT workflows fail, and how does an AI agent fix it?

Traditional OSINT is siloed: you manually jump from holehe to Sherlock to HaveIBeenPwned, copying usernames and URLs between tabs. Every investigative decision — what to run next, how to interpret findings — lives only in your head. When you close the terminal, the logic is lost. An AI agent changes this by using a large language model (like Claude) to autonomously decide which tools to chain based on previous results. It eliminates the mental overhead, speeds up investigations, and saves a complete, reproducible report. More importantly, the agent's design ensures that tool outputs come from real binaries, not generated guesses, making it trustworthy for security research.

What exactly is Claude's Tool Use API and how does it power autonomous OSINT?

Claude's Tool Use API allows the model to call external functions during a conversation. Instead of just generating text, Claude can request to run a specific tool — like a WHOIS lookup or a username search — and then incorporate the real output into its reasoning. The API sends a request with a list of available tools (defined as JSON schemas). When Claude decides a tool is needed, it returns a special response with the tool name and parameters. Your application then executes the real tool (e.g., a Python script) and sends the result back to Claude. This loop enables autonomous investigations where Claude plans the steps, delegates execution to actual OSINT binaries, and synthesizes findings—all without hallucinating tool outputs.

What are the three ways to use the OpenOSINT framework?

OpenOSINT offers three distinct modes. First, the Interactive AI REPL gives you a conversation-like terminal where you type a target in natural language (e.g., investigate alice@example.com) and the agent autonomously runs the right tools, showing live progress. Second, the Direct CLI lets you run individual tools like openosint holehe alice@example.com without any AI overhead — ideal for scripting and automation. Third, the MCP Server exposes all OSINT tools as resources that Claude Code or Claude Desktop can call directly, allowing you to integrate AI-powered OSINT into your existing workflow. All three modes share the same underlying tool implementations, ensuring consistency.

How do you install and set up OpenOSINT?

Installation is straightforward. First, clone the repository from GitHub. Then create a Python virtual environment and install dependencies with pip install -r requirements.txt. You'll need an Anthropic API key for Claude; set it as an environment variable ANTHROPIC_API_KEY. The framework also requires several OSINT binaries to be installed on your system: holehe, Sherlock, theHarvester, and whois, among others. The README provides a setup script for common package managers. Once everything is ready, you can start the interactive REPL with python main.py or use the CLI entry point directly. The MCP server requires an additional configuration file to define the server's endpoint.

How does the interactive AI REPL work in practice?

Start the REPL by running openosint in your terminal. You'll see a prompt like openosint ❯. Type a natural language command, for example investigate target@example.com. The agent immediately begins by calling relevant tools: it might run generate_dorks and search_email. As each tool executes, you see live status messages like → search_email('target@example.com') and then ✓ Found: Spotify, WordPress, Gravatar, Office365. The agent continues chaining tools — if a tool reveals a username, it may automatically invoke Sherlock to search across 300+ platforms. When finished, it displays a summary and saves a full Markdown report. You can also type what can I do? to get a list of available tools.

How can you run individual tools directly from the CLI?

For scripting or when you don't need AI decision-making, OpenOSINT provides a direct CLI. Usage is simple: openosint <tool-name> <arguments>. For example, openosint sherlock johndoe runs Sherlock on the username 'johndoe' and prints the results. Similarly, openosint holehe email@domain.com checks email registrations. You can pipe outputs, combine with shell scripts, or integrate into larger automation pipelines. The CLI supports all tools that the AI agent uses, so you're not limited. This mode is particularly useful for batch investigations or when you know exactly which tools you need without AI guidance.

How do you set up the MCP server for integration with Claude Code or Claude Desktop?

The MCP (Model Context Protocol) server allows Claude desktop tools to call your OSINT tools as resources. To set it up, run the MCP server script provided in the repository, which listens on a configurable port (e.g., 8000). Then configure Claude Code or Claude Desktop to point to this server endpoint. Once connected, Claude can invoke any registered OSINT tool during a conversation — for instance, asking "Check if this email is registered on any platforms" will cause Claude to call the holehe tool via your MCP server. The results come back as structured data, and Claude can use them to inform further analysis. This integration brings autonomous OSINT directly into your AI assistant without leaving your editor or desktop.

How does the agent loop ensure hallucination-free tool results?

The core design principle is that Claude never generates the tool output itself. Instead, the agent loop works as follows: Claude proposes a tool call with specific parameters. The Python framework executes the actual OSINT binary (e.g., launching Sherlock via subprocess) and captures its real output. That output is then fed back to Claude as a system message. Claude can only read and synthesize the data — it never fabricates results. This structural constraint makes hallucination in tool results impossible. The model can still hallucinate in its analysis, but the raw evidence is always factual. If you want to verify, you can re-run any tool manually with the CLI. The saved Markdown report includes both the agent's summary and the raw tool outputs for auditing.