https://github.com/kentcdodds/kody
An experimental personal assistant platform built on Cloudflare Workers and MCP
https://github.com/kentcdodds/kody
Last synced: 5 days ago
JSON representation
An experimental personal assistant platform built on Cloudflare Workers and MCP
- Host: GitHub
- URL: https://github.com/kentcdodds/kody
- Owner: kentcdodds
- License: mit
- Created: 2026-03-18T23:30:18.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-07-16T09:17:03.000Z (8 days ago)
- Last Synced: 2026-07-16T11:08:32.647Z (8 days ago)
- Language: TypeScript
- Homepage:
- Size: 22.1 MB
- Stars: 333
- Watchers: 2
- Forks: 26
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing/adding-capabilities.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
An experimental personal assistant platform built on Cloudflare Workers and MCP
---
`kody` is an experimental personal assistant platform built on Cloudflare
Workers and the Model Context Protocol (MCP). It ships a Remix UI, Worker-based
request routing, package runtime plumbing, and OAuth-protected MCP endpoints.
The project favors a compact MCP surface with powerful `search` and Code Mode
`execute` flows over a large static tool catalog.
Kody is a multi-user personal assistant: each signed-in user gets a fully
isolated assistant (packages, jobs, secrets, values, memories, and related
state). Tests and fixtures may seed deterministic local accounts, but no account
is privileged at runtime. The repo follows several
[epicflare](https://github.com/epicweb-dev/epicflare) starter conventions.
The repo is organized as an Nx monorepo, with shared modules in
`packages/shared` (`@kody-internal/shared`), the main app worker under
`packages/worker`, and mock Workers under `packages/mock-servers/*`.
## Quick Start
```bash
npm install
npm run dev
```
The dev server runs at `localhost:8787`. Wrangler handles the local Cloudflare
Workers runtime and D1 database automatically.
To scaffold a **new** project from the epicflare template instead, run
`npx create-epicflare`.
See
[`docs/contributing/getting-started.md`](./docs/contributing/getting-started.md)
for the full setup paths and expectations. Contributors and agents should start
with [`AGENTS.md`](./AGENTS.md) for repo-specific guidance.
If you are trying to understand what this repository is for, start with
[`docs/contributing/project-intent.md`](./docs/contributing/project-intent.md).
## Tech Stack
| Layer | Technology |
| --------------- | --------------------------------------------------------------------- |
| Runtime | [Cloudflare Workers](https://workers.cloudflare.com/) |
| UI Framework | [Remix 3](https://remix.run/) (alpha) |
| Package Manager | [npm](https://www.npmjs.com/) |
| Workspace | [Nx](https://nx.dev/) + npm workspaces |
| Database | [Cloudflare D1](https://developers.cloudflare.com/d1/) |
| Session/OAuth | [Cloudflare KV](https://developers.cloudflare.com/kv/) |
| MCP State | [Durable Objects](https://developers.cloudflare.com/durable-objects/) |
| E2E Testing | [Playwright](https://playwright.dev/) |
| Bundler | [esbuild](https://esbuild.github.io/) |
## Scope
- Personal assistant experiment, not a multi-tenant SaaS product
- MCP-first architecture intended to work across compatible AI agent hosts
- Compact MCP surface area preferred over a large static tool inventory
- ChatGPT is a likely primary host target, while keeping the server usable from
other MCP hosts where practical
## How It Works
```
Request → packages/worker/src/index.ts
│
├─→ OAuth handlers
├─→ MCP endpoints
├─→ Static assets (`packages/worker/public/`)
└─→ Server router → Remix components
```
- `packages/worker/src/index.ts` is the entrypoint for Cloudflare Workers
- OAuth requests are handled first, then MCP requests, then static assets
- Non-asset requests fall through to the server handler and router
- Client assets are bundled into `packages/worker/public/` and served via the
`ASSETS` binding
## Documentation
| Document | Description |
| -------------------------------------------------------------------------------------------- | ------------------------------------ |
| [`docs/contributing/getting-started.md`](./docs/contributing/getting-started.md) | Setup, environment variables, deploy |
| [`docs/contributing/environment-variables.md`](./docs/contributing/environment-variables.md) | Adding new env vars |
| [`docs/contributing/cloudflare-offerings.md`](./docs/contributing/cloudflare-offerings.md) | Optional Cloudflare integrations |
| [`docs/contributing/project-intent.md`](./docs/contributing/project-intent.md) | Scope, goals, and non-goals |
| [`docs/contributing/index.md`](./docs/contributing/index.md) | Developing and extending Kody |
| [`docs/use/index.md`](./docs/use/index.md) | Using Kody over MCP |
| [`docs/contributing/setup.md`](./docs/contributing/setup.md) | Local development and verification |
---