CLI Agents

import { CodexAgent, Task, Workflow, createSmithers } from "smthrs";
import { z } from "zod";

const { smithers, outputs } = createSmithers({
  analysis: z.object({ summary: z.string() }),
});

const reviewer = new CodexAgent({
  model: "gpt-5.6-sol",
  systemPrompt: "You are a careful code reviewer.",
  sandbox: "read-only",
  timeoutMs: 30 * 60 * 1000,
});

export default smithers((ctx) => (
  <Workflow name="review">
    <Task id="analysis" output={outputs.analysis} agent={reviewer}>
      {`Analyze the codebase and identify potential improvements.`}
    </Task>
  </Workflow>
));

agents[17]{class,cli,modelDefault,hijack,notes}:
  CodexAgent,codex,CLI default,native thread id,OpenAI Codex CLI (codex exec via stdin + JSON stream)
  ClaudeCodeAgent,claude,CLI default,native session id,Anthropic Claude Code CLI
  CursorAgent,cursor-agent,CLI default,not yet,Cursor CLI (cursor-agent --print stream-json)
  AntigravityAgent,agy,CLI default,native session id,Google Antigravity CLI
  GeminiAgent,gemini,CLI default,legacy session id,Deprecated legacy Gemini CLI wrapper
  PiAgent,pi,CLI default,native session id,Pi CLI (text/json/rpc modes + extension UI hooks)
  OmpAgent,omp,CLI default,native session id,Oh My Pi OMP harness (text/json/rpc modes)
  KimiAgent,kimi,CLI default,native session id,Moonshot Kimi CLI (auto-isolates KIMI_SHARE_DIR)
  GrokAgent,grok,CLI default,not yet,xAI Grok Build CLI (streaming JSON + native session resume)
  ForgeAgent,forge,CLI default,conversation id,Forge CLI (300+ models)
  HermesCliAgent,hermes,CLI default,session id,Nous Research Hermes Agent CLI (hermes -z headless)
  AmpAgent,amp,CLI default,thread id,Amp CLI (--execute headless mode)
  VibeAgent,vibe,CLI default,headless session id,Mistral Vibe CLI
  OpenCodeAgent,opencode,CLI default,not yet,OpenCode CLI (opencode run --format json)
  OpenClawAgent,openclaw,CLI default,session id,OpenClaw CLI (openclaw agent --json)
  PoolAgent,pool,CLI default,not yet,Poolside Pool CLI (ACP + NDJSON stream)
  NanocodexAgent,smithers-nanocodex,gpt-5.6-sol (default; terra/luna),checkpoint resume,Nanocodex bridge (Linux x64 / macOS arm64)

import { OmpAgent } from "smthrs";

const omp = new OmpAgent({
  provider: "openai",
  model: "gpt-5.6-terra",
  cwd: process.cwd(),
  autoApprove: true,
});

import { CodexAgent, Task, Workflow, createSmithers } from "smthrs";
import { z } from "zod";

const { smithers, outputs } = createSmithers({
  patch: z.object({ summary: z.string(), files: z.array(z.string()) }),
});

const codex = new CodexAgent({
  model: "gpt-5.6-luna",
  config: { model_reasoning_effort: "medium" },
  sandbox: "workspace-write",
  skipGitRepoCheck: true,
  yolo: true,
});

export default smithers(() => (
  <Workflow name="codex-implementation">
    <Task id="implement" output={outputs.patch} agent={codex}>
      Implement the requested change and summarize the edited files.
    </Task>
  </Workflow>
));

bunx smthrs agents reauth --provider claude-code --include-default

import { fallbackAgents } from "smthrs";

<Task
  agent={fallbackAgents({
    seed: ctx.runId,
    providers: ["claude-code"],
    models: { "claude-code": "claude-fable-5" },
    fallback: [],
    agentOptions: {
      "claude-code": {
        permissionMode: "bypassPermissions",
        dangerouslySkipPermissions: true,
      },
    },
  })}
  {...taskProps}
/>

bunx smthrs cancel RUN_ID
bunx smthrs up .smithers/workflows/WORKFLOW.tsx -d

bunx smthrs claude-shell -- --model claude-fable-5

import { ClaudeCodeAgent } from "smthrs";

// Subscription billing, pinned to an isolated login dir (no API key):
const claude = new ClaudeCodeAgent({
  model: "claude-fable-5",
  configDir: "/home/me/.claude-work", // CLAUDE_CONFIG_DIR for this invocation
});

// API billing (switches off subscription auth):
const apiClaude = new ClaudeCodeAgent({
  model: "claude-fable-5",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

import { ClaudeCodeAgent } from "smthrs";
import { z } from "zod";

const schema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const claude = new ClaudeCodeAgent({
  model: "claude-fable-5",
  outputFormat: "json",
  tools: "", // no tools, pure completion
  // no apiKey → bills your Claude Pro/Max subscription
});

const controller = new AbortController();
const result = await claude.generate({
  prompt:
    "Classify the sentiment of this review and summarize it in one sentence. " +
    'Respond with ONLY a raw JSON object: {"sentiment": "...", "summary": "..."}. ' +
    "First character `{`, last character `}`, no prose or code fences.\n\n" +
    "Review: Shipping was slow but the product is excellent.",
  outputSchema: schema,
  timeout: { totalMs: 2 * 60 * 1000, idleMs: 30 * 1000 },
  abortSignal: controller.signal,
});

const parsed = schema.parse(result.output ?? JSON.parse(result.text));
console.log(parsed.sentiment, parsed.summary);

import { CodexAgent } from "smthrs";
import { z } from "zod";

const schema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const codex = new CodexAgent({
  model: "gpt-5.6-luna",
  config: { model_reasoning_effort: "medium" },
  nativeStructuredOutput: true, // forwards outputSchema as --output-schema
  // no apiKey → bills your ChatGPT subscription
});

const result = await codex.generate({
  prompt:
    "Classify the sentiment of this review and summarize it in one sentence.\n\n" +
    "Review: Shipping was slow but the product is excellent.",
  outputSchema: schema,
  timeout: { totalMs: 2 * 60 * 1000, idleMs: 30 * 1000 },
});

const parsed = schema.parse(result.output);
console.log(parsed.sentiment, parsed.summary);

type BaseCliAgentOptions = {
  id?: string;                       // Agent instance id (default: random UUID)
  model?: string;                    // Model name passed to --model
  systemPrompt?: string;             // Prepended to the user prompt
  instructions?: string;             // Alias for systemPrompt
  cwd?: string;                      // Working directory (default: tool ctx rootDir or process.cwd())
  env?: Record<string, string>;      // Extra env vars merged with process.env
  yolo?: boolean;                    // Skip permission prompts (default: true)
  timeoutMs?: number;                // Hard wall-clock cap
  idleTimeoutMs?: number;            // Inactivity cap; resets on any stdout/stderr
  maxOutputBytes?: number;           // Truncate captured output
  extraArgs?: string[];              // Additional CLI flags appended to the command
  recoveryPolicy?: CliRecoveryPolicy; // Provider retry/recovery policy (see below)
};

import { CodexAgent } from "smthrs";
import { createHttp429RecoveryClassifier } from "@smthrs/agents/BaseCliAgent";

const agent = new CodexAgent({
  recoveryPolicy: {
    maxAttempts: 3,          // total attempts including the first
    maxElapsedMs: 120_000,   // bound on the whole recovery window
    backoffMs: (attempt) => 1000 * 2 ** attempt,
    classifyError: createHttp429RecoveryClassifier(),
  },
});

await agent.generate({
  prompt: "do the thing",
  timeout: { totalMs: 15 * 60 * 1000, idleMs: 2 * 60 * 1000 },
});

import { ClaudeCodeAgent } from "smthrs";
new ClaudeCodeAgent({
  permissionMode?: "acceptEdits" | "bypassPermissions" | "default" | "delegate" | "dontAsk" | "plan";
  allowedTools?: string[]; disallowedTools?: string[]; disableSlashCommands?: boolean;
  addDir?: string[]; file?: string[]; fromPr?: string; fallbackModel?: string;
  appendSystemPrompt?: string; agents?: Record<string, { description?: string; prompt?: string }> | string;
  agent?: string; tools?: string[] | "default" | "";
  betas?: string[]; pluginDir?: string[]; resume?: string; sessionId?: string;
  mcpConfig?: string[]; mcpDebug?: boolean; maxBudgetUsd?: number; jsonSchema?: string;
  configDir?: string; apiKey?: string;
  normalizeUsage?: (rawResult: unknown) => NormalizedTokenUsage | null | undefined;
  dangerouslySkipPermissions?: boolean; allowDangerouslySkipPermissions?: boolean; chrome?: boolean; noChrome?: boolean;
  continue?: boolean; forkSession?: boolean; noSessionPersistence?: boolean; replayUserMessages?: boolean;
  debug?: boolean | string; debugFile?: string; ide?: boolean; includePartialMessages?: boolean;
  inputFormat?: "text" | "stream-json"; settingSources?: string; settings?: string; strictMcpConfig?: boolean; verbose?: boolean;
  outputFormat?: "text" | "json" | "stream-json"; // default stream-json
});

const reviewer = new ClaudeCodeAgent({
  model: "claude-fable-5",
  allowedTools: ["Read", "Write"],   // may read and write files
  disallowedTools: ["Bash"],          // but never execute shell commands
});

import { ClaudeCodeAgent, createDeepSeekUsageNormalizer } from "smthrs";

const deepseek = new ClaudeCodeAgent({
  model: "deepseek-chat",
  env: { ANTHROPIC_BASE_URL: "https://api.deepseek.com/anthropic" },
  normalizeUsage: createDeepSeekUsageNormalizer(),
});

const agent = new ClaudeCodeAgent({
  model: "claude-fable-5",
  mcpConfig: [
    "./.mcp.json",                                                   // a file path
    '{"mcpServers":{"fs":{"command":"npx","args":["@modelcontextprotocol/server-filesystem","."]}}}', // inline JSON
  ],
  strictMcpConfig: true, // ignore any other MCP sources, use only mcpConfig
});

import { CodexAgent } from "smthrs";
new CodexAgent({
  sandbox?: "read-only" | "workspace-write" | "danger-full-access";
  fullAuto?: boolean; dangerouslyBypassApprovalsAndSandbox?: boolean;
  config?: Record<string, string | number | boolean | object | null> | string[];
  enable?: string[]; disable?: string[];
  oss?: boolean; localProvider?: string;
  image?: string[]; profile?: string; cd?: string; addDir?: string[];
  skipGitRepoCheck?: boolean; color?: "always" | "never" | "auto";
  outputSchema?: string; outputLastMessage?: string; json?: boolean;
  configDir?: string; apiKey?: string;
});

import { CursorAgent } from "smthrs";
new CursorAgent({
  apiKey?: string; header?: string[];
  model?: string; mode?: "plan" | "ask"; plan?: boolean;
  force?: boolean; autoReview?: boolean; sandbox?: "enabled" | "disabled";
  approveMcps?: boolean; trust?: boolean; workspace?: string;
  pluginDir?: string[]; resume?: string | boolean; continueSession?: boolean;
  worktree?: string | boolean; worktreeBase?: string; skipWorktreeSetup?: boolean;
  streamPartialOutput?: boolean;
});

import { AntigravityAgent } from "smthrs";
new AntigravityAgent({
  model?: string; sandbox?: boolean;
  yolo?: boolean; dangerouslySkipPermissions?: boolean;
  allowedMcpServerNames?: string[]; allowedTools?: string[];
  conversation?: string; continue?: boolean; resume?: string;
  includeDirectories?: string[];
  extensions?: string[]; listExtensions?: boolean;
  listSessions?: boolean; deleteSession?: string;
  screenReader?: boolean; outputFormat?: "text" | "json" | "stream-json";
  debug?: boolean;
  binary?: string; configDir?: string; geminiDir?: string; apiKey?: string;
  // Deprecated and rejected at runtime: debug, screenReader, outputFormat,
  // extensions, listExtensions, listSessions, deleteSession.
});

import { GeminiAgent } from "smthrs";
new GeminiAgent({
  debug?: boolean; model?: string; sandbox?: boolean; yolo?: boolean;
  approvalMode?: "default" | "auto_edit" | "yolo" | "plan";
  experimentalAcp?: boolean;
  allowedMcpServerNames?: string[]; allowedTools?: string[];
  extensions?: string[]; listExtensions?: boolean;
  resume?: string; listSessions?: boolean; deleteSession?: string;
  includeDirectories?: string[]; screenReader?: boolean;
  outputFormat?: "text" | "json" | "stream-json";
  configDir?: string; apiKey?: string;
});

import { PiAgent, type PiExtensionUiRequest, type PiExtensionUiResponse } from "smthrs";
new PiAgent({
  provider?: string; model?: string; apiKey?: string; appendSystemPrompt?: string; mode?: "text" | "json" | "rpc";
  print?: boolean; continue?: boolean; resume?: boolean; session?: string;
  sessionDir?: string; noSession?: boolean;
  models?: string | string[]; listModels?: boolean | string;
  extension?: string[]; skill?: string[]; promptTemplate?: string[]; theme?: string[];
  noExtensions?: boolean; noSkills?: boolean; noPromptTemplates?: boolean; noThemes?: boolean;
  tools?: string[]; noTools?: boolean; files?: string[];
  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
  export?: string; verbose?: boolean;
  onExtensionUiRequest?: (req: PiExtensionUiRequest) => Promise<PiExtensionUiResponse | null> | PiExtensionUiResponse | null;
});

import { KimiAgent } from "smthrs";
new KimiAgent({
  cliVersion?: "0.29";               // argv dialect for @moonshot-ai/kimi-code@0.29.x
  thinking?: boolean; outputFormat?: "text" | "stream-json";
  finalMessageOnly?: boolean; quiet?: boolean;
  agent?: "default" | "okabe"; agentFile?: string;
  workDir?: string; session?: string; continue?: boolean; addDir?: string[];
  skillsDir?: string; mcpConfigFile?: string[]; mcpConfig?: string[];
  maxStepsPerTurn?: number; maxRetriesPerStep?: number; maxRalphIterations?: number;
  verbose?: boolean; debug?: boolean; configDir?: string; // sets KIMI_SHARE_DIR (see below)
  credentialDir?: string; runtimeDir?: string; sessionStateDir?: string;
  wireUsage?: boolean | { path?: string; maxBytes?: number; maxEntries?: number; maxFiles?: number; maxDirectories?: number };
  sessionRecovery?: boolean | {
    onSessionResolved?: (info: { sessionId: string; source: "output" | "session-index"; homeDir?: string; stateDir?: string }) => void;
    maxBytes?: number; maxFiles?: number; maxDirectories?: number;
  };
});

import { GrokAgent } from "smthrs";
const grok = new GrokAgent({
  configDir: "/secure/grok-account", // sets GROK_HOME
  effort: "high",
  maxTurns: 20,
});

bunx smthrs agents add --provider grok --label grok-main --tmux

import { ForgeAgent } from "smthrs";
new ForgeAgent({
  directory?: string; provider?: string; agent?: string;
  conversationId?: string; sandbox?: string; restricted?: boolean;
  verbose?: boolean; workflow?: string; event?: string; conversation?: string;
});

import { HermesCliAgent } from "smthrs";
new HermesCliAgent({
  model?: string; provider?: string;
  continueSession?: string | boolean;
});

import { OpenClawAgent } from "smthrs";
new OpenClawAgent({
  agent?: string;
  session?: string;
  workspace?: string;
  json?: boolean;
  continueSession?: boolean;
});

import { AmpAgent } from "smthrs";
new AmpAgent({
  visibility?: "private" | "public" | "workspace" | "group";
  mcpConfig?: string; settingsFile?: string;
  logLevel?: "error" | "warn" | "info" | "debug" | "audit"; logFile?: string;
  dangerouslyAllowAll?: boolean; ide?: boolean; jetbrains?: boolean;
});

import { VibeAgent } from "smthrs";
new VibeAgent({
  agent?: string;
  maxTurns?: number; maxPrice?: number; maxTokens?: number;
  enabledTools?: string[];
  sessionId?: string; continueSession?: boolean;
});

import { OpenCodeAgent } from "smthrs";
new OpenCodeAgent({
  model: "provider/model",
  agentName: "readonly",
  attachFiles: ["src/main.ts"],
  variant: "high",
});

import { PoolAgent } from "smthrs";
new PoolAgent({
  agentName: "default",
  sandbox: "required",
  resumeSession: "session-id",
});