---
name: effect-v4
description: Write, review, or upgrade Effect v4 code in the Composio CLI, cli-keyring, and json-schema-to-effect-schema packages, all using the matching range effect@^4.1.0 — Context.Service and explicit layers, Schema.TaggedError and typed recovery, the effect/cli command surface, and the vendored effect source oracle. Use when writing or reviewing Effect v4 code, answering a v4 API question, working in effect/cli, defining a Context.Service service, modeling an error with Schema.TaggedError, bumping the Effect pins, or verifying an unfamiliar API against ts/vendor/effect. Do not use for CLI command UX/wiring design (use cli-command) or CLI E2E tests (use cli-e2e).
title: effect-v4
canonical_url: https://skilld.dev/gh/composiohq/composio/effect-v4
last_updated: 2026-11-12T04:08:57.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/cli-surface.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/cli-surface.md), [references/core-patterns.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/core-patterns.md), [references/upgrade-workflow.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/upgrade-workflow.md), [scripts/check-examples.mjs](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/scripts/check-examples.mjs), [versions.json](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/versions.json).
>
> If the user asked to install this Skill, run `npx skilld install composiohq/composio/effect-v4`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/effect-v4`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/composiohq/composio/effect-v4) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/effect-v4`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/effect-v4 --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/effect-v4 --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Effect v4

The CLI, `@composio/cli-keyring`, and `@composio/json-schema-to-effect-schema` run on
Effect v4. Every claim below is grounded in the migrated source, not memory of v3.

## Version matrix

`effect`, `@effect/platform-bun`, and `@effect/vitest`
use the **same range** `^4.1.0`; keep their lockfile resolutions aligned. Do not use
`@next` or mismatched versions across packages. `@effect/cli` and `@effect/platform` no longer exist as
dependencies; their surfaces are consolidated into `effect` and `effect/*`.
See [versions.json](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/versions.json) for the exact example-check matrix (also `typescript`, `vitest`).

## Read next

- [references/core-patterns.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/core-patterns.md) — services, layers, typed
  errors, Schema, choosing between `Effect.gen` and `Effect.fn`, `Option` combinators in
  place of `isSome` ternaries, driving time in tests with
  `TestClock` (fork, adjust until the fiber settles, join) instead of `it.live`, and the v3→v4 rename table
  (labeled historical, for recognizing stale patterns).
- [references/cli-surface.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/cli-surface.md) — `effect/cli`:
  `Command`, `Flag`, `Argument`, `GlobalFlag`, `CliConfig`, the custom
  `CliOutput.Formatter`, and the runner's double-print rule.
- [references/upgrade-workflow.md](https://skilld.dev/api/skills-raw/composiohq/composio/effect-v4/references/upgrade-workflow.md) — procedure for
  bumping to a newer release.

References label source excerpts and standalone framework examples separately. Repo-linked
excerpts name the file checked by `validate:cli-skills`. The cited source remains authoritative
when an excerpt or explanation disagrees with the implementation.

## Non-negotiables

- `Effect.gen(function* () {...})` for effect values — the dominant form, including named
  module consts — and `(params) => Effect.gen(...)` for parameterized helpers.
  `Effect.fn(...)` is the function form whose effects carry stack-frame annotations (its
  optional name string adds a per-call tracing span), worth it for service members and
  combinator callbacks that should be attributable in error reports. All forms re-run
  their body per execution. See "`Effect.gen` vs `Effect.fn`" in core-patterns.
- Define services with `Context.Service` and an explicit `static readonly Default`/`layer`
  layer built with `Layer.succeed`/`Layer.effect`/`Layer.provide`. V4 does not generate a
  layer for you.
- Model expected failures with `Schema.TaggedError` (or a plain `Data.TaggedError`
  when no Schema fields are needed) and recover with `Effect.catchTag`/`catchTags`/`Match`,
  never manual `_tag` string comparisons.
- Wrap fallible Promises with `Effect.tryPromise({ try, catch })`; `Effect.promise` turns
  rejection into a defect. No `async`/`await` or `try`/`catch` inside Effect workflows.
  oxlint rejects `try`/`catch` in `ts/packages/cli/src`. Nothing lints `async`/`await`, so review catches it.
- Treat every remembered v3 package name and API as wrong until verified against
  `ts/vendor/effect` (read-only source oracle — never edit or import from it) and the
  installed `effect@^4.1.0` typings. Source may be ahead of the published package;
  the compiler is the compatibility gate.

## Verification

```bash
pnpm typecheck
pnpm --filter @composio/cli run lint:effect
pnpm --filter @composio/cli test
```

Run `bun run validate:agent-skills` and `bun run validate:skill-routing` after editing this
skill or its descriptions, and compile the TypeScript blocks in this skill and in
`typescript-testing/references/effect-v4-cli.md` against the pinned packages with:

```bash
node .agents/skills/effect-v4/scripts/check-examples.mjs
```

Blocks that quote repo files with unresolvable imports carry a `no-check` fence info string.

`bun run validate:cli-skills` also verifies repo-linked command examples, their native Effect client requests, and the selected invocation contracts in Agent Substrate CI. Standalone snippet compilation and routing probes alone do not certify command behavior or agent task performance.
