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

> Discover the purpose of the cmd directory in ego-lite. Learn why this codebase, citrolabs/ego-lite, does not feature a cmd directory and its implications for your understanding.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: internals
- Published: 2026-08-03

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/AGENTS.md)** — High-level agent interface documentation

## Where the CLI Entry Point Actually Lives

In [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

```typescript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | CLI entry point with `runMain()` check |
| [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) | Execution engine for user scripts |
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) for new runtime capabilities, or modify [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) for execution behavior changes. The entry point in [`index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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.