How to Discover and Run Learned Site Tools and Browser Tools With ego-lite

Use siteSkills() or learnContext() to discover available capabilities, then invoke Node tools with runSiteTool() and browser tools with runSiteBrowserTool() to execute learned automation scripts.

ego-lite provides a learning subsystem that allows sites to contribute reusable automation tools—JavaScript modules that run either server-side in Node.js or client-side in the browser context. According to the citrolabs/ego-lite source code, these learned site tools enable agents to programmatically interact with specific domains using pre-defined, domain-specific logic stored in the skills/ego-browser/learnings/ directory.

Understanding Tool Types in ego-lite

ego-lite distinguishes between two execution environments for learned tools:

• Node (server-side) site tools – Execute inside the Node.js process hosting the ego-lite helpers. Ideal for file-system operations, API calls, or heavy computation. These run via the runSiteTool() helper.
• Browser (client-side) site tools – Execute in the context of the current web page using the Chrome DevTools Protocol (CDP). Perfect for DOM manipulation, data extraction, or UI interaction. These run via the runSiteBrowserTool() helper.

Both types are defined in per-site manifest.json files located under skills/ego-browser/learnings/<siteId>/.

Discovering Available Site Tools

Before invoking tools, you must identify what capabilities exist for a given URL. ego-lite provides two discovery helpers in src/helpers.ts.

Listing Skills with siteSkills()

The siteSkills() function returns a structured list of available tools for a specific URL, defaulting to the current page when called without arguments.

const skills = await siteSkills();  // Defaults to current page URL
// Returns: [{ siteId, siteName, tools: [{ toolName, toolType, ... }] }, ...]

In src/helpers.ts, siteSkills() delegates to siteSkillsForUrl() and siteSkillsForUrlCore() (lines 64–78), which traverse the skills/ego-browser/learnings/ directory and parse each site's manifest.json to match the URL against available site IDs.

Loading Full Context with learnContext()

For detailed information including tool signatures, descriptions, and example snippets, use learnContext().

const ctx = await learnContext();  // Includes knowledge notes and tool definitions
console.log(ctx.tools);

Defined in src/helpers.ts (lines 13–18), learnContext() forwards to loadLearnedContext() in src/learning/index.ts (lines 46–58), which aggregates data from the site's manifest.json and associated Markdown notes files.

Running Learned Tools

Once you have identified the siteId and toolName, execute tools using the appropriate helper based on the tool type.

Executing Node Site Tools with runSiteTool()

Invoke server-side logic using runSiteTool(), which loads and executes the tool module within the Node.js process.

// Example: Running a timeline extraction tool for x-com
const result = await runSiteTool('x-com', 'extractTimeline', { page: 1 });
console.log('Node tool result:', result);

The implementation in src/helpers.ts (lines 87–91) forwards the call to runNodeSiteTool() in src/learning/index.ts (lines 45–75). This function dynamically requires the tool's JavaScript file, resolves the exported callable, and executes it with the current helper context injected automatically.

Executing Browser Tools with runSiteBrowserTool()

For DOM-centric operations, use runSiteBrowserTool() to execute code in the browser context.

// Example: Extracting search results from Google
const html = await runSiteBrowserTool('google', 'extractSearchResults', { query: 'ego-lite' });
console.log('Extracted HTML:', html);

As implemented in src/helpers.ts (lines 99–105), this helper retrieves the raw source via loadBrowserToolSource() and evaluates it using evaluate(wrapBrowserTool(...)) (lines 78–96 in src/learning/index.ts). The wrapper injects the provided args object and returns the tool's asynchronous result from the page context.

Complete Workflow Example

This end-to-end example demonstrates discovering and invoking both tool types:

// 1. Discover tools for the current page
const { tools } = await learnContext();
console.log('Available tools:', tools.map(t => t.toolName));

// 2. Execute a Node tool
const nodeTool = tools.find(t => t.toolType === 'node');
if (nodeTool) {
  const output = await runSiteTool(nodeTool.siteId, nodeTool.toolName, { foo: 'bar' });
  console.log('Node output:', output);
}

// 3. Execute a Browser tool
const browserTool = tools.find(t => t.toolType === 'browser');
if (browserTool) {
  const data = await runSiteBrowserTool(browserTool.siteId, browserTool.toolName, { query: 'ego' });
  console.log('Browser output:', data);
}

Both runSiteTool() and runSiteBrowserTool() automatically inject the helper context (helperContext()) and agent workspace path, allowing learned tools to call other ego-lite helpers like click() or goto() without additional configuration.

Summary

• Two tool types: Node tools run server-side via runSiteTool(); Browser tools run client-side via runSiteBrowserTool().
• Discovery methods: Use siteSkills() for quick listings or learnContext() for detailed signatures and examples.
• Storage location: Tool definitions reside in skills/ego-browser/learnings/<siteId>/manifest.json with implementations in the tools/ subdirectory.
• Automatic context: Helpers inject the ego-lite environment automatically, enabling seamless helper composition within learned tools.
• Source locations: Core logic lives in src/helpers.ts with implementation details in src/learning/index.ts.

Frequently Asked Questions

What is the difference between Node and Browser tools in ego-lite?

Node tools execute within the Node.js process hosting the ego-lite runtime, enabling file system access, external API calls, and server-side data processing. Browser tools execute via CDP in the context of the current web page, allowing direct DOM manipulation and client-side data extraction. Choose Node tools for backend processing and Browser tools for interacting with rendered web pages.

How does ego-lite match URLs to learned site tools?

ego-lite uses siteSkillsForUrlCore() in src/helpers.ts (lines 64–78) to traverse the skills/ego-browser/learnings/ directory, reading each site's manifest.json to match the provided URL against configured site IDs. The check-domain-learning.js logic validates domain patterns and returns the appropriate skill set for the matching site.

Can I pass custom arguments to learned tools?

Yes. Both runSiteTool(siteId, toolName, args?) and runSiteBrowserTool(siteId, toolName, args?) accept an optional args object as the third parameter. For Node tools, these arguments are passed directly to the exported function. For Browser tools, the args are serialized and injected into the page context via the wrapBrowserTool() function before execution.

Where are learned tool definitions stored in ego-lite?

Tool definitions are stored in the skills/ego-browser/learnings/<siteId>/ directory structure. Each site contains a manifest.json file listing available nodeTools and browserTools, along with their file paths and callable signatures. The actual JavaScript implementations reside in tools/*.js files, while human-readable documentation lives in notes/*.md files within the same directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}