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

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

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:

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.

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

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

Example: Layer Graph for the Agent Package

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

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

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. 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	Central documentation for ELS commands and Effect conventions
packages/agent/src/index.ts	Primary agent API entry point—most common ELS target
packages/client-common/AGENTS.md	Client-side state patterns and layer usage
design/standards/effect-ts.md	Formal design specification for Effect-TS patterns

Consult 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 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 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.

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