# How to Use `bun els` for Effect Language Service Inspection in Magnitude Development

> Learn to use bun els for Effect Language Service inspection in Magnitude development. Explore Effect-TS constructs and dependency graphs without running your application.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: how-to-guide
- Published: 2026-09-06

---

**`bun els` is the built-in Effect Language Service CLI that lets you explore Effect-TS constructs and dependency graphs in the Magnitude repository without running the application.**

Magnitude is built on **Effect-TS** as its core framework, and the repository ships with a powerful Bun-integrated tool called the **Effect Language Service (ELS)**. This article explains how to use `bun els` commands to inspect services, layers, errors, and their dependency relationships—essential for understanding the codebase's dependency injection architecture.

## What Is `bun els` in Magnitude?

The Effect Language Service is a read-only CLI tool designed specifically for Effect-TS codebases. In Magnitude, it is configured as a Bun command that analyzes TypeScript modules and extracts structured information about Effect constructs.

According to the **AGENTS.md** file at the root of the repository, ELS provides two primary commands:

- **`bun els overview`** – Lists all exported Effect symbols (services, layers, errors) from a target file
- **`bun els layerinfo`** – Displays hierarchical layer dependency graphs for debugging DI wiring

These commands work against any TypeScript file in the workspace, making them invaluable for navigating Magnitude's modular package structure.

## Running `bun els overview` to Inspect Effect Exports

The `overview` command scans a module and categorizes its exported Effect-TS constructs. This is the fastest way to understand what a package exposes without reading source code.

### Command Syntax

```bash
bun els overview --file <path-to-ts-file>

```

### Example: Analyzing the Agent Package Entry Point

The most common entry point in Magnitude is the agent package. Run this command from the repository root:

```bash
bun els overview --file packages/agent/src/index.ts

```

### Expected Output Structure

```

🚀 Services
  ├─ CodingAgent
  ├─ ExecutionManager
  └─ AgentRoutingProjection

🧱 Layers
  ├─ AgentLayer
  ├─ ExecutionLayer
  └─ ProjectionLayer

❗ Errors
  ├─ classifyUnknownError
  └─ present

```

This output reveals three critical categories:

- **Services** – Effect services tagged with `Context.Tag`, injectable throughout the application
- **Layers** – `Layer` constructors that compose together to build the dependency graph
- **Errors** – Error constructors and handlers defined in the module

The output format is emoji-delimited for quick visual scanning, following conventions documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md).

## Running `bun els layerinfo` to Debug Dependency Injection

The `layerinfo` command exposes how Effect layers compose together—critical for spotting circular dependencies or missing layer requirements.

### Command Syntax

```bash
bun els layerinfo --file <path-to-ts-file>

```

### Example: Layer Graph for the Agent Package

```bash
bun els layerinfo --file packages/agent/src/index.ts

```

### Expected Output Structure

```

AgentLayer
 ├─ ClientCommonLayer
 │   └─ SdkLayer
 └─ StorageLayer
     └─ SqliteLayer

```

This tree structure shows:

- **AgentLayer** as the root layer exposed by the package
- **ClientCommonLayer** and **StorageLayer** as direct dependencies
- Deeper nesting for transitive dependencies (e.g., `SdkLayer`, `SqliteLayer`)

Use this output to verify that layer composition matches architectural intent and to identify where unprovided layers might cause runtime failures.

## Using `bun els` on Specific Modules

Beyond the main entry point, ELS works on any module in the repository. Target specific projections, services, or utilities for granular inspection.

### Example: Inspecting a Turn Projection

```bash
bun els overview --file packages/agent/src/projections/turn.ts

```

```bash
bun els layerinfo --file packages/agent/src/projections/turn.ts

```

Commands like these help isolate the Effect footprint of individual features during development or code review.

## Architecture Context: Why ELS Output Is Reliable in Magnitude

The Magnitude codebase follows strict **Effect-TS native** patterns documented in [`design/standards/effect-ts.md`](https://github.com/magnitudedev/magnitude/blob/main/design/standards/effect-ts.md). Key conventions include:

- All services registered via `Context.Tag` with explicit type signatures
- All dependency injection configured through `Layer` composition
- No hidden side effects or runtime service lookups

Because the entire architecture adheres to these patterns, `bun els` produces complete and accurate results. There are no "leaky" constructs that evade static analysis.

## Key Reference Files

| File | Purpose |
|------|---------|
| [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) | Central documentation for ELS commands and Effect conventions |
| [`packages/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/index.ts) | Primary agent API entry point—most common ELS target |
| [`packages/client-common/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/packages/client-common/AGENTS.md) | Client-side state patterns and layer usage |
| [`design/standards/effect-ts.md`](https://github.com/magnitudedev/magnitude/blob/main/design/standards/effect-ts.md) | Formal design specification for Effect-TS patterns |

Consult [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) first when integrating ELS into your workflow. It contains the authoritative command reference and architectural guidance.

## Summary

- **`bun els overview --file <path>`** lists all Effect services, layers, and errors exported by a module
- **`bun els layerinfo --file <path>`** displays hierarchical layer dependency graphs
- Both commands target [`packages/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/index.ts) for high-level API exploration
- ELS output is trustworthy throughout Magnitude due to strict Effect-TS native patterns
- The tool supports read-only code exploration without running the application

## Frequently Asked Questions

### What does `bun els` stand for in the Magnitude repository?

ELS stands for **Effect Language Service**, a Bun-integrated CLI tool for static analysis of Effect-TS code. It is distributed with Magnitude as a repository-local dependency.

### Why is the agent package entry point the most common ELS target?

[`packages/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/index.ts) aggregates the public API of Magnitude's core agent system, including its service definitions, layer compositions, and error types. Running ELS against this file provides a complete map of the agent's Effect footprint.

### Can `bun els` detect circular dependencies in layers?

Yes—the `layerinfo` command outputs the layer hierarchy as a tree. Circular references would appear as repeated nodes in this structure, making them visually obvious for debugging.

### Do I need to build the project before running `bun els` commands?

No. ELS operates on TypeScript source files directly through static analysis. You can run these commands immediately after cloning the repository without any build step.