Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
84 lines (58 loc) · 2.56 KB

DEVELOPMENT.md

File metadata and controls

84 lines (58 loc) · 2.56 KB

Developer Guide

To use the plugin from source:

git clone https://github.com/timescale/crayon.git
cd crayon
pnpm install
pnpm build

Note: This outputs the claude --plugin-dir <path> command you need to run Claude Code with the local plugin.

Local Development

crayon local run-dev starts the auth-server alongside the dev UI so you can test cloud features (cron scheduling, webhook tokens) locally. This command is only available when running from the monorepo.

Prerequisites

  1. Auth-server .env.local must exist at packages/auth-server/.env.local with the required env vars (see packages/auth-server/README.md). It should point to the same DATABASE_URL as the deployed auth-server so your CLI token works. Contents can be found in 1password "Crayon auth-server secrets".

  2. CLI login — run crayon login once so ~/.crayon/credentials has a valid token.

Usage

npx tsx /path/to/crayon/packages/core/src/cli/index.ts local run-dev

This will:

  • Start the auth-server on http://localhost:3000
  • Set CRAYON_SERVER_URL and CRAYON_TOKEN automatically
  • Launch the dev UI with cloud features enabled (webhook section, cron scheduling)
  • Open the browser and start Claude Code

To see changes in the local you need to build and refresh browser

pnpm --filter runcrayon build 2>&1

Testing Local Changes On Cloud

To test local core changes on a cloud dev machine:

  1. Build & push a Docker image with your changes:

    cd packages/core/docker && ./build-dev.sh <tag>

  2. Start the local auth server (separate terminal):

    cd packages/auth-server && pnpm dev

  3. Create a new cloud machine using the local auth server:

    CRAYON_SERVER_URL=http://localhost:3000 pnpm --filter runcrayon exec node dist/cli/index.js cloud run

  4. Open the dev UI at https://<fly-app-name>.fly.dev/dev/

Testing Custom Images On Cloud

You can create a cloud sandbox with a specific Docker image tag without modifying the auth-server's CLOUD_DEV_IMAGE env var.

crayon cloud run --image-tag <tag>

This creates the sandbox using registry.fly.io/crayon-cloud-dev-image:<tag> instead of the default :latest.

Workflow

  1. Build and push your image with a custom tag:

    cd packages/core/docker && ./build-dev.sh my-feature

  2. Create a sandbox using that tag:

    crayon cloud run --image-tag my-feature

This is useful for testing changes in isolation without affecting other developers' sandboxes that use the default image.