Monorepo for Kilo Code cloud platform. Use pnpm; required version is in root
package.json's packageManager field. Before changing a subtree, check for a
nearer AGENTS.md and follow its scoped invariants.
| Path | Description |
|---|---|
apps/web/ |
Next.js web application deployed to Vercel |
apps/ai-gateway/ |
Next.js app for the AI gateway API routes, deployed to Vercel as kilocode-ai-gateway |
apps/ai-gateway-secure-proxy/ |
Minimal Next.js relay for custom LLM requests, deployed to Vercel as kilocode-ai-gateway-secure-proxy |
apps/mobile/ |
React Native mobile application |
apps/extension/ |
WXT browser extension |
services/ |
Cloudflare Worker and supporting services |
packages/ |
Shared libraries, including database, tRPC, and Worker utilities |
dev/ |
Local development tooling, Docker Compose, environment sync, and seed data |
scripts/ |
CI and one-off repository scripts |
.specs/ |
Domain business-rule specs |
.agents/skills/ |
Third-party skills managed with the npx skills command |
.kilo/ |
Repository-owned commands, agents, and skills |
| Need | Location |
|---|---|
| Root scripts and dependency entry point | package.json |
| PostgreSQL schema | packages/db/src/schema.ts |
| PostgreSQL migrations | packages/db/src/migrations/ |
| Shared PostgreSQL contracts and migration invariants | packages/db/AGENTS.md |
| Durable Object SQLite conventions | durable-objects skill, docs/do-sqlite-drizzle.md, and owning service AGENTS.md |
| Web tRPC routers | apps/web/src/routers/ |
| Local environment values | Root .env.local |
| Environment variable catalog | ENVIRONMENT.md |
| Local setup and service management | DEVELOPMENT.md and dev/ |
Consumers of raw @kilocode/db values must consult packages/db/AGENTS.md for
data-contract caveats, even when changed code is outside packages/db.
| Command | Purpose |
|---|---|
pnpm format |
Format supported files |
pnpm typecheck |
Run repository TypeScript checks |
pnpm lint |
Run repository lint checks |
pnpm test |
Run web, web-env, and local development-tool tests; not every package suite |
pnpm validate |
Run root typecheck, lint, and test scripts |
Package-level scripts are in the relevant package.json. Read root and relevant
package manifests before running repository JavaScript or package scripts. Load
repository-verification to select narrow checks and prepare test dependencies.
| Task | Source |
|---|---|
| Path-specific invariants | Nearest relevant nested AGENTS.md |
| TypeScript implementation or review | code-quality skill |
| Verification or pre-commit checks | repository-verification skill |
| Local services, ports, and fake login | local-development skill |
| Cloud Agent sandbox setup, memory cap, and fake-LLM sessions | cloud-agent-sandbox skill and .kilo/cloud-agent-setup.sh |
| Shared web environment changes | apps/web/AGENTS.md and DEVELOPMENT.md |
| PostgreSQL schema or migration work | packages/db/AGENTS.md and database-migrations skill |
| Service, Durable Object, or Worker code | services/AGENTS.md, nearest owning service's AGENTS.md, and relevant Durable Objects or Workers skills |
| Domain language and ownership | CONTEXT.md, when its scope applies |
| Business requirements | Relevant .specs/*.md, indexed by specs skill |
| UI and product design | DESIGN.md, relevant app AGENTS.md; for apps/web, the kilo-design-cloud skill synced from Kilo-Org/kilo-design |
| Contribution and PR workflow | CONTRIBUTING.md and relevant Git or PR skill |
Our functions only ever run in these regions, regardless of what request metadata suggests:
| Vercel project | Function regions |
|---|---|
kilocode-app |
Frankfurt only |
kilocode-ai-gateway |
Frankfurt and us-west (SFO) |
kilocode-ai-gateway-secure-proxy |
us-west (SFO) only |
Treat this table as the source of truth for compute location, database
round-trip latency, and replica reasoning. If an observed region is not fra1 or
sfo1, it is a proxy/edge hop, not the function. Confirm against the Vercel
project's region list rather than inferring from a request or log field.
Region fields are not interchangeable. Per Vercel's Log Drains reference:
| Field | Meaning |
|---|---|
executionRegion |
Region where the request is executed |
proxy.lambdaRegion |
Region where the function executed |
proxy.region |
Region where the request is processed — the proxy/edge hop |
So a region field on a log's proxy object is the edge, and executionRegion /
proxy.lambdaRegion are the function. Do not quote a bare "region" from a log
line as the compute location without checking which of these it maps to.
x-vercel-id mixes both: Vercel documents it as "a list of Vercel regions your
request hit, as well as the region the function was executed in". Never read its
leading token as the compute location, especially for requests that pass through
a rewrite to another Vercel app, where PoP hops accumulate.
VERCEL_REGION is documented as "the ID of the Region where the app is running",
i.e. the function region. Given the table above it should only ever be fra1 or
sfo1, which is what makes isUSRegion in packages/web-shared/src/lib/drizzle.ts behave
correctly for the SFO half of kilocode-ai-gateway.
When changing failure handling — especially in the Cloud Agent control plane — optimize the user's experience, not only correctness:
- Do not fail a turn on a transient or single-observation condition. Retry within a bound.
- When progress is impossible, fail fast with a correct, specific reason. Do not make the user wait for a long timeout to learn something the system already knows.
- Never leave a session hanging silently. Surface the known error and release the session.
- Resume promptly when the condition clears, for example when the user answers a question.
A change that stops spurious failures but lengthens the wait for a genuine failure is only half a fix. State both effects in the change's verification.
- Never log tokens, credentials, API keys, authentication headers, cookies, or webhook secrets. Use
redactSensitiveHeaderswhen headers must be retained or logged. Do not enablesendDefaultPiiorattachRpcInputin Sentry.
When addressing a Kilobot review remark:
- Verify that the remark is valid. If unsure, attempt to reproduce it with an E2E or unit test.
- If valid, fix it and commit the change. Prefer small commits in general.
- Reply in the review thread, then resolve the thread.
- Push the commits.