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

> Discover over 20 cross-platform utilities in the WorldFlowAI/everything-claude-code repository. This reference guide details helper functions that work seamlessly on Windows, macOS, and Linux.

- Repository: [WorldFlowAI/everything-claude-code](https://github.com/WorldFlowAI/everything-claude-code)
- Tags: api-reference
- Published: 2026-09-07

---

**The [`scripts/lib/utils.js`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js) [lines 12–14](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L12-L14) 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](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L19-L21) |
| `getClaudeDir` | `~/.claude` config folder path | [lines 26–28](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L26-L28) |
| `getSessionsDir` | Path to Claude session files | [lines 33–35](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L33-L35) |
| `getLearnedSkillsDir` | Path to skill definitions | [lines 40–42](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L40-L42) |
| `getTempDir` | System temp directory via `os.tmpdir()` | [lines 46–48](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L46-L48) |
| `ensureDir` | Recursively creates directories if missing | [lines 54–58](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L54-L58) |

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](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L62-L70))
- **`getTimeString`** – returns `HH:MM` ([lines 74–80](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L74-L80))
- **`getDateTimeString`** – returns `YYYY-MM-DD HH:MM:SS` ([lines 84–94](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L84-L94))

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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js) module implements six file operations that abstract away common patterns:

**`findFiles`** ([lines 96–149](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L96-L149))
Recursively or non-recursively locate files matching glob patterns with optional age filtering.

```javascript
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](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L99-L105))
- `writeFile` ([lines 111–114](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L111-L114))
- `appendFile` ([lines 118–122](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L118-L122))

**`replaceInFile`** ([lines 188–196](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L188-L196))
Sed-like find-and-replace with regex support:

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

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

```

**`countInFile`** ([lines 200–206](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L200-L206))
Counts string or regex occurrences in a file.

**`grepFile`** ([lines 209–226](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L209-L226))
Cross-platform grep alternative returning matching lines with line numbers:

```javascript
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](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L53-L74)) – Parses JSON from stdin, used by hooks receiving structured data
- **`log`** ([lines 81–84](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L81-L84)) – Writes to stderr (visible in Claude Code UI)
- **`output`** ([lines 87–95](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L87-L95)) – Writes to stdout (returned to Claude as result)

## System Command Utilities

Four functions handle executable detection and process execution portably:

**`commandExists`** ([lines 126–136](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L126-L136))
Uses `where` on Windows, `which` elsewhere to verify PATH availability.

**`runCommand`** ([lines 140–154](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L140-L154))
Synchronous shell execution with captured output.

**Git Integration**
- **`isGitRepo`** ([lines 158–162](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L158-L162)) – detects `.git` presence
- **`getGitModifiedFiles`** ([lines 165–185](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js#L165-L185)) – lists changes relative to `HEAD` with optional pattern filtering

## Working with Cross-Platform Utilities: Practical Examples

### Creating Temporary Workspaces

```javascript
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

```javascript
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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js) | Core cross-platform utilities (documented above) |
| [`scripts/lib/package-manager.js`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/tests/lib/utils.test.js) | Cross-platform test coverage |

## Summary

- **20+ functions** in [`scripts/lib/utils.js`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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.