AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

Kody, a GitHub maintainer agent built on the eve agent framework. A weekly schedule composes a digest email of the configured repo's open issues and sends it through the Resend MCP connection. Inbound email commands are intentionally disabled pending a separately authenticated authorization protocol; replies never dispatch sessions. Kody reads and triages GitHub issues through the github tools (GitHub Tools SDK via Vercel Connect), creates and cross-references issues through the Linear MCP connection, and answers when @mentioned on GitHub issues/PRs or in Linear Agent Sessions. Per-user preferences live in Vercel Blob. Its workflow lives in agent/instructions.ts.

The whole agent is defined under agent/. eve discovers capabilities from the filesystem. See ARCHITECTURE.md for the component map, data flow, and boundaries.

Setup & commands

pnpm install        # install dependencies (Node 24.x)
pnpm dev            # eve dev — local TUI; run /model once to link a model provider
pnpm typecheck      # tsc (TypeScript, no emit)
pnpm check          # ultracite (Biome) lint + format check
pnpm fix            # ultracite (Biome) auto-fix
pnpm build          # eve build
eve deploy          # deploy to Vercel production (use this, not raw `vercel deploy`)
npx eve info        # print the discovered surface + discovery diagnostics
pnpm validate       # check + typecheck + eve info in one command

Run pnpm test for private preference storage, channel authorization regressions, and the outbound schedule contract. Verify changes with pnpm validate (lint, typecheck, and discovery diagnostics must all report 0 errors / 0 warnings), then exercise the agent in the pnpm dev TUI.

eve conventions

• Read the relevant guide in node_modules/eve/docs/ before writing code. Don't invent framework APIs; confirm them against the docs.
• Identity comes from the filesystem, never a name field. A tool at agent/tools/research.ts is the tool research; an extension mounted at agent/extensions/github.ts prefixes its tools with github__; a connection at agent/connections/linear.ts registers as linear.
• Authored slots: agent/agent.ts (model), agent/instructions.ts (defineInstructions, the system prompt; resolved at build time, injecting RESEND_FROM_ADDRESS into the sending-email rule), agent/tools/*.ts (defineTool, or defineWorkflowTool for durable workflows), agent/extensions/*.ts (mounted extensions), agent/connections/*.ts, agent/channels/*.ts, agent/schedules/*.ts (cron-triggered sessions), agent/skills/<name>/SKILL.md, agent/subagents/<id>/agent.ts (defineAgent), agent/sandbox.ts.
• Channels: github (eve GitHub channel via Connect, botName "Kody"; only @mentions on DIGEST_REPO from a sender matching the comment author, with current write, maintain, or admin permission verified through GitHub's API; lookup failures deny dispatch), linear (Connect Agent Sessions with requester context), resend (rejects every inbound POST with HTTP 403, including previously subscribed replies), plus the eve route-auth channel. Automatic PR-open summaries are disabled pending an isolated read-only agent and bounded publisher. Never authorize shared Linear access from roles on unrelated repositories or historical author_association values.
• Tools run in the app runtime (full process.env), one default export per file. Gate destructive tools with approval from eve/tools/approval (here: clear_user_preferences). The github extension (agent/extensions/github.ts, @github-tools/eve-extension) exposes the GitHub Tools maintainer preset as github__<tool> tools with credentials via Vercel Connect (the deprecated @github-tools/sdk/connect/eve one-liner no longer works: eve skips its tools at runtime); issue-conversation writes (addIssueComment, addLabels, closeIssue, createIssue, removeLabel) set requireApproval: "never" for authorized maintainer workflows, while higher-impact writes keep the extension's approval-by-default. The research tool is a defineWorkflowTool that opens a session with the researcher subagent via ctx.agent() and requests structured output per turn (defineAgent no longer takes outputSchema).
• Connections are MCP servers: linear (https://mcp.linear.app/mcp, app-scoped auth shared through linearAuth in agent/lib/constants.ts with scopes read, write, issues:create, comments:create) and resend (https://mcp.resend.com/mcp, static bearer token from RESEND_API_KEY via auth.getToken — a static token works in every session including the cron run, which has no signed-in user, and the Resend connector cannot issue app-scoped tokens; list/send emails, templates, contacts). Connections accept the same approval field as tools if a write needs gating; neither passes one today.
• Schedules: agent/schedules/weekly-digest.ts runs cron 0 9 * * 1 (Mondays 09:00 UTC) in markdown task mode: the prompt tells the agent to fetch open issues on DIGEST_REPO with the GitHub tools and send the digest to DIGEST_EMAIL itself with the Resend MCP tools, which gives it control of the subject line (the chat-sdk Resend adapter cannot set a subject on outbound-initiated threads). DIGEST_REPO, DIGEST_EMAIL, and RESEND_FROM_ADDRESS are required at module load via requireEnv, so a missing value fails discovery instead of producing a schedule that cannot send. The digest's structure lives in the digest-format skill; the schedule prompt carries only the run-specific facts (repo, recipient, sender, subject). Replies are not processed. Never invite email replies; direct follow-up to tracker links or authorized GitHub mentions.
• Skills are load-on-demand. A packaged skill (<name>/SKILL.md) requires description frontmatter; that description is the routing hint. The skills here are writing-quality, digest-format, triaging-issues, and github-linear-bridging.
• Subagents are declared under agent/subagents/<id>/agent.ts (defineAgent, required description — the routing hint). The directory name is the identity and the lowered tool name (no namespace; it must not collide with a tool name, and eve's build still rejects the collision even when the subagent sets tool: false, so a wrapping tool needs its own name, like research). A declared subagent runs in a fresh child session and inherits nothing from the root (no skills, connections, tools, or sandbox), so the caller passes everything it needs in the message. The one subagent here is researcher; it sets tool: false and is reached only through the research workflow tool.
• After editing, check LSP diagnostics / pnpm typecheck and fix type errors before moving on.

Code style

• Linting and formatting are handled by Ultracite (a Biome preset). Run pnpm check before finishing and pnpm fix to auto-fix. Config is in biome.jsonc; the kebab-case filename rule is disabled there because eve tools use snake_case names.
• TypeScript strict; ESM with NodeNext resolution (relative imports need a .js extension). Prefer const, arrow functions, optional chaining / nullish coalescing.
• Validate tool input/output with zod schemas.
• Document exported config with TSDoc (@remarks, @param, @returns, @defaultValue, @see). Avoid inline // comments — put rationale in the TSDoc block instead.
• Prose in markdown files is not hard-wrapped: write each paragraph or bullet as one line.
• Agent-facing text (instructions, skill bodies, tool and subagent descriptions) follows the "How you write" rules in agent/instructions.ts: no em dashes, no machine-made words, no bold for emphasis. It carries behavior only, never framework plumbing (sign-in flows, how approvals render) or references to tools and skills the reading agent can't access.

Security

• Never ask the user for API keys, client secrets, or any other credentials.
• Never commit secrets. .env* is gitignored. Connector UIDs are read from env (GITHUB_CONNECTOR, LINEAR_CONNECTOR); GitHub and Linear auth is brokered by Vercel Connect (Linear is app-scoped through linearAuth; tokens are resolved per call and never exposed to the model) and Blob auth is via the project's OIDC token. The outbound Resend MCP connection authenticates with RESEND_API_KEY, read from env and never committed. Inbound email is disabled in code; no webhook secret or Redis state is required. Other config comes from env too: DIGEST_REPO, DIGEST_EMAIL, RESEND_FROM_ADDRESS and optional RESEND_FROM_NAME (the sender identity, resolved at build time; the name falls back to "Kody"), legacy REDIS_URL and RESEND_WEBHOOK_SECRET values are unused. Re-enabling email commands requires separately authenticated, installation-bound authorization, not a From allowlist, thread header, or webhook signature.
• If you ever build a RegExp from data, escape it (literal match) and bound the input length.
• Gate irreversible or high-impact actions behind approval (here: clear_user_preferences).
• For per-user storage, derive the key from the resolved principal (ctx.session.auth.current), never from model input — see agent/lib/user-preferences.ts. The preference files live in a private Blob store under the reserved user-preferences/ prefix, reachable only through the principal-scoped preference tools.

Before committing

• pnpm validate passes (Ultracite check, tsc, and eve info with 0 errors / 0 warnings).
• No secrets, node_modules, or build output (.eve, .vercel, .output) staged.