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

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.

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

This command targets 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.

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

This analyzes 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:

[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:

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 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.
• Use bun els layerinfo --file <path> to examine layer dependency graphs in files like packages/acn/src/daemon.ts.
• ELS reveals Context.Tag origins, layer requirements, and replay policies without full compilation.
• Reference design/standards/effect-ts.md and 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 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.

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