Skip to Content
Development WorkflowAI Agent Setup

AI Agent Coding Guidelines

Give your coding agent the project schema, the selected docs version, and a concrete task. The Markdown documentation index and full current-docs corpus provide a starting context; the page’s Copy page menu supplies a focused guide.

Start a KalamDB project with an agent

BASH
mkdir my-app && cd my-appkalam init --yes --languages typescript --template simple-livekalam dev --agent

Use this prompt with your coding agent:

TEXT
Build a realtime todo app in this KalamDB project.Read kalam.toml, schema.sql, and the generated SDK before editing.Use PostgreSQL-style SQL and BIGSERIAL primary keys.Keep personal todos in a USER table; use CREATE POLICY for shared data.Use the generated types and live subscriptions instead of polling.Manage schema changes with kalam db migration commands; review SQL before applying.Keep database passwords out of browser code and use the signed-in user's token.Run the app, insert a row, and verify the live UI updates.Report the actual server, CLI, and SDK versions and any unsupported API.

Read CLI migrations before changing schema history. A ready database does not prove the application is running: inspect app output and confirm an actual live update. Keep generated artifacts and schema changes together in version control.

For agents that support external skills, the KalamDB skill package can be installed with:

BASH
npx skills add kalamdb/kalamdb-skills

Review the installed skill’s instructions and keep them aligned with the server version you run. Start with simple-live; use chat-with-ai for a fuller worker application.

Prefer subscriptions for realtime state

For live UI or state sync, use WebSocket subscriptions:

  • client.live(sql, callback, options) for materialized row state
  • client.liveTable(table, callback, options) when table-name sugar is enough
  • client.liveEvents(sql, callback, options) only when you need raw protocol events

Use subscriptions as the primary realtime pattern instead of interval polling.

Keep live SQL in the strict supported shape: SELECT ... FROM ... WHERE .... Do not put ORDER BY or LIMIT inside live subscription SQL; sort or cap rows after they arrive.

Do not use interval polling for realtime updates

Avoid timer-based loops such as:

  • setInterval(() => fetch(...), 1000)
  • periodic SELECT queries to detect row changes
  • fixed sleep loops to simulate streaming

These patterns add unnecessary load and increase staleness compared to server-push subscriptions.

Use topics and consumers for background workers

For worker pipelines and asynchronous processing, use topic consumers with ACK semantics:

  • createConsumerClient({...}).consumer({...}).run(handler)
  • runConsumer({...})

This is preferred over polling tables on a schedule.

Reliability defaults for AI-generated code

  • Keep writes idempotent.
  • Track and restore progress with sequence IDs / offsets when reconnecting.
  • Handle subscription error events explicitly.
  • Use bounded retries and onFailed persistence in agent/consumer flows.

Shared tables need CREATE POLICY

KalamDB shared tables enforce row-level security. Do not emit ACCESS_LEVEL table options. After creating a table with TYPE = 'SHARED', add CREATE POLICY grants for user and service. Prefer owner_id = CURRENT_USER or membership IN (SELECT … WHERE user_id = CURRENT_USER) over USING (true) unless every subscriber should see every change.

See Row-Level Security Architecture and CREATE POLICY SQL.

Environments & Deployment