# How to Run Learned Site Tools and Browser Tools Using ego-lite

> Learn to run site tools and browser tools with ego-lite. Discover capabilities using siteSkills() or learnContext(), then use runSiteTool() or runSiteBrowserTool() for seamless execution.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Use `runSiteTool()` for server-side Node tools and `runSiteBrowserTool()` for client-side browser tools after discovering available capabilities via `siteSkills()` or `learnContext()`.**

The ego-lite framework from [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) provides a learning subsystem that allows sites to contribute reusable automation scripts. These learned tools enable agents to invoke domain-specific logic either within the Node.js host process or directly inside the browser page context via Chrome DevTools Protocol (CDP).

## Understanding Learned Tool Types

ego-lite categorizes learned capabilities into two distinct execution environments:

- **Node (server-side) site tools** – Execute inside the Node.js process hosting the ego-lite helpers. These are ideal for file-system operations, heavy computation, or API orchestration. Invoke these using `runSiteTool(siteId, toolName, args?)`.

- **Browser (client-side) site tools** – Execute within the current page's JavaScript environment using CDP evaluation. These handle DOM-centric actions like extraction or interaction. Invoke these using `runSiteBrowserTool(siteId, toolName, args?)`.

## Discovering Available Tools

Before invoking tools, you must identify what capabilities exist for your target domain. The framework provides two discovery helpers in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

### Query Site Skills with siteSkills()

The `siteSkills()` function returns available tools matching a specific URL (defaulting to the current page). According to the source code in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 64-78), this helper chains through `siteSkillsForUrl()` to `siteSkillsForUrlCore()`, which traverses the learned-skills directory.

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

```

### Load Full Context with learnContext()

For complete site intelligence including notes, signatures, and examples, use `learnContext()`. Defined at lines 13-18 in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), this delegates to `loadLearnedContext()` in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 46-58), which reads the site's [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) and associated documentation.

```javascript
const ctx = await learnContext();  // Returns { knowledge, tools, ... }
console.log(ctx.tools);            // Array of available tool definitions

```

Both helpers rely on [`check-domain-learning.js`](https://github.com/citrolabs/ego-lite/blob/main/check-domain-learning.js) within the learning module to match URLs against site IDs in the `skills/ego-browser/learnings/` directory structure.

## Executing Learned Tools

Once you have the `siteId` and `toolName` from discovery, invoke the appropriate runner based on the tool's execution context.

### Running Node Site Tools with runSiteTool()

For server-side logic, `runSiteTool()` forwards your request to `runNodeSiteTool()` in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 45-75). This loads the tool's module, resolves the exported callable, and executes it with the current helper context.

```javascript
// Execute a Node tool for x-com that extracts timeline data
const result = await runSiteTool('x-com', 'extractTimeline', { page: 1 });
console.log('Node tool result:', result);

```

The helper automatically injects the helper context via `helperContext()` and the agent workspace path, allowing the tool to call other ego-lite helpers like `click()` or `goto()` without manual wiring.

### Running Browser Site Tools with runSiteBrowserTool()

For DOM operations, `runSiteBrowserTool()` retrieves the tool source via `loadBrowserToolSource()` and evaluates it in the page context. As implemented in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 99-105) and [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 78-96), this uses `evaluate(wrapBrowserTool(...))` to inject arguments and return the async result.

```javascript
// Execute a browser tool for google that extracts search results
const html = await runSiteBrowserTool('google', 'extractSearchResults', { 
  query: 'ego-lite' 
});
console.log('Extracted HTML:', html);

```

## Complete Workflow Example

This end-to-end example demonstrates discovery, selection by type, and execution:

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

// Step 2: Execute a Node tool if available
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);
}

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

```

## Summary

- **Discovery**: Use `siteSkills()` for quick tool listings or `learnContext()` for full site intelligence including notes and examples.
- **Node Execution**: Use `runSiteTool()` for server-side scripts that run in the Node.js process, defined in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts).
- **Browser Execution**: Use `runSiteBrowserTool()` for client-side scripts evaluated in the page context via CDP.
- **Context Injection**: Both runners automatically provide helper context and workspace paths to tools, enabling seamless integration with other ego-lite functions.
- **Storage**: Tools reside in `skills/ego-browser/learnings/{siteId}/` with manifests defining `nodeTools` and `browserTools` arrays.

## 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 framework, enabling file-system access, database operations, and complex computation. **Browser tools** execute inside the actual web page via Chrome DevTools Protocol, allowing direct DOM manipulation and extraction. Choose node tools for data processing tasks and browser tools for page interaction tasks.

### How does ego-lite match tools to a specific website?

The framework uses [`check-domain-learning.js`](https://github.com/citrolabs/ego-lite/blob/main/check-domain-learning.js) (part of the learning module) to match URLs against site IDs in the `skills/ego-browser/learnings/` directory. When you call `siteSkills()` or `learnContext()`, the system traverses this directory, validates [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) files, and returns tools associated with the matching domain.

### Can learned tools access other ego-lite helpers?

Yes. When `runSiteTool()` or `runSiteBrowserTool()` executes a tool, it automatically injects the helper context (via `helperContext()`) and the agent workspace path. This allows learned tools to invoke any standard ego-lite helper such as `goto()`, `click()`, or `type()` without requiring explicit imports or configuration.

### Where are learned tool manifests and implementations stored?

Site-specific learned data resides in `skills/ego-browser/learnings/{siteId}/`. Each site contains a [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) listing available `nodeTools` and `browserTools` with their paths and callables, a `tools/` directory containing the actual JavaScript implementations, and a `notes/` directory with Markdown documentation that populates `learnContext()` results.