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

Introduction

Open Source Intelligence (OSINT) workflows often rely on manual chaining of disparate tools—copying output, switching terminals, and mentally tracking investigation paths. This fragmented approach is error-prone and hard to reproduce. In this article, you'll learn how to build OpenOSINT, an open-source Python framework that replaces that manual process with an AI agent capable of executing tool chains autonomously.

You'll understand how Claude's native tool-use API enables the agent, how to run investigations interactively or via scripting, and how to expose the same tools to Claude Code or Claude Desktop using an MCP server.

What Is OSINT and Why Manual Workflows Break Down

OSINT is the practice of collecting and analyzing publicly available information. Security researchers use it during penetration tests, journalists to verify identities, and threat analysts to profile infrastructure.

A typical manual workflow might start with an email address: you run holehe to find registered platforms, copy a username, run Sherlock to check 300+ sites, then switch to a browser for HaveIBeenPwned and WHOIS lookups. Every tool is a silo; every pivot is manual. The investigation logic—what to run next, what to chain, what findings mean—exists only in your head. When you close the terminal, it's gone.

OpenOSINT overcomes this by embedding an AI agent that autonomously decides which tools to invoke and in what order, then saves a structured Markdown report.

What You Will Build

By the end of this tutorial, you'll have a working OSINT agent usable in three modes:

• Interactive AI REPL – type a target in natural language; the agent decides what to run.
• Direct CLI – run individual tools without AI, ideal for scripting.
• MCP Server – expose all tools to Claude Code or Claude Desktop.

A real session looks like this:

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

The agent chains tools, executes real binaries, and produces a final report—all from a single command.

How Claude's Tool Use API Works

Claude's tool-use API lets you define a set of functions (tools) and pass them to the model. The model can then request to call a tool with specific parameters, but does not execute it. Your application performs the actual execution and returns the result back to the model. This loop repeats until the model decides the task is complete.

Key advantage: the model never sees the tool's internal code or credentials—only the output. This makes hallucination in tool results structurally impossible, because the tool either ran and returned real data, or it didn't. The agent cannot fabricate a lookup result.

Installing OpenOSINT

OpenOSINT requires Python 3.10+ and pip. Install with:

pip install openosint

You'll also need an API key for Claude (or another supported LLM). Set it as an environment variable:

export ANTHROPIC_API_KEY=your-api-key

For tools like holehe and Sherlock, ensure they are installed and available in your PATH. OpenOSINT will call them as subprocesses.

Using the Interactive AI REPL

The primary way to use OpenOSINT is via its interactive REPL. Start it with:

openosint repl

You'll see a prompt: openosint ❯. Enter a target—an email, domain, or username—and the agent will begin its investigation. Monitor the real-time output as tools are invoked. When finished, a Markdown report is saved to a reports/ folder.

The REPL supports commands like /help and /history.

Running Individual Tools from CLI

For scripting or automation, use the direct CLI to run a specific OSINT tool without invoking the AI:

openosint run holehe target@example.com
openosint run sherlock --username johndoe

This bypasses the agent loop and executes the tool directly, outputting results to stdout. Useful for integrating into existing pipelines.

Setting Up the MCP Server

OpenOSINT includes an MCP (Model Context Protocol) server that exposes all its tools to Claude Code or Claude Desktop. Start the server with:

openosint mcp-server

Then configure Claude Code to connect to it (e.g., via environment variable CLAUDE_CODE_MCP_SERVERS). This gives you an AI-powered OSINT assistant directly in your code editor.

How the Agent Loop Works Under the Hood

The agent loop follows this sequence:

1. System prompt + tool definitions are sent to Claude with the user's query.
2. Claude responds with a tool call request (e.g., search_email with parameters).
3. Your application executes the tool (subprocess call to holehe, Sherlock, etc.) and captures stdout/stderr.
4. The tool result is sent back to Claude as a new message.
5. Claude either requests another tool or outputs a final answer with the report.

This loop continues until Claude signals completion. All context is retained, so the agent can make conditional decisions based on previous results.

Conclusion

OpenOSINT demonstrates how combining an autonomous AI agent with well-defined OSINT tools can dramatically improve the speed and reproducibility of investigations. By using Claude's tool-use API, you get a system that cannot hallucinate tool outputs and can be used interactively, via scripting, or integrated into editor workflows with MCP.

Start your next investigation with openosint repl and let the agent handle the chaining.