How Kody works

Official Kody guide

A question you would ask again becomes an export you can invoke from any agent, then a daily email that stays quiet until something actually shipped.

Example of a conversation you might have with your agent.

Ask once

You
What did my favorite bot ship recently on GitHub?
Reasoning
I will look up GitHub user activity and any memory that names your favorite bot.

searchFind a saved GitHub token for user activity

memoryContext

{
  "task": "What did my favorite bot ship recently on GitHub?",
  "entities": [
    "favorite bot"
  ]
}

query

"github user activity"

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

# Search results

For full detail on entity-backed hits, call `search` with `entity: "{id}:{type}"`.

1. **secret** `githubAccessToken` — github OAuth access token. Entity: `githubAccessToken:secret`

## Relevant memories

- **Favorite bot** — kody-bot is my favorite bot. I'm really interested in what it ships on github

Reasoning
Favorite bot is kody-bot. I will fetch public events with the saved token.

executeFetch public events with the saved token and keep only real ships

conversationId

"3k7n2p9q4r8w"

memoryContext

{
  "task": "What did my favorite bot ship recently on GitHub?",
  "entities": [
    "favorite bot"
  ]
}

code

export default async function main() {
	const response = await fetch(
		'https://api.github.com/users/kody-bot/events/public',
		{
			headers: {
				Accept: 'application/vnd.github+json',
				Authorization: 'Bearer {{secret:githubAccessToken}}',
				'X-GitHub-Api-Version': '2022-11-28',
			},
		},
	)
	if (!response.ok) throw new Error(`GitHub ${response.status}`)
	const events = await response.json()
	return events.flatMap((event) => {
		if (
			event.type === 'ReleaseEvent' &&
			event.payload.action === 'published'
		) {
			return [{
				id: event.id,
				kind: 'release',
				title: `${event.repo.name} ${event.payload.release.tag_name}`,
			}]
		}
		if (
			event.type === 'CreateEvent' &&
			event.payload.ref_type === 'repository'
		) {
			return [{
				id: event.id,
				kind: 'repository',
				title: `New repo ${event.repo.name}`,
			}]
		}
		return []
	})
}

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

[
  {
    "id": "51284920123",
    "kind": "release",
    "title": "kody-bot/lantern v1.4.0"
  },
  {
    "id": "51279004401",
    "kind": "repository",
    "title": "New repo kody-bot/quiet-days"
  }
]

Agent
Two things since the last look: kody-bot/lantern v1.4.0, and a new public repo kody-bot/quiet-days. Want this as a package so I can get you the answer quicker next time?
You
Yes
Reasoning
I will load the package authoring guides, then save the filter as an export you own.

searchFind the official package authoring guides

conversationId

"3k7n2p9q4r8w"

query

"package authoring lifecycle"

domain

"coding"

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

# Search results

For full detail on entity-backed hits, call `search` with `entity: "{id}:{type}"`.

1. **capability** `coding_guide_get` (`coding`) — Load an official Kody guide (markdown, bundled from the kody repository). Prefer this capability plus `search` results over local repo spelunking when Kody auth or integration behavior is already documented. Entity: `coding_guide_get:capability`
   `kody.coding_guide_get(args)` — `type CodingGuideGetInput = { guide: "what_is_kody" | "quick_example" | "first_win" | "package_authoring" | "package_lifecycle" | ... }`; use entity detail for the full definition

searchOpen coding_guide_get for the guide ids

conversationId

"3k7n2p9q4r8w"

entity

"coding_guide_get:capability"

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

# Capability — `coding_guide_get`

Load an official Kody guide (markdown, bundled from the kody repository).
Use `guide: "package_authoring"` for package creation or material package updates.
Use `guide: "package_lifecycle"` to choose reuse vs a new durable package, and before enabling package-owned schedules.

## Summary

- Entity: `coding_guide_get:capability`
- Domain: `coding`
- Required input fields: `guide`

## Execute from `execute`

```ts
import { kody } from 'kody:runtime'

export default async function main(input = {}) {
	return await kody.coding_guide_get(input)
}
```

executeLoad the package authoring and lifecycle guides

conversationId

"3k7n2p9q4r8w"

memoryContext

{
  "task": "What did my favorite bot ship recently on GitHub?",
  "entities": [
    "favorite bot"
  ]
}

code

import { kody } from 'kody:runtime'

export default async function main() {
	const authoring = await kody.coding_guide_get({
		guide: 'package_authoring',
	})
	const lifecycle = await kody.coding_guide_get({
		guide: 'package_lifecycle',
	})
	return { authoring, lifecycle }
}

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "authoring": {
    "title": "Package authoring guide",
    "body": "# Package authoring guide\n\nUse this guide when creating a new Kody package or materially changing an existing one.\n\n## Choose an authoring lane\n\n…"
  },
  "lifecycle": {
    "title": "Durable package lifecycle guide",
    "body": "# Durable package lifecycle\n\nUse this guide to decide whether to reuse existing behavior, explore with `execute`, or create durable repo-backed package code. Use it before scheduling new package behavior.\n\n## Choose the smallest durable surface\n\n…"
  }
}

Reasoning
The authoring guide prefers the git lane. I will register a stub, clone it, write the export, push, and publish.

executeRegister the stub and mint a clone remote

conversationId

"3k7n2p9q4r8w"

memoryContext

{
  "task": "What did my favorite bot ship recently on GitHub?",
  "entities": [
    "favorite bot"
  ]
}

code

import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.package_get_git_remote({
		kody_id: 'kody-bot-shipped',
		create: true,
		description: 'What kody-bot shipped since you last asked.',
	})
}

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "package_id": "pkg_kody_bot_shipped",
  "kody_id": "kody-bot-shipped",
  "created": true,
  "remote": "https://acct.artifacts.cloudflare.net/git/default/package-pkg_kody_bot_shipped.git",
  "authenticated_remote": "[REDACTED SECRET]",
  "git_extra_header": "[REDACTED SECRET]",
  "scope": "write",
  "expires_at": "2026-08-13T18:52:00.000Z",
  "git_author": {
    "name": "You",
    "email": "you@example.com"
  },
  "setup_commands": [
    "git -c http.extraHeader='Authorization: Bearer [REDACTED SECRET]' clone 'https://acct.artifacts.cloudflare.net/git/default/package-pkg_kody_bot_shipped.git' 'pkg_kody_bot_shipped'",
    "cd 'pkg_kody_bot_shipped'",
    "git config --local user.email -- 'you@example.com'",
    "git config --local user.name -- 'You'",
    "git remote add kody 'https://acct.artifacts.cloudflare.net/git/default/package-pkg_kody_bot_shipped.git'",
    "git config remote.kody.fetch '+refs/heads/*:refs/remotes/kody/*'",
    "git config --add remote.kody.fetch '+refs/notes/*:refs/notes/*'",
    "git -c http.extraHeader='Authorization: Bearer [REDACTED SECRET]' fetch kody 'refs/notes/*:refs/notes/*'",
    "git -c http.extraHeader='Authorization: Bearer [REDACTED SECRET]' push kody HEAD:'main'"
  ]
}

filesWrite the export in the temporary clone

package.jsonExport only — no job yet

{
  "name": "@you/kody-bot-shipped",
  "private": true,
  "exports": {
    "./whatShipped": "./src/what-shipped.ts"
  },
  "kody": {
    "id": "kody-bot-shipped",
    "description": "What kody-bot shipped since you last asked."
  }
}

README.mdWhy this package exists

# kody-bot-shipped

## Intent

Tell me what kody-bot shipped — published releases and new public repos —
since I last asked.

src/what-shipped.tsFilter public events and advance the cursor

import { packageStorage } from 'kody:runtime'

const login = 'kody-bot'
const seenKey = 'lastSeenEventId'

export default async function whatShipped() {
	const storage = packageStorage()
	const sinceId = (await storage.get(seenKey)) as string | null
	const shipped = await listShipped(sinceId)
	if (shipped[0]) await storage.set(seenKey, shipped[0].id)
	return shipped.length === 0
		? { shipped, message: 'Nothing new.' }
		: { shipped, message: shipped.map((item) => item.title).join('\n') }
}

async function listShipped(sinceId: string | null) {
	const response = await fetch(
		`https://api.github.com/users/${login}/events/public`,
		{
			headers: {
				Accept: 'application/vnd.github+json',
				Authorization: 'Bearer {{secret:githubAccessToken}}',
				'X-GitHub-Api-Version': '2022-11-28',
			},
		},
	)
	if (!response.ok) throw new Error(`GitHub ${response.status}`)
	const events = (await response.json()) as Array<{
		id: string
		type: string
		repo: { name: string }
		payload: {
			action?: string
			ref_type?: string
			release?: { tag_name?: string }
		}
	}>
	const shipped = []
	for (const event of events) {
		if (sinceId && event.id === sinceId) break
		if (
			event.type === 'ReleaseEvent' &&
			event.payload.action === 'published'
		) {
			shipped.push({
				id: event.id,
				kind: 'release',
				title: `${event.repo.name} ${event.payload.release?.tag_name ?? 'release'}`,
			})
		}
		if (
			event.type === 'CreateEvent' &&
			event.payload.ref_type === 'repository'
		) {
			shipped.push({
				id: event.id,
				kind: 'repository',
				title: `New repo ${event.repo.name}`,
			})
		}
	}
	return shipped
}

executePublish Artifacts HEAD as the owned package

conversationId

"3k7n2p9q4r8w"

memoryContext

{
  "task": "What did my favorite bot ship recently on GitHub?",
  "entities": [
    "favorite bot"
  ]
}

code

import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.package_publish_external_push({
		kody_id: 'kody-bot-shipped',
	})
}

Returns

conversationId: 3k7n2p9q4r8w
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "status": "published",
  "previous_commit": "4c1a0e8b2d91",
  "published_commit": "7f3a91c2e8b4",
  "manifest": {
    "name": "@you/kody-bot-shipped",
    "private": true,
    "exports": {
      "./whatShipped": "./src/what-shipped.ts"
    },
    "kody": {
      "id": "kody-bot-shipped",
      "description": "What kody-bot shipped since you last asked."
    }
  },
  "checks": [
    {
      "kind": "manifest",
      "ok": true,
      "message": "ok"
    }
  ],
  "hosted_app_url": null,
  "static_dependents": {
    "total": 0,
    "items": []
  },
  "pending_secret_package_approvals": null
}

Agent
You now have `kody-bot-shipped`. Ask again from any agent and I will invoke the export instead of walking GitHub by hand.

Later, on your phone with a completely different Kody-connected agent

Ask again. Now safer, cheaper, and more reliable.

You
Anything interesting shipped by my favorite bot recently?
Reasoning
Same question in different words. I will search for a package that already answers this.

searchFind the owned package, not a new GitHub walk

memoryContext

{
  "task": "Anything interesting shipped by my favorite bot recently?",
  "entities": [
    "favorite bot"
  ]
}

query

"anything interesting shipped favorite bot"

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

# Search results

For full detail on entity-backed hits, call `search` with `entity: "{id}:{type}"`.

1. **package** @you/kody-bot-shipped (`kody-bot-shipped`) — What kody-bot shipped since you last asked. Entity: `kody-bot-shipped:package`

## Relevant memories

- **Favorite bot** — kody-bot is my favorite bot. I'm really interested in what it ships on github

executeInvoke the export — no model rewriting the filter

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Anything interesting shipped by my favorite bot recently?",
  "entities": [
    "favorite bot"
  ]
}

code

import whatShipped from 'kody:@you/kody-bot-shipped/whatShipped'

export default async function main() {
	return await whatShipped()
}

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "shipped": [],
  "message": "Nothing new."
}

Agent
Nothing interesting has shipped.
You
Update me when kody-bot does something.
Reasoning
I will search for how to notify you when this package has something new.

searchFind how to notify when the export has news

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Update me when kody-bot does something.",
  "entities": [
    "kody-bot"
  ]
}

query

"notify when github user ships"

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

# Search results

For full detail on entity-backed hits, call `search` with `entity: "{id}:{type}"`.

1. **capability** `coding_guide_get` (`coding`) — Load an official Kody guide (markdown, bundled from the kody repository). Use `guide: "package_lifecycle"` before enabling a package-owned schedule. Entity: `coding_guide_get:capability`
2. **capability** `webhook_url_mint` (`webhooks`) — Mint an inbound webhook URL for a package-declared webhook. Entity: `webhook_url_mint:capability`
3. **capability** `job_schedule` (`jobs`) — Schedule a repo-backed job without creating a saved package first. Entity: `job_schedule:capability`

executeLoad the package lifecycle guide

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Update me when kody-bot does something.",
  "entities": [
    "kody-bot"
  ]
}

code

import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.coding_guide_get({
		guide: 'package_lifecycle',
	})
}

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "title": "Durable package lifecycle guide",
  "body": "# Durable package lifecycle\n\nUse this guide to decide whether to reuse existing behavior, explore with `execute`, or create durable repo-backed package code. Use it before scheduling new package behavior.\n\n## Choose the smallest durable surface\n\n…"
}

Reasoning
Inbound webhooks are URLs I host, not a GitHub feed of one person’s public activity. `job_schedule` is for jobs without a package. I will open a repo session, patch in a daily cron wrapper, test it, then enable the job.

executePatch the package in a repo session, job left off

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Update me when kody-bot does something.",
  "entities": [
    "kody-bot"
  ]
}

code

import { kody } from 'kody:runtime'

const dailyDigest = `import { kody } from 'kody:runtime'
import whatShipped from './what-shipped.ts'

export default async function dailyDigest() {
	const result = await whatShipped()
	if (result.shipped.length === 0) return { emailed: false }
	await kody.email_send({
		subject:
			result.shipped.length === 1
				? 'kody-bot shipped something'
				: \`kody-bot shipped \${result.shipped.length} things\`,
		text: result.message,
	})
	return { emailed: true, count: result.shipped.length }
}
`

export default async function main() {
	const session = await kody.repo_open_session({
		target: { kind: 'package', kody_id: 'kody-bot-shipped' },
		conversation_id: '5h8m2q7t1v4x',
	})
	await kody.repo_write_file({
		session_id: session.id,
		files: [{ path: 'src/daily-digest.ts', content: dailyDigest }],
	})
	await kody.repo_edit_files({
		session_id: session.id,
		edits: [
			{
				kind: 'replace',
				path: 'package.json',
				search: '    "./whatShipped": "./src/what-shipped.ts"',
				replacement:
					'    "./whatShipped": "./src/what-shipped.ts",\n    "./daily-digest": "./src/daily-digest.ts"',
			},
			{
				kind: 'replace',
				path: 'package.json',
				search: '    "description": "What kody-bot shipped since you last asked."',
				replacement: `    "description": "What kody-bot shipped since you last asked.",
    "jobs": {
      "daily-digest": {
        "entry": "./src/daily-digest.ts",
        "schedule": { "type": "cron", "expression": "0 8 * * *" },
        "timezone": "America/Denver",
        "enabled": false
      }
    }`,
			},
			{
				kind: 'replace',
				path: 'README.md',
				search: 'since I last asked.',
				replacement:
					'since I last asked. Email me only when that list is not empty.',
			},
		],
	})
	await kody.repo_commit({
		session_id: session.id,
		message: 'Add a quiet daily digest job',
	})
	const checks = await kody.repo_run_checks({ session_id: session.id })
	const published = await kody.repo_publish_session({
		session_id: session.id,
	})
	return { session_id: session.id, checks, published }
}

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "session_id": "rs_kody_bot_shipped",
  "checks": {
    "ok": true,
    "results": [
      {
        "kind": "manifest",
        "ok": true,
        "message": "ok"
      },
      {
        "kind": "typecheck",
        "ok": true,
        "message": "ok"
      }
    ],
    "manifest": {
      "name": "@you/kody-bot-shipped",
      "kody_id": "kody-bot-shipped",
      "description": "What kody-bot shipped since you last asked.",
      "has_app": false
    }
  },
  "published": {
    "status": "ok",
    "session_id": "rs_kody_bot_shipped",
    "published_commit": "c8e2b1a04f73",
    "message": "Published session to main."
  }
}

executeTest the no-argument wrapper the scheduler will call

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Update me when kody-bot does something.",
  "entities": [
    "kody-bot"
  ]
}

code

import dailyDigest from 'kody:@you/kody-bot-shipped/daily-digest'

export default async function main() {
	return await dailyDigest()
}

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "emailed": false
}

executeEnable the daily job after the wrapper succeeds

conversationId

"5h8m2q7t1v4x"

memoryContext

{
  "task": "Update me when kody-bot does something.",
  "entities": [
    "kody-bot"
  ]
}

code

import { kody } from 'kody:runtime'

export default async function main() {
	const session = await kody.repo_open_session({
		target: { kind: 'package', kody_id: 'kody-bot-shipped' },
		conversation_id: '5h8m2q7t1v4x',
	})
	await kody.repo_edit_files({
		session_id: session.id,
		edits: [
			{
				kind: 'replace',
				path: 'package.json',
				search: '"enabled": false',
				replacement: '"enabled": true',
			},
		],
	})
	await kody.repo_commit({
		session_id: session.id,
		message: 'Enable the daily digest job',
	})
	const checks = await kody.repo_run_checks({ session_id: session.id })
	const published = await kody.repo_publish_session({
		session_id: session.id,
	})
	return { session_id: session.id, checks, published }
}

Returns

conversationId: 5h8m2q7t1v4x
Tool conversation id; pass it back on subsequent search/execute calls.

{
  "session_id": "rs_kody_bot_shipped",
  "checks": {
    "ok": true,
    "results": [
      {
        "kind": "manifest",
        "ok": true,
        "message": "ok"
      },
      {
        "kind": "typecheck",
        "ok": true,
        "message": "ok"
      }
    ],
    "manifest": {
      "name": "@you/kody-bot-shipped",
      "kody_id": "kody-bot-shipped",
      "description": "What kody-bot shipped since you last asked.",
      "has_app": false
    }
  },
  "published": {
    "status": "ok",
    "session_id": "rs_kody_bot_shipped",
    "published_commit": "e1d9c70b3a26",
    "message": "Published session to main."
  }
}

Agent
It will check every morning. If kody-bot shipped something, you get mail. If not, nothing hits your inbox.

The package

What the agent wrote

Same implementation for “ask again” and the morning job. The job calls email_send only when the list is not empty.

package.jsonExport plus a daily job

{
  "name": "@you/kody-bot-shipped",
  "private": true,
  "exports": {
    "./whatShipped": "./src/what-shipped.ts",
    "./daily-digest": "./src/daily-digest.ts"
  },
  "kody": {
    "id": "kody-bot-shipped",
    "description": "What kody-bot shipped since you last asked.",
    "jobs": {
      "daily-digest": {
        "entry": "./src/daily-digest.ts",
        "schedule": { "type": "cron", "expression": "0 8 * * *" },
        "timezone": "America/Denver",
        "enabled": true
      }
    }
  }
}

README.mdWhy this package exists

# kody-bot-shipped

## Intent

Tell me what kody-bot shipped — published releases and new public repos —
since I last asked. Email me only when that list is not empty.

src/what-shipped.tsFilter public events and advance the cursor

import { packageStorage } from 'kody:runtime'

const login = 'kody-bot'
const seenKey = 'lastSeenEventId'

export default async function whatShipped() {
	const storage = packageStorage()
	const sinceId = (await storage.get(seenKey)) as string | null
	const shipped = await listShipped(sinceId)
	if (shipped[0]) await storage.set(seenKey, shipped[0].id)
	return shipped.length === 0
		? { shipped, message: 'Nothing new.' }
		: { shipped, message: shipped.map((item) => item.title).join('\n') }
}

async function listShipped(sinceId: string | null) {
	const response = await fetch(
		`https://api.github.com/users/${login}/events/public`,
		{
			headers: {
				Accept: 'application/vnd.github+json',
				Authorization: 'Bearer {{secret:githubAccessToken}}',
				'X-GitHub-Api-Version': '2022-11-28',
			},
		},
	)
	if (!response.ok) throw new Error(`GitHub ${response.status}`)
	const events = (await response.json()) as Array<{
		id: string
		type: string
		repo: { name: string }
		payload: {
			action?: string
			ref_type?: string
			release?: { tag_name?: string }
		}
	}>
	const shipped = []
	for (const event of events) {
		if (sinceId && event.id === sinceId) break
		if (
			event.type === 'ReleaseEvent' &&
			event.payload.action === 'published'
		) {
			shipped.push({
				id: event.id,
				kind: 'release',
				title: `${event.repo.name} ${event.payload.release?.tag_name ?? 'release'}`,
			})
		}
		if (
			event.type === 'CreateEvent' &&
			event.payload.ref_type === 'repository'
		) {
			shipped.push({
				id: event.id,
				kind: 'repository',
				title: `New repo ${event.repo.name}`,
			})
		}
	}
	return shipped
}

src/daily-digest.tsSkip mail on a quiet day

import { kody } from 'kody:runtime'
import whatShipped from './what-shipped.ts'

export default async function dailyDigest() {
	const result = await whatShipped()
	if (result.shipped.length === 0) return { emailed: false }
	await kody.email_send({
		subject:
			result.shipped.length === 1
				? 'kody-bot shipped something'
				: `kody-bot shipped ${result.shipped.length} things`,
		text: result.message,
	})
	return { emailed: true, count: result.shipped.length }
}