effect-mcp: Instructions file for Codex

Writing Effect Guide

Pre-requisites

• Have the Effect MCP server installed and running.
  • npx -y effect-mcp@latest

Critical information

Important: When requiring more information about Effect, use the effect_docs_search MCP tool. It is an authoritative source of information about Effect and its ecosystem.

Writing basic Effect's

Prefer Effect.gen when writing Effect's. It is a powerful way to create an Effect in a async/await style, which is more readable and maintainable.

import { Effect, Random } from "effect"

Effect.gen(function* () {
  // Use `yield*` to run another Effect
  yield* Effect.sleep("1 second")

  const bool = yield* Random.nextBoolean
  if (bool) {
    // When failing with Effect.fail/die etc. always use `return yield*` so
    // TypeScript can correctly narrow conditional types
    return yield* Effect.fail("Random boolean was true")
  }

  // You can return a success value directly
  return "Returned value"
}).pipe(
  // You can use the `pipe` method to add additional operations
  Effect.withSpan("tracing span"),
)

Writing Effect functions

If you need to write a function that returns an Effect, prefer using Effect.fn. It allows you to use the yield* syntax inside the function body, and also add a span for observability.

import { Effect, Random } from "effect"

const myEffectFn = Effect.fn("myEffectFn")(
  function* (x: number, y: number) {
    const bool = yield* Random.nextBoolean
    if (bool) {
      // When failing with Effect.fail/die etc. always use `return yield*` so
      // TypeScript can correctly narrow conditional types
      return yield* Effect.fail("Random boolean was true")
    }
    return x + y
  },
  // You can add "pipe" operations as additional arguments
  Effect.annotateLogs({
    some: "annotation",
  }),
  // You can also access the arguments of the function in pipe operations
  (effect, x, y) => Effect.annotateLogs(effect, { x, y }),
)

// call the Effect function
myEffectFn(1, 2).pipe(Effect.runPromise)

// You can also omit the function span name if you don't need it
const withNoSpan = Effect.fn(function* (x: number, y: number) {
  yield* Effect.log("Calculating sum", { x, y })
  return x + y
})