What Is the Purpose of the `cmd` Directory in ego-lite?

The ego-lite repository does not contain a cmd directory, so it serves no architectural purpose in this codebase.

The cmd folder is a common convention in Go projects where entry-point binaries are organized, but citrolabs/ego-lite follows a different structure. All source code lives under package/ego-browser/ and skills/ego-browser/, with the CLI entry point located directly in package/ego-browser/src/index.ts.

Understanding the ego-lite Directory Structure

Unlike traditional Go projects that use cmd/ for command-line tools, ego-lite is a TypeScript-based project. The repository organizes code by package and skill domains rather than by binary entry points.

The main directories are:

• package/ego-browser/ — Core harness containing the browser automation engine
• skills/ego-browser/ — Skill package definitions and wrappers
• AGENTS.md — High-level agent interface documentation

Where the CLI Entry Point Actually Lives

In package/ego-browser/src/index.ts, the runMain() function serves as the de facto entry point. This file checks if it's being invoked directly and executes the main logic:

// package/ego-browser/src/index.ts
if (require.main === module) {
  runMain(); // reads JavaScript from stdin and executes it
}

The runMain() function is implemented in package/ego-browser/src/run.ts, which handles the execution flow. Helper functions that scripts can invoke are defined in package/ego-browser/src/helpers.ts.

Running the ego-lite CLI

Since there's no cmd directory with pre-built binaries, you invoke the tool through the built package:

node dist/out/index.js <<'JS'
globalThis.ego.help()
JS

This pattern—reading JavaScript from stdin and executing it within the harness—is how ego-lite operates without a traditional command structure.

Why No cmd Directory Matters

If you're searching for cmd expecting to find:

• Standalone executable definitions
• Separate CLI tool implementations
• Binary build targets

You'll need to look in package/ego-browser/src/ instead. The architectural decision to colocate entry points with core logic reflects ego-lite's design as a library-first tool where the harness and its invocation interface share the same codebase.

Key Files Replacing cmd/ Functionality

File	Purpose
package/ego-browser/src/index.ts	CLI entry point with runMain() check
package/ego-browser/src/run.ts	Execution engine for user scripts
package/ego-browser/src/helpers.ts	Runtime helper surface exposed to scripts

Summary

• ego-lite has no cmd directory — the repository uses package/ego-browser/src/ for entry points
• Entry point: package/ego-browser/src/index.ts with conditional runMain() invocation
• Execution model: Reads JavaScript from stdin via the built package, not standalone binaries
• Architecture: Library-first design merging harness and CLI functionality

Frequently Asked Questions

Does ego-lite follow Go project conventions?

No. Despite the cmd/ directory being standard in Go, ego-lite is a TypeScript project that organizes code by functional domain (package/, skills/) rather than by binary entry points.

Where should I add a new CLI command to ego-lite?

Add logic to package/ego-browser/src/helpers.ts for new runtime capabilities, or modify package/ego-browser/src/run.ts for execution behavior changes. The entry point in index.ts rarely needs changes.

Could a cmd directory be added in the future?

Technically yes, but it would deviate from the current architecture. The project maintains CLI functionality within the core package to keep the harness and its invocation tightly coupled.

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