cybara CLAUDE.md

AI Coding Rules for Cybara Agent Platform

This document contains coding standards and best practices for AI assistants working on this codebase.

No Code Comments (STRICT)

Do NOT write comments in code. No //, /* */, #, JSDoc, or docstring comments — not for explaining "why", not for section headers, not for TODOs, not in TypeScript, tests, scripts, Swift, or config. Write self-explanatory code with clear names instead. Never reference competitors or other products in code or comments. This is a hard rule: if a change adds a comment, remove it before finishing. Existing comments may stay; do not add new ones.

Runtime Environment

• Runtime: Bun (not Node.js)
• Package Manager: bun
• TypeScript: Strict mode enabled

Import Rules

✅ DO

// Static imports at top of file
import { homedir } from "os";
import { readFileSync, existsSync, statSync } from "fs";
import { tables } from "./database";

// No .js extension in imports (ESM standard)
import { config } from "../core/config";

❌ DON'T

// No require() - use import instead
const fs = require("fs"); // BAD

// No require() for os.homedir()
process.env.HOME || require("os").homedir(); // BAD

// Prefer: 
import { homedir } from "os";
process.env.HOME || homedir(); // GOOD

Dynamic Imports (when acceptable)

Dynamic imports are acceptable ONLY for:

1. Circular dependency avoidance - when two modules import each other
2. Optional dependencies - like Playwright which may not be installed
3. Lazy loading at startup - to speed up initial load time

// Acceptable: Optional dependency
const { chromium } = await import("playwright");

// Acceptable: Circular dependency avoidance
const { listSessions } = await import("../api/chat");

Bun Native APIs

Use Bun.spawnSync instead of child_process

// ❌ DON'T
import { execSync } from "child_process";
const output = execSync("which rg", { encoding: "utf-8" });

// ✅ DO
const result = Bun.spawnSync(["which", "rg"]);
const output = result.stdout.toString();

// For shell commands:
const result = Bun.spawnSync(["sh", "-c", "complex | shell | command"]);