AGENTS.md

Agent Instructions

commy is a hexagonal MCP substrate for inter-agent communication — see docs/architecture.md for the architecture overview and workspace package map, docs/self-hosting.md for the operator's environment contract, and docs/ for the substrate rationale (why Zulip), bot naming conventions, and the inbound event contract. The README is the consumer-facing front door.

Any change to the agent-facing surface is held against docs/agent-experience.md — what an agent's experience of commy is supposed to be, and the principles a divergence from it has to name.

Before implementing a behaviour, ask whether the substrate already computes it. If you are about to derive something the realm knows — who a message mentions, who may edit it, what a member is subscribed to — read the realm's answer instead of inferring one. An inference has to track the substrate's semantics forever; a read is correct by construction.

What commy owns

commy is a substrate that lets coding agents and people talk to each other through a chat realm the user already runs. This repo decides and changes:

• The ports in @commy/core and the behaviour every adapter must honour.
• The Zulip adapter, the in-memory test double, and the contract tests that tie them together.
• The MCP tool surface, the agent identity and naming rules, and the inbound event contract.
• The Claude Code plugin that packages the server, and its release process.
• The documentation of all of the above, including the operator's environment contract.

What it does not own

• A deployment's realm, members, channels and data belong to whoever runs that realm. commy has no hosted service and holds none of a user's messages.
• A deployment's credentials and configuration belong to whoever runs it. This repo documents the environment contract and never holds a value.
• How a team uses its channels, such as which channels and topics exist and what each is for, belongs to that team.
• Zulip itself belongs to the Zulip project. Fixes to its behaviour go upstream, and commy adapts to what the realm reports.
• The agent host, such as Claude Code, belongs to its vendor. commy adapts to the host's plugin and channel interfaces.

Build & Test

Requires Bun (version pinned in package.json under packageManager).

bun install        # install deps
bun run check      # run all quality gates via turbo (typecheck → lint → test, cached)
bun run lint:fix   # biome auto-fix (not cached, interactive use only)
bun run test:live  # run live suite against a real Zulip realm

Always use bun run check for quality gates. The individual scripts (test, typecheck, lint) refuse to run outside turbo — they exist only as turbo task targets. This ensures turbo's dependency ordering and caching are always in play.

Run the gate inside the dev shell. bun run check (and the pre-commit hook) includes the clients/hermes Python gate (//#test:hermes → scripts/test.sh: ruff + pytest), which needs uv. uv lives in the flake dev shell — so work inside nix develop (or nix develop .#ci --command bun run check to use the lean CI shell). A bare bun run check outside the shell fails the hermes task with uv: command not found whenever its turbo cache is cold. CI runs the gate this way too (.github/workflows/ci.yml).

Live tests (*.live.test.ts) hit a real Zulip realm and can rate-limit other clients sharing it. They are excluded from default discovery via bunfig.toml [test] pathIgnorePatterns. The test:live script clears that override and targets the file explicitly. Live tests are env-gated inside the file too — without ZULIP_SITE / ZULIP_MINTER_* / ZULIP_LIVE_CHANNEL_* set, the suite skips silently.

Lint layers, when to reach for which:

• biome — JS/TS style, formatting, generic lint (unused imports, etc.). Run via bun run check (turbo cached) or bun run lint:fix for auto-fix.
• @effect/tsgo — Effect idiom (floating Effects, untyped catches, unnecessary Effect.gen, reaching for global fetch/Date/console instead of Effect-native services, ~60 rules). It patches the TypeScript 7 compiler and reads its plugin entry, still named @effect/language-service, from tsconfig.json under compilerOptions.plugins. The effect-tsgo patch step in the prepare script applies the patch at install time — so diagnostics surface under tsc --noEmit (i.e. bun run check), not just in editors. Project-scope rule tweaks live in the tsconfig plugin entry; document the reason inline when disabling.

Contributing

Work on a branch and open a pull request against main. CI runs the same bun run check gate inside the nix CI shell; a green gate is required to merge. File bugs and feature requests as GitHub issues.

Cutting a release is its own flow — see docs/releasing.md: bump the eight lockstep version sites, write RELEASE-NOTES/<version>.md, open the bump PR. The maintainer's merge is the single trigger; CI tags, publishes to npm, and cuts the GitHub Release.

Conventions & Patterns

Effect style

This codebase is built on Effect. Two rules shape every change that touches Effect-aware code:

1. Effects flow through to a single runtime call at the application's edge. The destination is one Effect composed bottom-up — adapters return Effect, ports return Effect, application bootstrap composes them into one Effect, and a single Effect.runPromise / Effect.runSync lives at the MCP SDK boundary (the only place where the host environment demands a Promise). Don't sprinkle Effect.runPromise, Effect.runSync, Effect.tryPromise, Schema.decodeUnknownSync, or throwing brand constructors at internal seams to "keep this method Promise-returning for now." Each bridge fragments the typed E channel, resists composition, and creates churn when the surrounding code converts later.

If converting a function to Effect would force its callers to convert too, that's expected. Either grow the current change to absorb the propagation, or file a paired follow-up issue — never introduce a temporary bridge as a placeholder.

2. Reach for Effect's built-in helpers before writing imperative code. The Effect ecosystem has many helpers — Schema.NonEmptyString, Schema.minLength, Schema.pattern, Schema.URL, Schema.transformOrFail, ParseResult.try, Effect.gen, Effect.retry, Schedule.*, Stream.*, @effect/platform's HttpClient — and they're usually shorter and more correct (annotations, AST integration, proper error formatting) than the hand-rolled equivalent. Before writing a Schema.filter with manual value.length === 0 checks, regex tests, or try/catches around standard parses (URL, JSON, Date), grep the relevant Effect source first.

If you have a local read-only Effect source clone available (path is machine-local), grep it directly: grep -n '^export' packages/effect/src/Schema.ts (or Effect.ts, Stream.ts, Schedule.ts, etc.) finds helpers fast. Same for packages/platform/src/HttpClient.ts and friends. Otherwise read the same files on GitHub (Effect-TS/effect).

Don't use:

• Schema.decodeUnknownSync — throws on failure; use Schema.decodeUnknown (returns Effect)
• Effect.tryPromise at the network edge — use @effect/platform's HttpClient which is Effect-native
• Throwing brand constructors inside Effect code — brand validators that can fail return Effect<Brand, ParseError>

3. Common imperative → Effect-native swaps. These shapes recur; reach for the native one first, while writing — not after. This table is a digest: the full four-axis catalogue (substitution / structural / modelling / behaviour) lives in .claude/skills/effect-native-audit/domains.md and is swept periodically by /effect-native-audit.

imperative shape	native shape
x instanceof Error ? x.message : String(x)	Predicate.isError(x) ? …
typeof o === 'object' && o !== null && 'k' in o + casts	Predicate.hasProperty(o, 'k')
switch (x.kind) (esp. with a hand-rolled const _: never default)	Match.value(x).pipe(Match.discriminatorsExhaustive('kind')({…}))
arr.flat().sort((a, b) => a.n - b.n)	Arr.flatten + Arr.sort(Order.mapInput(Order.number, …))
a validating constructor returning T | undefined	return Option<T> (callers stop re-wrapping with Option.fromNullable)
a sentinel value or bare throw for a recoverable case	Either / Option
booleans + optional fields with a cross-field invariant	Data.TaggedEnum — make illegal states unrepresentable
a bare string / number domain id or constrained value	branded Schema.brand, decoded once at the boundary
new Map<string, …> keyed on `${a}|${b}`	Data.struct({ a, b }) key + HashMap / HashSet (value equality, no delimiter collisions)
a new-able class or config-field thread doing DI	a Context.Tag service declared in R
an injected now() / sleep() thunk	Clock.currentTimeMillis / Effect.sleep (default services; TestClock in tests)
reassigned let mutated across yield* points	Ref / SynchronizedRef
try/finally for cleanup	Effect.acquireRelease / Scope
independent effects run sequentially	Effect.all / Effect.forEach with bounded { concurrency } — never 'unbounded' onto a rate-limited Zulip realm
untrusted data via as / JSON.parse at the edge	Schema.decodeUnknown

This complements the linters, it doesn't repeat them: @effect/tsgo and biome catch per-line idiom; this table is for the whole-block / whole-type / whole-module shapes a linter can't see.

This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the turbo package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo.

Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by turbo before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in crates/turborepo-cli/src/cli/agent_guidance.rs. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set "agentGuidance": false in the root turbo.json or turbo.jsonc to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.