The Complete Production SOP: How to Deploy and Run tsx Zero-Config Node.js TypeScript Execution Engine in Autonomous AI Agents

Autonomous agents require declarative system capabilities before executing ad-hoc terminal tasks. By mounting the verified SKILL.md into your global or workspace agent configuration folder (`.agents/skills` or `.claude/skills`), runtimes like Claude Code, Codex, and Cursor can discover the trigger intents and bind procedural execution SOPs directly to their planner loops.

---
name: "tsx-zero-config-typescript-execute"
description: "Execute modern TypeScript and ESM files directly with Node.js without pre-compilation."
metadata:
  author: "Hiroki Osame"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "run typescript with tsx"
  - "tsx watch server.ts"
  - "execute ts without compile"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

To achieve deterministic command execution across varying developer workstations, the target repository should declare `tsx` as a development dependency. The agent should verify that `package.json` contains `tsx` or install it via the detected package manager, guaranteeing that tsx resolves tsconfig path mappings and ESM flags consistently.

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "node --import tsx src/index.ts"
  },
  "devDependencies": {
    "tsx": "^4.19.0",
    "typescript": "^5.5.0"
  }
}

When invoking tasks like executing seed scripts, background daemons, or scratchpad automation files, prompt the agent using unambiguous phrases declared in the SKILL.md triggers. The agent will bypass `tsc` compilation passes and directly invoke the `tsx` CLI runner.

import { resolve } from "node:path";

const bootstrap = async (): Promise<void> => {
  console.log(`Starting worker at ${resolve(".")}`);
  await new Promise((res) => setTimeout(res, 100));
  console.log("Initialization complete.");
};

await bootstrap();

Because tsx intentionally strips types via esbuild for maximum execution speed, the agent's procedural quality gate must run type verification independently before declaring a code change completed. This ensures runtime execution and static typing both pass.

import assert from "node:assert/strict";

const testHealthCheck = async () => {
  const status = 200;
  assert.equal(status, 200, "Status must return 200 OK");
  console.log("Smoke test passed successfully.");
};

await testHealthCheck();