Cross-Platform Utilities in the scripts Directory: Complete Reference Guide

The scripts/lib/utils.js module in everything-claude-code provides 20+ battle-tested helper functions that work identically on Windows, macOS, and Linux.

The scripts directory in WorldFlowAI/everything-claude-code contains a robust utility layer designed to eliminate OS-specific quirks from Claude Code automation scripts. Every function relies on pure Node.js standard library APIs—fs, path, os, and child_process—ensuring behavior remains consistent regardless of host platform.

Platform Detection Utilities

Three boolean flags expose the current operating system without manual process.platform parsing:

• isWindows – true when process.platform === 'win32'
• isMacOS – true when process.platform === 'darwin'
• isLinux – true when process.platform === 'linux'

These are defined in scripts/lib/utils.js lines 12–14 and provide the foundation for conditional logic in cross-platform scripts.

Directory Helpers

The cross-platform utilities include six standardized path resolvers that handle OS-specific directory conventions automatically:

Function	Return Value	Source Location
getHomeDir	User home directory via os.homedir()	lines 19–21
getClaudeDir	~/.claude config folder path	lines 26–28
getSessionsDir	Path to Claude session files	lines 33–35
getLearnedSkillsDir	Path to skill definitions	lines 40–42
getTempDir	System temp directory via os.tmpdir()	lines 46–48
ensureDir	Recursively creates directories if missing	lines 54–58

The ensureDir utility is particularly valuable—it eliminates ENOENT errors by automatically creating parent directories before file operations.

Date and Time Formatting

Three formatting functions produce consistent, sortable strings across all platforms:

• getDateString – returns YYYY-MM-DD (lines 62–70)
• getTimeString – returns HH:MM (lines 74–80)
• getDateTimeString – returns YYYY-MM-DD HH:MM:SS (lines 84–94)

These use toLocaleString with fixed options rather than platform-dependent locale defaults, guaranteeing deterministic output for logging and file naming.

File System Utilities

The scripts/lib/utils.js module implements six file operations that abstract away common patterns:

findFiles (lines 96–149) Recursively or non-recursively locate files matching glob patterns with optional age filtering.

const { findFiles, getSessionsDir } = require('./scripts/lib/utils');

// Find .tmp files modified within last 7 days
const files = findFiles(getSessionsDir(), '*.tmp', {
  maxAge: 7,
  recursive: true
});

Safe File I/O (readFile, writeFile, appendFile) These auto-create parent directories and handle encoding consistently:

• readFile (lines 99–105)
• writeFile (lines 111–114)
• appendFile (lines 118–122)

replaceInFile (lines 188–196) Sed-like find-and-replace with regex support:

const { replaceInFile } = require('./scripts/lib/utils');

replaceInFile('config.md', /{{VERSION}}/g, process.env.npm_package_version);

countInFile (lines 200–206) Counts string or regex occurrences in a file.

grepFile (lines 209–226) Cross-platform grep alternative returning matching lines with line numbers:

const matches = grepFile('log.txt', /ERROR/);
// Returns: [{ line: 42, content: 'ERROR: connection failed' }, ...]

Process I/O Helpers

Three functions standardize communication with Claude Code's execution environment:

• readStdinJson (lines 53–74) – Parses JSON from stdin, used by hooks receiving structured data
• log (lines 81–84) – Writes to stderr (visible in Claude Code UI)
• output (lines 87–95) – Writes to stdout (returned to Claude as result)

System Command Utilities

Four functions handle executable detection and process execution portably:

commandExists (lines 126–136) Uses where on Windows, which elsewhere to verify PATH availability.

runCommand (lines 140–154) Synchronous shell execution with captured output.

Git Integration

• isGitRepo (lines 158–162) – detects .git presence
• getGitModifiedFiles (lines 165–185) – lists changes relative to HEAD with optional pattern filtering

Working with Cross-Platform Utilities: Practical Examples

Creating Temporary Workspaces

const path = require('path');
const {
  getTempDir,
  ensureDir,
  writeFile,
  log
} = require('./scripts/lib/utils');

function setupHookWorkspace(hookName) {
  const workDir = path.join(getTempDir(), 'claude-hook', hookName);
  ensureDir(workDir);
  writeFile(path.join(workDir, 'startedAt'), getDateTimeString());
  log(`Workspace ready: ${workDir}`);
  return workDir;
}

Processing Learned Skills Files

const path = require('path');
const {
  getLearnedSkillsDir,
  findFiles,
  replaceInFile,
  grepFile
} = require('./scripts/lib/utils');

const skillsDir = getLearnedSkillsDir();
const draftFiles = findFiles(skillsDir, '*.draft.md');

// Update version placeholders in all drafts
draftFiles.forEach(file => {
  replaceInFile(file, /{{SKILL_VERSION}}/g, '1.0.0');
});

// Find TODO markers
const todos = grepFile(path.join(skillsDir, 'index.md'), /TODO:/);
console.log(`${todos.length} items pending`);

Related Files in the scripts Directory

File	Purpose
scripts/lib/utils.js	Core cross-platform utilities (documented above)
scripts/lib/package-manager.js	Package manager abstractions (npm, yarn, pnpm) built on base utilities
scripts/hooks/*.js	Production examples consuming these utilities
tests/lib/utils.test.js	Cross-platform test coverage

Summary

• 20+ functions in scripts/lib/utils.js eliminate OS-specific code from Claude Code scripts
• Pure Node.js implementation using fs, path, os, child_process only—no native dependencies
• Platform detection via isWindows/isMacOS/isLinux booleans
• Directory normalization through getHomeDir, getClaudeDir, ensureDir, and related helpers
• Portable file operations including findFiles, replaceInFile, grepFile with glob and regex support
• Git and shell integration via commandExists, runCommand, getGitModifiedFiles

Frequently Asked Questions

How do I check if a command exists before running it?

Use commandExists from scripts/lib/utils.js. It automatically selects where on Windows and which on Unix-like systems, returning a boolean without executing the target command.

Can I use these utilities outside of Claude Code hooks?

Yes. The utilities are standard Node.js modules with no Claude-specific dependencies. Import them from scripts/lib/utils.js in any Node.js script requiring cross-platform file system or shell operations.

What happens if ensureDir receives a deeply nested path?

It recursively creates all missing parent directories using fs.mkdirSync with { recursive: true }, identical to mkdir -p behavior on Unix or mkdir -Force on PowerShell.

Are these utilities tested on all three platforms?

The repository includes tests/lib/utils.test.js with automated verification. The pure Node.js standard library approach minimizes platform-specific edge cases, though CI typically runs against Windows, macOS, and Linux runners for confirmation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}