Tools

OpenSentinel includes 123 built-in tools that Claude can use to interact with your system, the web, and external services.

Overview

Tools are the capabilities that Claude can invoke to take action in the real world. They are defined in src/tools/index.ts and automatically registered when OpenSentinel starts. Claude selects and executes the right tools based on context — no manual routing required.

Key characteristics of the tool system:

• Sandboxed execution — All tools run in isolated contexts with configurable timeouts
• Allowlist / Blocklist — Configure which tools are available per user or per environment
• Extensible — Add custom tools with a simple definition format
• Composable — Claude can chain multiple tools together to complete complex tasks

Shell Tools

Execute system commands and scripts directly from the AI assistant. Shell tools run in a sandboxed environment with configurable permissions.

execute_command

Run a single shell command and return its output. Commands are executed in a sandboxed shell with configurable timeout and working directory.

"List all running Docker containers"
// Claude executes: docker ps

run_script

Execute a multi-line script. Supports bash, Python, and other interpreters. Useful for complex operations that require multiple sequential commands.

"Check disk usage, find the largest files, and clean up temp directories"
// Claude generates and executes a multi-line bash script

File Tools

Full filesystem access with configurable boundaries. Claude can read, write, list, and search files within the allowed directories.

"Find all TODO comments in the src/ directory and write a summary to todos.md"
// Claude uses search_files to find TODOs, then write_file to create the summary

Browser Tools

Navigate the web, extract content, and interact with pages using headless browser automation powered by Playwright.

browse_web

Navigate to a URL and extract its content. Returns cleaned text, metadata, and optionally a screenshot. Handles JavaScript-rendered pages, cookie banners, and infinite scroll.

screenshot_page

Capture a full-page or viewport screenshot of any URL. Returns the image for analysis or inclusion in generated documents.

fill_form

Interact with web forms — fill inputs, select dropdowns, click buttons, and submit forms. Useful for automation workflows.

"Take a screenshot of the Hacker News front page and list the top 5 stories"
// Claude uses browse_web + screenshot_page, then summarizes

Search Tools

Search the web using multiple engines and perform deep multi-query research with automatic synthesis.

web_search

Perform a web search using Google, DuckDuckGo, or Brave Search. Returns titles, URLs, and snippets from the top results. The search engine is configurable via environment variables.

research_mode

Deep research mode that executes multiple search queries, visits the most relevant pages, extracts key information, and synthesizes findings into a comprehensive summary. Ideal for competitive analysis, market research, or any topic requiring multiple sources.

"Research the current state of WebAssembly adoption and create a brief report"
// Claude uses research_mode: runs 3-5 queries, visits top results, synthesizes

Vision Tools

AI-powered image understanding, text extraction, and visual capture from screens and cameras.

"Take a screenshot of my desktop and tell me what apps are open"
// Claude uses screenshot + analyze_image to describe the desktop

File Generation Tools

Generate professional documents, charts, diagrams, and images. All generated files are saved to the configured output directory and can be sent back through any channel.

"Create a PDF report about Q4 sales with a bar chart comparing monthly revenue"
// Claude uses generate_chart for the bar chart, then generate_pdf for the report

Rendering Tools

Render structured content into visual or formatted output for display or inclusion in documents.

"Render the quadratic formula as an image"
// Claude uses render_math with LaTeX: x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}

Media Tools

Process and analyze media content including video files and streams.

summarize_video

Transcribe and summarize video content. Supports local files and YouTube URLs. Extracts audio, runs speech-to-text via Whisper, and generates a structured summary with timestamps, key points, and action items.

"Summarize this YouTube video: https://youtube.com/watch?v=..."
// Claude downloads audio, transcribes with Whisper, and generates a summary

Using Tools via Library

When using OpenSentinel as an NPM library, tools are available through the chatWithTools() function. Claude automatically selects and executes tools based on the user's request.

import { configure, chatWithTools } from 'opensentinel';

configure({ CLAUDE_API_KEY: process.env.CLAUDE_API_KEY });

const result = await chatWithTools([
  { role: 'user', content: 'Take a screenshot of hackernews.com and summarize the top stories' }
]);

console.log(result.text);
// "Here are today's top Hacker News stories: ..."

console.log(result.toolCalls);
// [{ tool: 'browse_web', ... }, { tool: 'screenshot_page', ... }]

You can also restrict which tools are available:

// Only allow search and file tools (no shell access)
const result = await chatWithTools(messages, {
  allowedTools: ['web_search', 'read_file', 'write_file', 'search_files']
});

// Block specific tools
const result = await chatWithTools(messages, {
  blockedTools: ['execute_command', 'run_script']
});

Adding Custom Tools

You can extend OpenSentinel with your own tools. Each tool is a simple object with a name, description, parameters schema, and an execution function.

export const TOOLS = [
  // ... existing tools ...
  {
    name: 'check_weather',
    description: 'Get current weather for a location',
    input_schema: {
      type: 'object',
      properties: {
        location: {
          type: 'string',
          description: 'City name or coordinates'
        }
      },
      required: ['location']
    }
  }
];

case 'check_weather': {
  const { location } = input;
  const response = await fetch(
    `https://wttr.in/${location}?format=j1`
  );
  const data = await response.json();
  return {
    temperature: data.current_condition[0].temp_C,
    description: data.current_condition[0].weatherDesc[0].value,
    humidity: data.current_condition[0].humidity
  };
}