Guides for you and your agent
How Kody works, first builds, and recipes — verified and plain markdown. Append .md to any URL and hand it to your agent. Connecting Discord, GitHub, and other providers lives on connection guides.
Work with Kody
Start here
- What is Kody?Pre-account capability tour for people and agents deciding whether Kody fits: what Kody is, what you cannot get elsewhere, the building blocks, real usage examples, and notes for running a discovery interview. Nothing here requires an account or an MCP connection.
- Onboarding — the home your agents shareFirst-run guide for a connected agent. Teach lightly what Kody is and is not, ask 1–2 questions to find the person's use, help them take advantage of the right features, and set up integrations with clear difficulty. One small win, then Step 3.
- How Kody worksThe factory loop as a conversation: ask what your favorite bot shipped, save the answer as an export you can invoke from any agent, then a daily email that stays quiet until something actually ships.
- The Kody factory mapMap Kody's discovery, credentials, integrations, packages, storage, schedules, hosted surfaces, and memories—and know where the boundary is.
- First build — ad hoc execute, then persistAgent playbook after Make something useful (`/onboarding/step-2`) or Connect your agent (`/onboarding/step-1`): run one useful ad hoc execute, show the result, persist that working code as a package they own, and offer optional triggers without recommending one.
More guides
- Portability — reuse what already existsSecond-agent proof after a first win. Find what the account already has, reuse it once, and stop. Retrieved as portability:guide from Step 3.
- Packages, integrations, and MCP serversPackages are saved behavior. Integrations are account-owned logins. MCP servers are how agents connect. Use this when those three look interchangeable.
- Connect a home MCP serverRun an MCP server beside a vault, CLI, or home device, publish it with Cloudflare Tunnel and Access, and connect its HTTPS URL to Kody.
- Offload work that does not fit a Worker isolateWhen package checks or publish rebuilds exceed isolate memory or CPU — usually a large npm graph such as PDF.js — keep the Kody package as a thin orchestrator and run the heavy work in a process the owner operates (Cloudflare Container, Fly machine, or similar). Do not provision paid infra without asking.
- Google OAuth interactive guideInteractive transcript of a coding agent walking a naive user through Google OAuth for Gmail inbox reading: official guides first, one console step at a time, prefilled /connect/oauth, refuse secrets in chat, then a Gmail profile smoke test.
- Email and memories — welcome email, reply, memoriesOptional agent playbook: send a welcome email, point the person at their own inbox to reply, look the reply up when they say it is sent, save what matters as memories, then offer a next step. After Connect your agent (`/onboarding/step-1`), Step 2 is Make something useful (`/onboarding/step-2`) and Step 3 is Connect a second agent (`/onboarding/step-3`); the optional climax guide is quick-example. Load this when someone wants the email loop. Includes the no-polling rule and troubleshooting for missing mail and unbound tools.
- Package authoring guideSTART HERE when creating or materially changing a Kody package: package shape, required README.md (human) and AGENTS.md (agent), README Intent section, per-export JSDoc (search Purpose), personal-details hygiene before going public, secret-using package approval checklist, and scope-update guidance without adding new primitives.
- Durable package lifecycle guideChoose between invoking existing behavior, temporary execute exploration, forking a close public package, deferred workflows, and creating a durable repo-backed package; test package-owned job wrappers safely.
- Platform efficiencyHow unique Dynamic Worker days work across execute, jobs, package exports, and other surfaces, and how a stable module graph reuses one isolate for the UTC day.
- Integration bootstrap guideSTART HERE when a third-party integration must work before saving a dependent package or package app: inspect integration/secret state, stop for setup, run an authenticated smoke test, then use connect nextSteps or communitySearch before building from scratch.
- Gmail drafts without send — lock what Google cannot scopeGoogle has gmail.send but no drafts-only scope. gmail.compose can manage drafts and send. Publish a drafts-only package, lock it, then integrationLock the connection so execute cannot use the token.
- Lock an MCP server to a packageConnected MCP servers expose every discovered tool to execute and every package. Lock the server to a thin package so only that published surface can call it.
- Secret-backed integration recipeDefault non-OAuth recipe for secret-backed integrations: research auth, collect secrets through /account/secrets/new, run a smoke test, build the downstream package, then surface package secret approval links (prefer bulk) before calling the work complete.
- Integration-backed package app happy pathAfter integration/secret verification and a cheap smoke test, proceed directly to a package app rooted in package.json and package-owned code; avoid unnecessary repo spelunking.
- OAuth guide (standard path)START HERE for third-party OAuth: hosted /connect/oauth, the exact redirect URI (https://kody.codes/connect/oauth), required query params, PKCE vs confidential, post-connect nextSteps with community helpers suggestions, and how it differs from MCP OAuth.
- Account secret setup guideHosted /account/secrets/new URL shape, query params, approval policy for API keys and PATs, and post-hoc package approval URLs including bulk approve.
- Package subscription guideUse package.json#kody.subscriptions for package-owned event handlers; discover subscribers with packageSubscriptionsList; smoke-test handlers with packageSubscriptionDispatch; follow metadata-first email, run.error.recorded activity notifiers, integration.auth.failed / integration.auth.succeeded reconnect notifiers, mcp.server.disconnected / mcp.server.reconnected connection episodes, consent-gated admin-only platform.feedback.submitted notification guidance, admin-only community.activity.recorded / community.listing.published community notifications, admin-only status.incident.opened / status.incident.resolved operator telemetry, admin-only fleet.package_error_rate.elevated package-runtime health, admin-only fleet.entitlement.crossed entitlement crossings, admin-only auth.denial.burst / email.delivery.burst operator bursts, admin-only user.created / user.deleted account lifecycle notifications, and admin-only user.email_verification.failed / user.email_verification.stalled / user.email_outbound.paused / email.system-message.sent mail-operator notifications.
- Kody platform friction guideUse for meaningful Kody friction, bugs, poor experiences, or suggestions: show the exact proposal and account-identity notification disclosure before asking for explicit approval, and write one actionable issue per submission (repro steps, expected vs actual, impact).
- OpenAPI integrations guidePrefer a close community helpers package, then fork `@kody/openapi` to bind and call selected operations.
Connect a provider
How to connect Discord, GitHub, Google, Notion, Origin, Salesforce, Slack, or Spotify to Kody — console steps, scopes, and a smoke test.