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, playbooks, 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 playbook 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.
- Playbooks, integrations, and MCP serversPlaybooks 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 playbook save checks or bundle builds exceed isolate memory or CPU — usually a large npm graph such as PDF.js — keep the Kody playbook 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.
- Personal playbook authoring guideCreate private executable playbooks with playbookSave; edit complete text files using the edit_token from playbookGet, then run the latest saved code. Manifest shape, conflict handling, permissions, and safe verification.
- Playbook appsPlaybook apps: session handoff, smoke with playbookAppFetch, absolute asset URLs, and personal text-file saves.
- Personal playbook lifecycle guideReuse personal behavior or explore with execute, save durable complete text files, edit with a compare-and-set token, test safely, run, and delete.
- Platform efficiencyHow unique Dynamic Worker days work across execute, jobs, playbook 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 playbook or playbook app: inspect integration/secret state, stop for setup, run an authenticated smoke test, then reuse or save a personal helpers playbook.
- Gmail draft permissions and personal playbooksGmail compose permission also permits sending. Keep personal draft helpers narrow, restrict integration access, and do not mistake editable source for an immutable drafts-only security boundary.
- Lock an MCP server to a playbookConnected MCP servers expose every discovered tool to execute and every playbook. Lock the server to a thin personal playbook so only that identity 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 playbook, then surface playbook secret approval links (prefer bulk) before calling the work complete.
- Integration-backed playbook app happy pathAfter integration/secret verification and a cheap smoke test, proceed directly to a playbook app rooted in package.json and playbook-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 personal helpers, 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 playbook approval URLs including bulk approve.
- Playbook subscription guideUse package.json#kody.subscriptions for playbook-owned event handlers; discover subscribers with playbookSubscriptionsList; smoke-test handlers with playbookSubscriptionDispatch; 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 status.incident.opened / status.incident.resolved operator telemetry, admin-only fleet.playbook_error_rate.elevated playbook-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 guideVerify an API's official OpenAPI contract, connect and smoke-test auth, then reuse or save a narrow personal playbook for 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.