# How to Use the Effect Language Service to Analyze Files in Magnitude

> Analyze Effect-TS declarations and dependencies with the Effect Language Service CLI tool in magnitudedev/magnitude. Inspect graphs and layers without full compilation.

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

---

**The Effect Language Service (ELS) is a built-in CLI tool in the magnitudedev/magnitude repository that inspects Effect-TS declarations, dependency graphs, and layer compositions without requiring a full project compilation.**

The Effect Language Service provides deterministic visibility into Magnitude's Effect-TS architecture. As implemented in the magnitudedev/magnitude codebase, this tool allows developers to analyze TypeScript files for exported services, layers, and dependency graphs directly from the command line. It is particularly useful for verifying the "package layering" contract that governs how clients, SDKs, and the ACN protocol interact.

## What Is the Effect Language Service?

The **Effect Language Service** (ELS) ships as a Bun-native CLI script within the Magnitude monorepo. It parses TypeScript source files to extract Effect-TS specific constructs including `Context.Tag` definitions, `Layer` compositions, `Effect` declarations, and `Schema` objects. Unlike traditional compilation, ELS provides a lightweight analysis that reveals import origins, dependency requirements, and replay policy annotations such as `replaySafe` or `atMostOnce`.

Because the service relies on Bun-specific Node-API bindings for Effect-TS, you must use the `bun` runtime rather than standard Node.js when invoking ELS commands.

## Analyzing Files with ELS Commands

ELS exposes two primary subcommands for file analysis: `overview` for high-level exports and `layerinfo` for detailed dependency graphs.

### Overview Command

Use `els overview` to list all Effect-TS exports in a file, including tags, layers, and schemas.

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

```

This command targets [`packages/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/index.ts), which serves as the main agent entry point and composes multiple layers. The output identifies every exported construct and its originating package.

### Layer Info Command

Use `els layerinfo` to examine the dependency graph and wiring requirements of specific layers.

```bash
bun els layerinfo --file packages/acn/src/daemon.ts

```

This analyzes [`packages/acn/src/daemon.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/daemon.ts), revealing how the ACN daemon wires layers for runtime execution, including what services each layer provides and requires.

## Interpreting ELS Output

The Effect Language Service outputs structured information about Effect-TS declarations. A typical analysis reveals:

- **Context.Tag definitions** with their types and source packages
- **Layer compositions** showing `provides` and `requires` relationships
- **Replay policies** indicating execution constraints like `atMostOnce`
- **Import origins** tracing where definitions are imported from

For example, analyzing a daemon file might produce:

```text
[Context.Tag] AgentClient
  from: @magnitudedev/sdk
  type: Tag<AgentClient>

[Layer] AgentRuntimeLayer
  provides: AgentClient
  requires: Logger, Config
  replayPolicy: atMostOnce

```

You can pipe this output to filtering tools for targeted analysis:

```bash
bun els layerinfo --file packages/acn/src/daemon.ts | grep Logger

```

## Practical Use Cases for Effect Language Service Analysis

The Effect Language Service supports several critical workflows in the Magnitude codebase.

### Verifying Layer Dependencies

Before wiring a layer into the application, run ELS to confirm all dependencies are satisfied. This prevents runtime injection errors caused by missing `Context.Tag` definitions.

### Validating RPC Contracts

Use ELS to ensure exported RPC contracts in [`packages/sdk/src/client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/client.ts) are properly declared within the `acn-protocol` boundary. This maintains the architectural separation between client implementations and protocol definitions.

### Detecting Definition Issues

ELS helps identify duplicate or missing `Context.Tag` definitions across related files. Analyze both the implementation in `packages/acn/src/...` and the SDK consumer in `packages/sdk/src/...` to confirm consistency across the client → client-common → SDK → ACN package hierarchy.

## Summary

- The **Effect Language Service** is a Bun-native CLI tool integrated into magnitudedev/magnitude for analyzing Effect-TS code.
- Use `bun els overview --file <path>` to inspect high-level exports in files like [`packages/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/src/index.ts).
- Use `bun els layerinfo --file <path>` to examine layer dependency graphs in files like [`packages/acn/src/daemon.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/daemon.ts).
- ELS reveals `Context.Tag` origins, layer requirements, and replay policies without full compilation.
- Reference [`design/standards/effect-ts.md`](https://github.com/magnitudedev/magnitude/blob/main/design/standards/effect-ts.md) and [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) for architectural context on Effect-TS conventions in Magnitude.

## Frequently Asked Questions

### What is the Effect Language Service in Magnitude?

The Effect Language Service is a specialized CLI tool that ships with the magnitudedev/magnitude repository. It analyzes TypeScript files to extract and display Effect-TS specific declarations including services, layers, errors, and dependency graphs, providing visibility into the codebase's dependency injection structure without requiring a full build.

### Why does ELS require Bun instead of Node.js?

ELS is compiled as a Bun-native script that depends on specific Node-API bindings for Effect-TS. According to the source implementation, using `bun` ensures these bindings resolve correctly, whereas standard Node.js execution would fail to load the required native modules.

### How do I interpret the replayPolicy field in ELS output?

The `replayPolicy` field indicates execution constraints for a layer, such as `atMostOnce` or `replaySafe`. These annotations, defined in Magnitude's Effect-TS standards, determine whether a layer can be re-executed during effect interruption or must run exactly one time.

### Can ELS analyze files across package boundaries?

Yes. You can run ELS on any TypeScript file within the monorepo, including [`packages/sdk/src/client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/client.ts) or ACN protocol implementations, to trace how services defined in one package are consumed in another. This cross-package analysis helps enforce Magnitude's strict layering architecture.