tweakcc: Instructions file for Codex

AGENTS.md

This document provides guidelines for agentic coding assistants working in this repository.

Development Commands

# Build
pnpm build           # Production build (typecheck + minify)
pnpm build:dev       # Development build (no minification)
pnpm watch           # Watch mode for iterative development

# Testing
pnpm test            # Run all tests once
pnpm test:dev        # Run tests in watch mode
npx vitest run <test-file>     # Run single test file
pnpm run test -- <pattern>     # Run tests matching pattern

# Linting & Formatting
pnpm lint            # Typecheck + ESLint
pnpm format          # Format code with Prettier

# Run CLI
pnpm start           # Run built CLI
node dist/index.mjs  # Alternative run command

Making changes

Whenever you make a logical change that belongs in one commit, update the changelog at the bottom of the "Unreleased" section. It should follow the format Change description (#PR) - @author. The change description should usually be the PR title unless there are multiple logical changes in the same PR that each deserve their own item.

Imports

// Group imports in this order:
import fs from 'node:fs/promises'; // Node.js built-ins (use node: prefix)
import path from 'node:path';
import chalk from 'chalk'; // Third-party libraries
import ink from 'ink';
import { getConfig } from '@/config'; // Internal imports (use @/ alias)
import { PatchConfig } from '@/types';

TypeScript

• Strict mode enabled in tsconfig.json
• Avoid any: Use unknown with type guards or as unknown as Type for assertions
• Interfaces for complex objects, types for simple unions
• Custom errors: Extend Error class with name property

export class CustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'CustomError';
  }
}

Naming Conventions

• Files: camelCase for logic (config.ts), PascalCase for React components (MainView.tsx)
• Functions: camelCase (getConfig, detectInstallation)
• Constants: UPPER_SNAKE_CASE (CONFIG_DIR, DEFAULT_CONFIG)
• Components: PascalCase with descriptive names (ThinkingVerbsView)
• Interfaces: PascalCase, descriptive (StringsPrompt, MarkdownPrompt)