@agentskit/cross-platform β for agents
One place for OS and runtime portability. Spawn, paths, line endings and filesystem that behave the same on Windows, macOS and Linux under Node, Bun and Deno.
#Install
npm install @agentskit/cross-platform#Why
Windows contributors kept fixing the same bugs in every repository: .cmd shims (npx, pnpm, claude) failing without a shell, prompts truncated at the first newline by cmd.exe, \ vs / in path comparisons, CRLF breaking hashes and frontmatter, EBUSY on rename, and child processes left running after a timeout. This package owns those fixes and the libraries behind them (cross-spawn, tree-kill, pathe, std-env, graceful-fs, which). See ADR-0036.
#Primary exports
#Processes
spawnProcess(command, args?, options?)β returns aChildHandlewith web-streamstdin/stdout/stderr, anexitedpromise and a tree-widekill(). Never throws for a failed start:exitedrejects withCrossPlatformError.runCommand(command, args?, options?)β runs to completion; resolves{ code, signal, stdout, stderr, timedOut, truncated, durationMs }. A non-zero exit is a result, not an error.spawnShell(commandLine, options?)/runShell(commandLine, options?)β same handle/result, but through the platform shell (sh -con POSIX,%ComSpec% /d /s /con Windows). Only for command lines a user wrote (hooks, scripts).shellCommand(line, env)returns that invocation.spawnNodeChild(command, args?, options?)βchild_process.spawnwith the same resolution (.cmdshims, cmd.exe escaping, child PATH), for code that needs Node streams and events (JSON-RPC over stdio, long-lived servers). A missing command emits the usual'error'(ENOENT); pair it withkillProcessTree.selectAdapter(runtime?)β the native adapter:node:child_process,Bun.spawnorDeno.Command.resolveCommand(command, args, { cwd, env })β Windows command resolution and cmd.exe escaping (cross-spawn's parser).killProcessTree(pid, signal?, fallback?)βtaskkill /T /Fon Windows; on POSIX a tree walk plus the process grouppidleads (children spawned withdetached: true), so descendants whose parent already exited are reached too.findExecutable(command)/commandExists(command)β PATH lookup honouringPATHEXT.safeEnv({ inherit?, extra?, source? })β minimal child env withSYSTEM_ENV_KEYS(PATH,PATHEXT,SystemRoot,COMSPECβ¦).getEnv(name)is case-insensitive on Windows.homeDir(),tempDir().
Options: cwd, env, input (written to stdin, then closed), stdin/stdout/stderr (pipe | inherit | ignore), timeoutMs, killGraceMs, signal (AbortSignal), windowsHide (default true), and for runCommand/runShell maxOutputBytes (per stream).
#Paths and file URLs
toPosix,normalizePosix,joinPosix,resolvePosix,relativePosix,basename,dirname,extnameβ/output on every OS (pathe).samePath(a, b),isPathInside(parent, child)β separator-, trailing-slash- and (on Windows) case-insensitive.isAbsolutePath,isWindowsStylePath.fileUrlToPath,pathToFileUrl,moduleDir(import.meta.url),isMainModule(import.meta.url)β never usenew URL(...).pathname.
#Text
normalizeEol,stripBom,splitLines,splitFrontmatter(CRLF/BOM tolerant),hashText(SHA-256 after EOL normalisation; Web Crypto).
#Filesystem
removePath(rm -rf with retries),renamePath(graceful-fs retries on Windows locks),writeFileAtomic(temp file on the same volume, then rename),createSymlink(junction/copy fallback without Windows symlink privilege),copyPath,setFileMode(no-op on Windows; returns false).
#Testing helpers
Import createFetchStub, jsonResponse, and withTempDir from
@agentskit/cross-platform/testing. They have no test-runner dependency;
withTempDir uses this package's OS temp-directory and retrying cleanup helpers.
#Runtime and errors
getRuntimeInfo()β{ runtime, os, platform, isServer };isWindows,isMacOS,isLinux,isBun,isDeno(std-env).CrossPlatformError,CrossPlatformErrorCodes(AK_PLATFORM_PERMISSION_DENIED,AK_PLATFORM_COMMAND_NOT_FOUND,AK_PLATFORM_SPAWN_FAILED,AK_PLATFORM_INVALID_INPUT,AK_PLATFORM_UNSUPPORTED_RUNTIME),isPermissionError,isNotFoundError,mapRuntimeError,permissionDenied.
#Guardrail
PORTABILITY_RULES,scanText,scanRepository,countFindings,compareToBaseline,tightenBaseline,runCliβ back theagentskit-cross-platform checkbin (ratchet baseline in.cross-platform-baseline.json;runCliaccepts optional{ rules, filter }for custom ratchets;cross-platform-ignore: <reason>skips every rule on the line, and<rule-id>-ignore: <reason>skips only that rule).
#Source layout
packages/cross-platform/src/process/β spawn, run, kill, command resolution and the Node, Bun and Deno adapters behindspawnProcess,runCommandandkillProcessTree.packages/cross-platform/src/lint/β the guardrail:rules.ts,scan.ts,baseline.tsand thecli.tsbehindagentskit-cross-platform check.
#Usage
import { runCommand, spawnProcess } from '@agentskit/cross-platform'
const result = await runCommand('claude', ['-p', '--output-format', 'json'], {
input: longMultiLinePrompt,
timeoutMs: 120_000,
})
const child = spawnProcess('npx', ['-y', '@modelcontextprotocol/server-filesystem', '.'])
for await (const chunk of child.stdout!) process.stdout.write(chunk)#Notes
@agentskit/cross-platform/pureexposes paths, text and runtime detection withoutnode:imports (browsers, edge workers).- Deno: missing
--allow-run/--allow-read/--allow-write/--allow-envraisesAK_PLATFORM_PERMISSION_DENIEDnaming the flag. It never prompts. - Supported: Node β₯ 20.19, Bun β₯ 1.2, Deno β₯ 2.0 on Windows, macOS and Linux (CI matrix).
Explore nearby
- PeerFor agents β overview
Dense, LLM-friendly reference for every AgentsKit package. Designed to paste into an agent's context window.
- Peer@agentskit/core β for agents
Zero-dependency foundation. Contracts, chat controller, primitives, and a dozen feature subpaths.
- Peer@agentskit/adapters β for agents
Provider adapters (OpenAI-compatible + native) + router + ensemble + fallback + generic factory.
@agentskit/sandbox β for agents
Secure code execution (E2B / Web Worker / local runtimes) + mandatory sandbox policy wrapper.
@agentskit/net β for agents
HTTP plumbing over web APIs. Retries with Retry-After, per-attempt timeouts, bounded body reads, SSE parsing and SSRF address checks on Node, Bun, Deno, browsers and edge.