Runtime API

The runtime module provides functions for executing prompts through local AI agent CLIs, managing configurations, and detecting available providers.

runPrompt()

Execute a single prompt with the configured provider.

import { runPrompt, loadRunConfig, detectProviders, resolveRunProvider } from "prompts-gpt";

const config = await loadRunConfig(process.cwd());
const providers = await detectProviders();
const provider = resolveRunProvider(config.defaultAgent, providers, config.providerOrder);

const result = await runPrompt({
  promptFile: ".prompts-gpt/code-review.md",
  provider,
  model: "gpt-5.5",
  timeoutSeconds: 900,
  cwd: process.cwd(),
  artifactsDir: ".scripts/runs",
});

console.log(result.ok);         // boolean
console.log(result.exitCode);   // number
console.log(result.durationMs); // number
console.log(result.outputFile); // string

RunPromptInput

Property	Type	Required	Description
`promptFile`	`string`	Yes	Path to prompt Markdown file
`provider`	`string`	Yes	Provider name (codex/claude/cursor/copilot)
`model`	`string`	No	Model override
`timeoutSeconds`	`number`	No	Execution timeout
`cwd`	`string`	No	Working directory
`artifactsDir`	`string`	No	Artifacts output directory
`runId`	`string`	No	Custom run ID
`sandbox`	`string`	No	Codex sandbox mode
`permissionMode`	`string`	No	Claude permission mode
`background`	`boolean`	No	Cursor background mode

RunPromptResult

Property	Type	Description
`ok`	`boolean`	Whether execution succeeded
`provider`	`string`	Provider used
`model`	`string`	Model used
`exitCode`	`number`	Process exit code
`durationMs`	`number`	Execution time in ms
`outputFile`	`string`	Path to raw output log
`summaryFile`	`string`	Path to extracted summary
`tokenUsage`	`TokenUsage`	Token consumption metrics
`error`	`string`	Error message (if failed)

runBatch()

Execute multiple prompt files in sequence.

import { runBatch } from "prompts-gpt";

const result = await runBatch({
  promptFiles: [
    ".prompts-gpt/review.md",
    ".prompts-gpt/tests.md",
    ".prompts-gpt/docs.md",
  ],
  provider: "codex",
  model: "gpt-5.4",
  timeoutSeconds: 600,
  cwd: process.cwd(),
});

console.log(`${result.succeeded}/${result.results.length} succeeded`);

RunBatchInput

Property	Type	Description
`promptFiles`	`string[]`	Array of prompt file paths
`provider`	`string`	Provider name
`model`	`string`	Model override
`timeoutSeconds`	`number`	Timeout per prompt
`cwd`	`string`	Working directory
`artifactsDir`	`string`	Artifacts directory

RunBatchResult

Property	Type	Description
`results`	`RunPromptResult[]`	Per-prompt results
`totalDurationMs`	`number`	Total execution time
`succeeded`	`number`	Count of successful runs
`failed`	`number`	Count of failed runs

loadRunConfig()

Load the run configuration from .prompts-gpt/config.json.

import { loadRunConfig } from "prompts-gpt";

const config = await loadRunConfig(process.cwd());
console.log(config.defaultAgent);     // "router"
console.log(config.providerOrder);    // ["codex", "cursor", "claude"]
console.log(config.timeoutSeconds);   // 900
console.log(config.modelOverrides);   // { codex: "gpt-5.5" }

ResolvedRunConfig

Property	Type	Description
`defaultAgent`	`string`	Default orchestration profile
`providerOrder`	`string[]`	Provider priority order
`timeoutSeconds`	`number`	Default timeout
`retryCount`	`number`	Default retry count
`artifactsDir`	`string`	Artifacts directory path
`modelOverrides`	`Record<string, string>`	Per-provider model defaults
`disallowDestructiveGit`	`boolean`	Block destructive git ops
`defaultPromptFile`	`string`	Default prompt file for `run`
`batchPromptFiles`	`string[]`	Default files for `run-batch`
`batchManifest`	`string`	Default manifest for `run-batch`

detectProviders()

Detect which AI agent CLIs are installed and available.

import { detectProviders } from "prompts-gpt";

const providers = await detectProviders();
for (const p of providers) {
  console.log(`${p.provider}: v${p.version ?? "unknown"}`);
}
// codex: v1.0.12
// claude: v1.0.30
// cursor: v0.46.0

Returns ProviderHealth[]:

Property	Type	Description
`provider`	`string`	Provider name
`available`	`boolean`	Whether CLI is found
`version`	`string \	null`	CLI version
`path`	`string \	null`	Binary path

resolveRunProvider()

Select the best provider based on agent profile and availability.

import { resolveRunProvider, detectProviders, loadRunConfig } from "prompts-gpt";

const config = await loadRunConfig();
const providers = await detectProviders();

const provider = resolveRunProvider(
  config.defaultAgent,  // "router"
  providers,
  config.providerOrder  // ["codex", "cursor"]
);
// Returns: "codex" (first available in order)

doctor()

Run prerequisite checks programmatically.

import { doctor } from "prompts-gpt";

const report = await doctor();
console.log(report.nodeVersion);  // "v22.0.0"
console.log(report.providers);    // ProviderHealth[]

Utility Functions

Token Usage

import { extractTokenUsageFromLog, aggregateTokenUsage, emptyTokenUsage } from "prompts-gpt";

const usage = extractTokenUsageFromLog(logContent);
const total = aggregateTokenUsage([usage1, usage2]);

Git Utilities

import { isGitRepo, hasUncommittedChanges, captureGitHead, captureGitBranch } from "prompts-gpt";

const isRepo = await isGitRepo(cwd);
const dirty = await hasUncommittedChanges(cwd);
const head = await captureGitHead(cwd);
const branch = await captureGitBranch(cwd);

Model Resolution

import { resolveModelAlias, getModelCostTier, estimateTokenCost } from "prompts-gpt";

const model = resolveModelAlias("gpt-5.5", "codex");
const tier = getModelCostTier(model);
const cost = estimateTokenCost(model, inputTokens, outputTokens);