How the EGO_BROWSER_AGENT_WORKSPACE Environment Variable Is Resolved in citrolabs/ego-lite

The EGO_BROWSER_AGENT_WORKSPACE environment variable is resolved through a three-step hierarchy in package/ego-browser/src/env.ts, checking explicit user overrides, bundled skill directories, and finally defaulting to the repository's skills/ego-browser folder.

The EGO_BROWSER_AGENT_WORKSPACE environment variable determines the file system location where the Ego browser agent stores and retrieves skill files. In the citrolabs/ego-lite repository, resolution logic is centralized in the agentWorkspace() helper function within package/ego-browser/src/env.ts. This implementation provides a robust fallback chain that ensures the runtime always locates a valid workspace directory.

Three-Tier Resolution Hierarchy

The agentWorkspace() function implements a deterministic resolution strategy that prioritizes user configuration over system defaults.

Explicit Environment Variable Override

When EGO_BROWSER_AGENT_WORKSPACE is present in the environment, its value takes precedence. According to lines 9-11 in package/ego-browser/src/env.ts, the function passes the variable's value through resolvePath() to convert it to an absolute path. This allows users to specify custom workspace locations anywhere on the file system.

Bundled Skill Fallback

If the environment variable is unset, the code checks for a bundled copy of the ego-browser skill adjacent to the compiled sources. As implemented in lines 13-16, the function verifies whether SRC_DIR/ego-browser exists and returns its absolute path if found. This supports packaged distributions where skills ship alongside the compiled JavaScript.

Repository Default

When neither custom overrides nor bundled skills are available, the function falls back to the repository's default location. Lines 18-19 define this as skills/ego-browser, resolved relative to the source root two directory levels up from the current file. This default ensures the development environment works immediately after cloning without additional configuration.

Path Normalization with resolvePath()

The resolvePath() helper (lines 21-25) performs essential path transformations before returning the final absolute path. Most notably, it expands a leading tilde (~) to the current user's home directory. This means setting EGO_BROWSER_AGENT_WORKSPACE=~/custom-skills correctly resolves to /home/username/custom-skills (or equivalent) before path validation occurs.

Practical Usage Examples

The following JavaScript examples demonstrate the three resolution paths in practice:

// Default resolution (no env var set)
console.log(agentWorkspace());
// → /path/to/repo/skills/ego-browser

// Explicit absolute path override
process.env.EGO_BROWSER_AGENT_WORKSPACE = "/custom/skill/path";
console.log(agentWorkspace());
// → /custom/skill/path

// Home directory shortcut expansion
process.env.EGO_BROWSER_AGENT_WORKSPACE = "~/my-skill";
console.log(agentWorkspace());
// → /home/youruser/my-skill

Integration with the Learning Subsystem

The resolved workspace path is consumed throughout the browser agent, particularly by the learning subsystem defined in src/learning/index.ts (lines 201-205). After calling agentWorkspace(), the learning module uses the returned path to locate skill files for training and inference operations, logging the resolved location during initialization to aid debugging.

Summary

• Explicit override takes precedence: Setting EGO_BROWSER_AGENT_WORKSPACE forces the runtime to use your specified path via resolvePath() in package/ego-browser/src/env.ts.
• Tilde expansion supported: Paths starting with ~ automatically expand to the user's home directory before resolution completes.
• Three-tier fallback: The system checks environment variables, then bundled skills (SRC_DIR/ego-browser), then defaults to the repository's skills/ego-browser directory.
• Learning subsystem dependency: Components like the learning system in src/learning/index.ts rely on this resolution to locate skill assets at runtime.

Frequently Asked Questions

What happens if EGO_BROWSER_AGENT_WORKSPACE is not set?

When the environment variable is absent, the agentWorkspace() function proceeds to check for a bundled skill directory at SRC_DIR/ego-browser. If that directory does not exist, it falls back to the repository default at skills/ego-browser, located two levels up from the source root in package/ego-browser/src/env.ts.

Can I use a tilde (~) in the workspace path?

Yes. The resolvePath() helper in package/ego-browser/src/env.ts (lines 21-25) automatically expands leading tildes to the current user's home directory. This allows portable configurations like EGO_BROWSER_AGENT_WORKSPACE=~/ego-skills to work correctly across different user accounts.

Which source file contains the resolution logic?

The resolution logic is implemented in package/ego-browser/src/env.ts within the agentWorkspace() function (lines 9-19), with path normalization handled by resolvePath() (lines 21-25) in the same file.

How does the learning subsystem use this path?

The learning subsystem in src/learning/index.ts (lines 201-205) calls agentWorkspace() during initialization to determine where skill files are stored. It logs the resolved path and uses it to locate training data and skill configurations required for browser automation tasks.

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