code-style

Code Style & Patterns

Detailed coding conventions, tool implementation patterns, and common patterns for the Open Agents codebase.

Package Manager

• Use pnpm exclusively for dependency management
• The monorepo uses [email protected] through Corepack
• Use Node 24's built-in TypeScript support for utility scripts
• Use Bun only as the test runner

TypeScript Configuration

• Strict mode enabled
• Target: ESNext with module "Preserve"
• noUncheckedIndexedAccess: true - always check indexed access
• verbatimModuleSyntax: true - use explicit type imports

Formatting (Ultracite — oxfmt)

• Indent: 2 spaces
• Quote style: double quotes for JavaScript/TypeScript
• Run pnpm fix before committing

Naming Conventions

• Files: kebab-case (e.g., deep-agent.ts, paste-blocks.ts)
• Types/Interfaces: PascalCase (e.g., TodoItem, AgentContext)
• Functions/Variables: camelCase (e.g., getSandbox, workingDirectory)
• Constants: UPPER_SNAKE_CASE for true constants (e.g., TIMEOUT_MS, SAFE_COMMAND_PREFIXES)

Imports

• Do NOT use .js extensions in imports (e.g., import { foo } from "./utils" not "./utils.js")
  • The .js extension causes module resolution issues with Next.js/Turbopack
  • This applies to all packages and apps in the monorepo
• Use explicit .ts extensions in modules loaded directly by Node 24 utility scripts
• Prefer named exports over default exports
• Group imports: external packages first, then internal packages, then relative imports
• Use type imports when importing only types: import type { Foo } from "./types"

Types

• Never use any - use unknown and narrow with type guards
• Define schemas with Zod, then derive types: type Foo = z.infer<typeof fooSchema>
• Prefer interfaces for object shapes, types for unions/intersections
• Export types alongside their related functions

Error Handling

• Return structured error objects rather than throwing when possible:

  return { success: false, error: `Failed to read file: ${message}` };
  

• When catching errors, extract message safely:

  const message = error instanceof Error ? error.message : String(error);
  

• Use descriptive error messages that include context (tool name, file path, etc.)