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

RunPromptResult

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

RunBatchResult

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

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[]:

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);

See Also

• Sweep API
• Orchestration API
• Types Reference