effect-claudecode AGENTS.md

AGENTS.md — effect-claudecode

Effect-first library for writing Claude Code hooks, plugins, skills, subagents, commands, and settings in a maximally Effect-native way. Wraps Claude Code's extensibility primitives (stdio hook processes, settings.json, plugin manifests, frontmatter files, .mcp.json) in Effect v4 idioms.

Build / Lint / Test Commands

bun run test           # vitest run (all tests)
bun run typecheck      # tsc --noEmit

Running a single test

bunx vitest run test/Hook/Events/PreToolUse.test.ts     # single file
bunx vitest run -t "denies rm -rf"                        # by test name pattern
bunx vitest run test/Hook/Runner.test.ts -t "schema decode"

Verification before submitting

bun run test && bun run typecheck

Project Structure

src/
  index.ts                  Barrel: re-exports Hook, Settings, Plugin, Frontmatter,
                            Mcp, Testing namespaces + cross-module errors.
  Hook.ts                   Re-export hub for all Hook/* modules.
  Hook/
    Runner.ts               Hook.runMain + Hook.dispatch. Stdio FFI boundary.
    Context.ts              HookContext namespace (ServiceMap.Service + accessors).
    Envelope.ts             Base HookEnvelope schema (session_id, cwd, etc.).
    Matcher.ts              Tool-name regex helpers for Pre/PostToolUse.
    Transcript.ts           FileSystem-backed transcript reader.
    Events/
      index.ts              Builds HookInput/HookOutput tagged unions.
      <EventName>.ts        One file per event — Input, Output, decision
                            helpers, and define(). 27 event files total.
  Settings.ts               Re-export hub for Settings/*.
  Settings/                 SettingsFile schema + Settings.load (user/project/local merge).
  Plugin.ts                 Re-export hub for Plugin/*.
  Plugin/                   plugin.json manifest schema + Plugin.define + Plugin.write.
  Frontmatter.ts            Re-export hub for Frontmatter/*.
  Frontmatter/              YAML-frontmatter parsers for skills, subagents, commands.
  Mcp.ts                    Re-export hub for Mcp/*.
  Mcp/                      .mcp.json schema (stdio/http/sse discriminated).
  Errors.ts                 All Schema.TaggedErrorClass declarations.
  Testing.ts                Test helpers: runHookWithMockStdin, fixtures,
                            expect*Decision assertions.

test/                       One file per source module.
vitest.config.ts            vitest config (plain vitest, no vite-plus in Phase 1).
vitest.setup.ts             @effect/vitest equality testers.
tsconfig.json               Strict TS with @effect/language-service plugin.