ralph-tool 1.0.0

package/Dockerfile

@@ -0,0 +1,40 @@
+FROM node:20-bookworm
+
+# System deps
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  git bash ca-certificates curl ripgrep openssh-client \
+  jq bsdutils bc gosu \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+  && apt-get update && apt-get install -y gh \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install Claude Code globally
+RUN npm install -g @anthropic-ai/claude-code
+
+# Install ralph-tool globally from source
+COPY . /tmp/ralph-tool
+RUN npm install -g /tmp/ralph-tool && rm -rf /tmp/ralph-tool \
+  && ln -sf $(which ralph) /usr/local/bin/ralph
+
+# Prepare writable config dirs for the non-root user
+RUN mkdir -p /home/node/.config /home/node/.cache /home/node/.ssh \
+  && chown -R node:node /home/node/.config /home/node/.cache /home/node/.ssh
+
+# Add GitHub's SSH host key to known_hosts
+RUN ssh-keyscan github.com >> /home/node/.ssh/known_hosts \
+  && chown node:node /home/node/.ssh/known_hosts
+
+# Add entrypoint script
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+WORKDIR /workspace
+ENV TERM=xterm-256color
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["bash"]

package/README.md

@@ -0,0 +1,148 @@
+# Ralph
+
+AI-powered task automation for software development. Ralph orchestrates [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to implement features task-by-task — one task per iteration, fresh context every time, automatic PRs when done.
+
+## Install
+
+```bash
+npm install -g ralph-tool
+```
+
+> Ralph auto-installs required dependencies (`jq`, `bc`, `claude`) during setup. Docker and `gh` are optional.
+
+## Quick Start
+
+```bash
+cd my-project
+ralph init
+```
+
+This creates a `.ralph/` directory with all config, templates, and task files. Then choose your workflow:
+
+### Workflow A: Plan from Vision
+
+Best for greenfield projects or large feature sets. Define what you want, let Ralph plan the tasks.
+
+```bash
+# 1. Write your project vision (or use the Claude Code role to help)
+#    Edit .ralph/config/vision.md
+
+# 2. Ralph plans features + creates task specs from your vision
+ralph plan --max 20
+
+# 3. Ralph implements everything
+ralph start --max 50
+
+# 4. Review & merge PRs as they come
+ralph review
+```
+
+### Workflow B: Define Tasks Directly
+
+Best for adding specific features to an existing project.
+
+```bash
+# 1. Edit .ralph/tasks/prd.json with your features and tasks
+#    Optionally create spec files in .ralph/tasks/1_new_tasks/
+
+# 2. Configure build/test commands
+#    Edit .ralph/tasks/testing-harness.md
+
+# 3. Run it
+ralph start --max 10
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph init` | Initialize Ralph in current directory |
+| `ralph start [options]` | Run loop in Docker sandbox (recommended) |
+| `ralph loop [options]` | Run loop directly on your machine |
+| `ralph plan [options]` | Plan features from `vision.md` into tasks |
+| `ralph sandbox` | Open interactive Docker shell |
+| `ralph status` | Show current feature and task progress |
+| `ralph review` | Review latest PR and merge to main |
+| `ralph cleanup [feature]` | Archive completed features |
+| `ralph clear` | Clear iteration logs |
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max N` | 6 (start/loop), 10 (plan) | Maximum iterations |
+| `--model MODEL` | sonnet | Model to use: `sonnet`, `opus`, `haiku` |
+| `--local` | off | Commit locally only, skip branch/push/PR |
+
+## How It Works
+
+**Loop mode** (`start` / `loop`):
+
+1. Ralph picks the next incomplete task from `prd.json`
+2. Reads the task spec (if one exists) and delegates code exploration to subagents
+3. Implements the code changes, then runs your test harness
+4. On pass: marks task complete, updates progress. On fail: fixes and retests
+5. When all tasks in a feature are done → creates a git branch and PR automatically
+6. Repeat. Each iteration gets fresh context — state lives in files, not memory
+
+**Plan mode** (`plan`):
+
+1. Reads your `vision.md` and existing `prd.json`
+2. Identifies one unplanned area, explores the codebase
+3. Creates a detailed spec file and adds the feature + tasks to `prd.json`
+4. Every 5 iterations: runs a cleanup pass to consolidate and reorder
+5. Repeat until the vision is fully covered
+
+## Claude Code Roles
+
+Ralph ships with roles you can use directly in Claude Code (`@` mention the file):
+
+| Role | File | Purpose |
+|------|------|---------|
+| Vision Creator | `.ralph/roles/ralph-plan-vision.md` | Helps you write `vision.md` interactively |
+| Feature Planner | `.ralph/roles/ralph-plan-feature.md` | Plans a single feature with you |
+| Helper | `.ralph/roles/ralph-helper.md` | Explains Ralph concepts and usage |
+
+## Project Structure
+
+After `ralph init`:
+
+```
+.ralph/
+├── config/
+│   ├── prompt.md               # Loop orchestrator prompt
+│   ├── plan-prompt.md          # Planning orchestrator prompt
+│   ├── plan-cleanup-prompt.md  # Planning cleanup prompt
+│   ├── AGENT.md                # Persistent learnings (accumulates over time)
+│   ├── vision.md               # Your project vision (for plan mode)
+│   └── pr-review-prompt.md     # PR review template
+├── tasks/
+│   ├── prd.json                # Features and tasks definition
+│   ├── progress.txt            # Current iteration progress
+│   ├── testing-harness.md      # Build/test commands
+│   ├── feature-spec-template.md
+│   ├── 1_new_tasks/            # Active task spec files
+│   └── 2_done_tasks/           # Archived completed features
+├── roles/                      # Claude Code role files
+└── logs/                       # Iteration logs and cost tracking
+```
+
+## Key Concepts
+
+- **One task per iteration** — Ralph completes exactly one task, then exits. The loop script starts a new iteration with fresh context.
+- **File-based state** — All state lives in `prd.json`, `progress.txt`, and `AGENT.md`. No memory between iterations.
+- **AGENT.md** — Persistent knowledge base that accumulates learnings across all iterations and features. Never cleared automatically.
+- **Spec files** — Detailed implementation specs in `1_new_tasks/`. Created by `ralph plan` or manually.
+- **Testing harness** — Your build/test commands in `testing-harness.md`. Ralph runs these after every implementation.
+
+## Requirements
+
+- **Node.js** 18+
+- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
+- **Docker** — for `ralph start` / `ralph sandbox` (optional if using `ralph loop`)
+- **GitHub CLI** (`gh`) — for PR creation and `ralph review` (optional with `--local`)
+- **jq**, **bc** — auto-installed during `npm install`
+
+## License
+
+MIT

package/bin/ralph.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+
+// Colors matching culinary cloud style
+const cmd = chalk.bold.magenta;
+const title = chalk.bold.cyan;
+const dim = chalk.dim;
+
+// Resolve paths
+const RALPH_HOME = path.resolve(__dirname, '..');
+const PROJECT_DIR = process.cwd();
+const PROJECT_RALPH_DIR = path.join(PROJECT_DIR, '.ralph');
+
+// Set environment variables for child scripts
+process.env.RALPH_HOME = RALPH_HOME;
+process.env.PROJECT_DIR = PROJECT_DIR;
+process.env.PROJECT_RALPH_DIR = PROJECT_RALPH_DIR;
+
+// Helper: Check if .ralph exists
+function requireInit() {
+  if (!fs.existsSync(PROJECT_RALPH_DIR)) {
+    console.error(chalk.red('Error: .ralph/ not found in current directory'));
+    console.log('');
+    console.log("Run 'ralph init' first to initialize Ralph in this project.");
+    process.exit(1);
+  }
+}
+
+// Helper: Run a bash script (async — for non-interactive commands)
+function runScript(scriptName, args = []) {
+  const scriptPath = path.join(RALPH_HOME, 'scripts', scriptName);
+
+  if (!fs.existsSync(scriptPath)) {
+    console.error(chalk.red(`Error: Script not found: ${scriptPath}`));
+    process.exit(1);
+  }
+
+  const child = spawn('bash', [scriptPath, ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, RALPH_HOME, PROJECT_DIR, PROJECT_RALPH_DIR }
+  });
+
+  child.on('close', (code) => {
+    process.exit(code || 0);
+  });
+}
+
+// Helper: Run a bash script synchronously (for interactive/TTY commands like sandbox)
+function runScriptSync(scriptName, args = []) {
+  const scriptPath = path.join(RALPH_HOME, 'scripts', scriptName);
+
+  if (!fs.existsSync(scriptPath)) {
+    console.error(chalk.red(`Error: Script not found: ${scriptPath}`));
+    process.exit(1);
+  }
+
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, RALPH_HOME, PROJECT_DIR, PROJECT_RALPH_DIR }
+  });
+
+  process.exit(result.status || 0);
+}
+
+// Helper: Copy directory recursively
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Init command
+function doInit() {
+  if (fs.existsSync(PROJECT_RALPH_DIR)) {
+    console.log(chalk.yellow('Warning: .ralph/ already exists in this directory'));
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    rl.question('Overwrite? (y/N) ', (answer) => {
+      rl.close();
+      if (answer.toLowerCase() !== 'y') {
+        console.log('Aborted.');
+        process.exit(0);
+      }
+      performInit();
+    });
+  } else {
+    performInit();
+  }
+}
+
+function performInit() {
+  console.log(chalk.green(`Initializing Ralph in ${PROJECT_DIR}`));
+  console.log('');
+
+  // Create directory structure
+  console.log('[1/3] Creating directory structure...');
+  fs.mkdirSync(path.join(PROJECT_RALPH_DIR, 'config'), { recursive: true });
+  fs.mkdirSync(path.join(PROJECT_RALPH_DIR, 'tasks', '1_new_tasks'), { recursive: true });
+  fs.mkdirSync(path.join(PROJECT_RALPH_DIR, 'tasks', '2_done_tasks'), { recursive: true });
+  fs.mkdirSync(path.join(PROJECT_RALPH_DIR, 'logs', 'progress'), { recursive: true });
+  fs.mkdirSync(path.join(PROJECT_RALPH_DIR, 'roles'), { recursive: true });
+  console.log(chalk.green('  ✓') + ' Directories created');
+
+  // Copy templates
+  console.log('[2/3] Copying templates...');
+  const templatesDir = path.join(RALPH_HOME, 'templates');
+
+  // Config files
+  fs.copyFileSync(
+    path.join(templatesDir, 'prompt.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'prompt.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'AGENT.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'AGENT.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'pr-review-prompt.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'pr-review-prompt.md')
+  );
+
+  // Task files
+  fs.copyFileSync(
+    path.join(templatesDir, 'testing-harness.md'),
+    path.join(PROJECT_RALPH_DIR, 'tasks', 'testing-harness.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'feature-spec-template.md'),
+    path.join(PROJECT_RALPH_DIR, 'tasks', 'feature-spec-template.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'prd.json'),
+    path.join(PROJECT_RALPH_DIR, 'tasks', 'prd.json')
+  );
+
+  // Plan mode files
+  fs.copyFileSync(
+    path.join(templatesDir, 'vision.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'vision.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'plan-prompt.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'plan-prompt.md')
+  );
+  fs.copyFileSync(
+    path.join(templatesDir, 'plan-cleanup-prompt.md'),
+    path.join(PROJECT_RALPH_DIR, 'config', 'plan-cleanup-prompt.md')
+  );
+
+  // Role files
+  copyDir(
+    path.join(templatesDir, 'roles'),
+    path.join(PROJECT_RALPH_DIR, 'roles')
+  );
+
+  // Create empty progress file
+  fs.writeFileSync(path.join(PROJECT_RALPH_DIR, 'tasks', 'progress.txt'), '');
+
+  console.log(chalk.green('  ✓') + ' Templates copied');
+
+  // Done
+  console.log('[3/3] Done!');
+  console.log('');
+  console.log(chalk.green('Ralph initialized successfully!'));
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Plan a feature: @.ralph/roles/ralph-plan-feature.md in Claude Code');
+  console.log('  2. Edit .ralph/tasks/testing-harness.md for your build/test commands');
+  console.log('  3. Run \'ralph start\' to begin');
+  console.log('');
+}
+
+// Custom help display
+function showHelp() {
+  console.log('');
+  console.log(title('Ralph - AI Task Automation CLI'));
+  console.log('');
+  console.log(`Usage: ralph ${dim('{command} [options]')}`);
+  console.log('');
+  console.log('Commands:');
+  console.log(`  ${cmd('init')}`);
+  console.log('      Initialize Ralph in current directory (creates .ralph/)');
+  console.log('');
+  console.log(`  ${cmd('start')} ${dim('[--max N] [--model MODEL] [--local]')}`);
+  console.log('      Open Docker sandbox and start loop inside container');
+  console.log('');
+  console.log(`  ${cmd('sandbox')}`);
+  console.log('      Open interactive Docker shell');
+  console.log('');
+  console.log(`  ${cmd('loop')} ${dim('[--max N] [--model MODEL] [--local]')}`);
+  console.log('      Start Ralph loop directly (default: 6 iterations, sonnet-4-5)');
+  console.log('');
+  console.log(`  ${cmd('plan')} ${dim('[--max N] [--model MODEL]')}`);
+  console.log('      Plan features from vision.md (default: 10 iterations, cleanup every 5)');
+  console.log('');
+  console.log(`  ${cmd('status')}`);
+  console.log('      Check current PRD task status');
+  console.log('');
+  console.log(`  ${cmd('clear')}`);
+  console.log('      Clear all log files (keeps progress)');
+  console.log('');
+  console.log(`  ${cmd('review')}`);
+  console.log('      Review latest PR, merge to main');
+  console.log('');
+  console.log(`  ${cmd('cleanup')} ${dim('[feature]')}`);
+  console.log('      Archive completed features');
+  console.log('');
+  console.log(`  ${cmd('help')}`);
+  console.log('      Show this help message');
+  console.log('');
+  console.log('Options:');
+  console.log(`  ${cmd('--max N')}          Maximum iterations (default: 6)`);
+  console.log(`  ${cmd('--model MODEL')}    AI model: sonnet, opus, haiku (default: sonnet)`);
+  console.log(`  ${cmd('--local')}           Commit locally, skip branch/push/PR creation`);
+  console.log('');
+  console.log('Examples:');
+  console.log(`  ralph ${cmd('init')}                          # Set up Ralph in your project`);
+  console.log(`  ralph ${cmd('start')} --max 5 --model haiku   # Run in Docker with haiku`);
+  console.log(`  ralph ${cmd('loop')}                           # Run loop directly`);
+  console.log(`  ralph ${cmd('loop')} --max 10 --model opus    # 10 iterations with opus`);
+  console.log(`  ralph ${cmd('plan')}                           # Plan features from vision`);
+  console.log(`  ralph ${cmd('plan')} --max 20 --model opus    # Deep planning with opus`);
+  console.log(`  ralph ${cmd('status')}                         # Check task progress`);
+  console.log('');
+}
+
+// Setup CLI — disable commander's built-in help entirely
+program
+  .name('ralph')
+  .version('1.0.0')
+  .helpOption(false)
+  .addHelpCommand(false)
+  .configureOutput({
+    outputError: () => {},  // suppress commander error output
+  });
+
+program
+  .command('init')
+  .description('Initialize Ralph in current directory')
+  .action(doInit);
+
+program
+  .command('start')
+  .option('--max <n>', 'Maximum iterations', '6')
+  .option('--model <model>', 'AI model: sonnet, opus, haiku')
+  .option('--local', 'Local mode: commit but skip branch/push/PR creation')
+  .action((options) => {
+    requireInit();
+    if (options.local) process.env.RALPH_LOCAL = '1';
+    console.log(chalk.dim('Starting Docker container...'));
+    runScriptSync('start.sh', [options.max, options.model || '']);
+  });
+
+program
+  .command('sandbox')
+  .action(() => {
+    requireInit();
+    console.log(chalk.green('Opening Docker sandbox...'));
+    runScriptSync('sandbox.sh');
+  });
+
+program
+  .command('loop')
+  .option('--max <n>', 'Maximum iterations', '6')
+  .option('--model <model>', 'AI model: sonnet, opus, haiku')
+  .option('--local', 'Local mode: commit but skip branch/push/PR creation')
+  .action((options) => {
+    requireInit();
+    if (options.local) process.env.RALPH_LOCAL = '1';
+    console.log(chalk.dim('Starting Ralph loop...'));
+    const promptFile = path.join(PROJECT_RALPH_DIR, 'config', 'prompt.md');
+    runScript('loop.sh', [promptFile, options.max, options.model || '']);
+  });
+
+program
+  .command('plan')
+  .option('--max <n>', 'Maximum iterations', '10')
+  .option('--model <model>', 'AI model: sonnet, opus, haiku')
+  .action((options) => {
+    requireInit();
+    const visionFile = path.join(PROJECT_RALPH_DIR, 'config', 'vision.md');
+    if (!fs.existsSync(visionFile)) {
+      console.error(chalk.red('Error: Vision file not found at .ralph/config/vision.md'));
+      console.log('');
+      console.log('Create your vision first:');
+      console.log('  Use @.ralph/roles/ralph-plan-vision.md in Claude Code');
+      process.exit(1);
+    }
+    console.log(chalk.dim('Starting Ralph planning loop...'));
+    runScript('plan-loop.sh', [options.max, options.model || '']);
+  });
+
+program
+  .command('status')
+  .action(() => {
+    requireInit();
+    runScript('status.sh');
+  });
+
+program
+  .command('clear')
+  .action(() => {
+    requireInit();
+    runScript('clear.sh');
+  });
+
+program
+  .command('review')
+  .action(() => {
+    requireInit();
+    runScript('review.sh');
+  });
+
+program
+  .command('cleanup [feature]')
+  .action((feature) => {
+    requireInit();
+    runScript('cleanup.sh', feature ? [feature] : []);
+  });
+
+program
+  .command('help')
+  .action(() => showHelp());
+
+// Intercept before commander parses: handle no args, help, and --help
+const args = process.argv.slice(2);
+const firstArg = args[0];
+
+if (!firstArg || firstArg === 'help' || firstArg === '--help' || firstArg === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+// Unknown commands → show help
+program.on('command:*', () => {
+  console.error(chalk.red(`Error: Unknown command '${args[0]}'`));
+  showHelp();
+  process.exit(1);
+});
+
+program.parse();

package/docker-compose.yaml

@@ -0,0 +1,40 @@
+services:
+  ai:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    working_dir: /workspace
+    environment:
+      - TERM=xterm-256color
+      - CLAUDE_CONFIG_DIR=/home/node/.config/claude
+      - SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock
+      - RALPH_HOME=/ralph-tool
+      - GIT_USER_NAME=${GIT_USER_NAME:-}
+      - GIT_USER_EMAIL=${GIT_USER_EMAIL:-}
+    volumes:
+      # Project directory mounted to /workspace (set by ralph CLI)
+      # This is handled dynamically by the start.sh script
+
+      # Ralph tool installation
+      - .:/ralph-tool:ro
+
+      # Persistent volumes for configs
+      - claude_config:/home/node/.config/claude
+      - claude_workspace:/workspace/.claude
+      - gh_config:/home/node/.config/gh
+
+      # SSH agent for git operations
+      - type: bind
+        source: /run/host-services/ssh-auth.sock
+        target: /run/host-services/ssh-auth.sock
+
+      # Git config (read-only)
+      - ~/.gitconfig:/home/node/.gitconfig:ro
+
+    stdin_open: true
+    tty: true
+
+volumes:
+  claude_config:
+  claude_workspace:
+  gh_config:

package/helpers/constants.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Constants for Ralph Loop
+
+# Configuration constants
+MAX_CHARS="${MAX_CHARS:-4000}"
+MAX_LINES_FOR_TOOL_RESULT=4
+DEFAULT_MODEL="claude-sonnet-4.5"
+
+# Fun names for Ralph
+RALPH_NAMES=(
+  "YOLO RALPH COOKING"
+  "RALPH IN THE MATRIX"
+  "RALPH MODE: ACTIVATED"
+  "RALPH.EXE RUNNING"
+  "EMPLOYEE OF THE MONTH RALPH"
+  "RALPH IS SPEEEEEEEEEED"
+  "BUSINESS MONEY GETTING BURNED BY RAAAALLLPPPHHHHH"
+  "CRACKHEAD RALPH TO THE RESCUE"
+  "BUSINESSSSSSS ISS RAAAAALLLLPPPPHHHH"
+  "RALPH: PROCESSING..."
+  "RALPH COOKING SOME TOOOKKKEEENNNNN FOR BUSINESSSSSSS"
+)

package/helpers/cost_helpers.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Cost calculation helpers for Ralph loop
+
+# Model pricing lookup (bash 3.2 compatible — no associative arrays)
+# Returns: input_base cache_write_5m cache_write_1h cache_hit output (per million tokens)
+get_model_pricing() {
+  case "$1" in
+    claude-opus-4-5)    echo "5.0 6.25 10.0 0.50 25.0" ;;
+    claude-opus-4-1)    echo "15.0 18.75 30.0 1.50 75.0" ;;
+    claude-opus-4)      echo "15.0 18.75 30.0 1.50 75.0" ;;
+    claude-sonnet-4-5)  echo "3.0 3.75 6.0 0.30 15.0" ;;
+    claude-sonnet-3-5)  echo "3.0 3.75 6.0 0.30 15.0" ;;
+    claude-haiku-3)     echo "0.25 0.30 1.25 0.03 1.25" ;;
+    *)                  echo "3.0 3.75 6.0 0.30 15.0" ;;  # default to sonnet pricing
+  esac
+}
+
+# Function to normalize model name for pricing lookup
+normalize_model_name() {
+  local model="$1"
+  echo "$model" | tr '[:upper:]' '[:lower:]' | sed 's/\./-/g' | sed 's/-[0-9]\{8\}$//' | sed 's/[^a-z0-9-]/-/g' | sed 's/--*/-/g'
+}
+
+# Function to calculate cost based on model and usage
+calculate_cost() {
+  local model="$1"
+  local input_tokens="$2"
+  local output_tokens="$3"
+  local cache_read_tokens="$4"
+  local cache_write_tokens="$5"
+
+  local normalized_model
+  normalized_model=$(normalize_model_name "$model")
+  local pricing
+  pricing=$(get_model_pricing "$normalized_model")
+
+  local input_price cache_write_price cache_hit_price output_price
+  input_price=$(echo "$pricing" | awk '{print $1}')
+  cache_write_price=$(echo "$pricing" | awk '{print $2}')
+  cache_hit_price=$(echo "$pricing" | awk '{print $4}')
+  output_price=$(echo "$pricing" | awk '{print $5}')
+
+  local input_cost output_cost cache_read_cost cache_write_cost total_cost
+  input_cost=$(echo "scale=6; ($input_tokens * $input_price) / 1000000" | bc)
+  output_cost=$(echo "scale=6; ($output_tokens * $output_price) / 1000000" | bc)
+  cache_read_cost=$(echo "scale=6; ($cache_read_tokens * $cache_hit_price) / 1000000" | bc)
+  cache_write_cost=$(echo "scale=6; ($cache_write_tokens * $cache_write_price) / 1000000" | bc)
+
+  total_cost=$(echo "scale=6; $input_cost + $output_cost + $cache_read_cost + $cache_write_cost" | bc)
+
+  echo "$total_cost"
+}
+
+# Function to format token count (add commas)
+format_tokens() {
+  local tokens="$1"
+  if [[ -z "$tokens" ]] || [[ "$tokens" == "null" ]] || [[ "$tokens" == "0" ]]; then
+    echo "0"
+  else
+    echo "$tokens" | awk '{printf "%'"'"'d\n", $1}'
+  fi
+}
+
+# Function to format cost
+format_cost() {
+  local cost="$1"
+  if [[ -z "$cost" ]] || [[ "$cost" == "null" ]] || [[ "$cost" == "0" ]]; then
+    echo "\$0.00"
+  else
+    local formatted=$(printf "%.4f" "$cost" | sed 's/0*$//' | sed 's/\.$//')
+    printf "\$%s\n" "$formatted"
+  fi
+}