Effect Language Service

Operational guide for @effect/language-service CLI and configuration. This skill handles tooling: running commands, interpreting output, applying fixes, configuring projects. For architecture decisions about when/how to use Effect, see effect-usage-cc instead.

Command Decision Table

Always run from the project root via the local binary (bunx effect-language-service or ./node_modules/.bin/effect-language-service). Commands like check resolve paths relative to cwd — running from a subdirectory breaks them.

Interpreting Output

Diagnostic format

src/service.ts:42:3 effect(floatingEffect): This Effect is not yielded or assigned

Structure: file:line:col effect(ruleName): message. The ruleName maps directly to the diagnosticSeverity config key in tsconfig.json and to the inline suppression syntax.

Quickfix format

Output: diagnostic line followed by one or more unified diffs per available fix. Each fix has a fixName (e.g., floatingEffect_yieldStar) that can be used with --fix to filter.

Severity levels

• error — Must fix. Blocks CI (always non-zero exit)
• warning — Should fix. Blocks CI only with --strict
• message/suggestion — Informational. Never blocks CI even with --strict (emits ::notice in github-actions format, not ::error). Only blocks tsc if includeSuggestionsInTsc enabled

Key Workflows

Fix all issues in a file

# 1. See what's wrong
effect-language-service diagnostics --file src/service.ts --format pretty

# 2. See available fixes with diffs
effect-language-service quickfixes --file src/service.ts

# 3. Filter to a specific rule
effect-language-service quickfixes --file src/service.ts --code floatingEffect

Review the diffs before applying. Correctness fixes (floatingEffect, missingReturnYieldStar) are safe to apply. Style fixes (effectMapVoid, unnecessaryPipe) are preferences — check project conventions.

Onboard a new project

# 1. Interactive setup (patches TS, configures tsconfig)
effect-language-service setup

# 2. Persist patch across installs
# Add to package.json scripts: "prepare": "effect-language-service patch"

# 3. Baseline scan
effect-language-service diagnostics --project tsconfig.json --format pretty

LLM context generation

overview and layerinfo produce text output (no --format json — only diagnostics supports --format). Both emit ANSI spinner noise that must be stripped.

Clean extraction pattern (use for all text-output commands):

# Strip ANSI codes and spinner lines from any ELS text command
els_clean() {
  effect-language-service "$@" 2>/dev/null \
    | sed 's/\x1b\[[0-9;]*m//g' \
    | grep -v "^Processing file"
}

# Project map: services, layers, yieldable errors
els_clean overview --project tsconfig.json --max-symbol-depth 2

# Specific layer: provides, requires, composition order
els_clean layerinfo --file src/layers.ts --name AppLayer

# Full snapshot: overview + diagnostics + quickfixes in one shot
els_clean overview --project tsconfig.json --max-symbol-depth 2 > /tmp/els-overview.txt
effect-language-service diagnostics --project tsconfig.json --format json > /tmp/els-diag.json
els_clean quickfixes --project tsconfig.json > /tmp/els-fixes.txt

overview groups exports into "Yieldable Errors", "Services", "Layers" with file+line, type info, and JSDoc. Warning: each symbol appears at every re-export point (barrel files, index.ts). Deduplicate by source file:line — expect ~40% noise from duplicates in large projects.

layerinfo outputs a suggested Layer.provide / Layer.provideMerge composition. Requires a named, exported Layer — anonymous or inline layers are not supported. Tip: write all layers in Layer.mergeAll(...), run layerinfo, use the suggested order.

Guardrails

1. Scope your scans — Use --file when working on a single file. Full --project scans are slow in large codebases and produce noise from files you're not touching.

2. Review quickfix diffs — Correctness fixes are generally safe. Style fixes may conflict with project conventions. Anti-pattern fixes sometimes need manual adjustment.

3. Monorepo tsconfig — Always specify --project explicitly. Without it, ELS infers the tsconfig which may be wrong in monorepos with multiple configs.

4. codegen --force caution — Regenerates ALL directives in the project. Use --file to scope to a single file. Manual edits to generated blocks will be overwritten.

5. Patch persistence — The TS patch modifies node_modules/typescript/. It disappears after npm install/bun install. Use "prepare": "effect-language-service patch" to persist it.

6. diagnostics vs tsc — Without patching, tsc does NOT run Effect diagnostics. The diagnostics CLI command works without patching. The patch is only needed for tsc integration and IDE features.

7. ANSI spinner pollution — overview, layerinfo, and quickfixes emit ANSI escape codes and "Processing file" spinner lines mixed into stdout. Always pipe through the els_clean pattern (strip ANSI + filter spinner) when capturing output programmatically.

8. --format is diagnostics-only — Only diagnostics supports --format json|text|pretty|github-actions. All other commands (overview, layerinfo, quickfixes, codegen) output unstructured text. Do not waste time trying --format on them.

9. codegen with no directives — If no files contain @effect-codegens, codegen throws NoFilesToCodegenError instead of exiting cleanly. This is not a real error — the project simply has no codegen directives. Check before running.

10. config/setup file picker — Both config and setup are interactive and list ALL .json files in the project, not just tsconfig files. This is a known UX issue — select the correct tsconfig manually.

Fetching Documentation

This skill covers tooling operations. For current API details or version-specific changes:

Navigating References

Load references when the command table and workflows above are insufficient.

!echo "## ELS Project Context" !~/.claude/skills/effect-language-service-cc/scripts/probe-els.sh

Source: bengous/agents-skills — distributed by TomeVault.