Skip to main content

CLI Agent Models

Run Claude Code or Codex as your agent's model for long-running, tool-driven agentic tasks.​

Why Use CLI Agent Models​

A chat completion answers one prompt in one pass. Some tasks need more: researching a topic across your knowledge bases, iterating on generated files, or working through a multi-step plan that calls tools dozens of times. Squeezing that into single completions means orchestrating every step yourself.

CLI agent models put a full agentic CLI, Claude Code or Codex, behind the same agent API you already use. Squid runs the CLI server-side in an isolated session; the CLI plans, invokes your agent's tools, and iterates until the task is done:

Client code
await squid.ai().agent('research-assistant').updateModel('claude-code');

const jobId = crypto.randomUUID();
await squid.ai().agent('research-assistant').askAsync('Compare our Q1 and Q2 sales data and summarize the trends', jobId);

// An askAsync job resolves with the agent's answer as a plain string.
const answer = await squid.job().awaitJob<string>(jobId);

Overview​

CLI agent models are selected exactly like vendor models: pass the model name to upsert(), updateModel(), or the model ask option (see Building AI agents). Instead of calling a chat completions API, Squid launches the corresponding CLI in a sandboxed session, forwards your agent's instructions and tools, and returns the CLI's final response.

Available models​

Model nameProvider CLIRunsContext window
claude-codeClaude CodeThe CLI's default model tier200K tokens
claude-code-opusClaude CodeThe latest Opus tier200K tokens
claude-code-sonnetClaude CodeThe latest Sonnet tier200K tokens
claude-code-haikuClaude CodeThe latest Haiku tier200K tokens
codexCodexThe CLI's default model272K tokens
codex-gpt-5.5CodexGPT-5.5272K tokens
codex-gpt-5.4CodexGPT-5.4272K tokens
codex-gpt-5.4-miniCodexGPT-5.4 Mini272K tokens
codex-gpt-5.3-codexCodexGPT-5.3 Codex272K tokens

Claude Code tiers track the latest model of each tier automatically; the Codex variants pin specific models. All CLI agent models support up to 64K output tokens.

When to use a CLI agent model​

Use CaseRecommendation
Multi-step tasks that chain many tool callsCLI agent model
Long-running research or analysis (minutes of work)CLI agent model with askAsync() + jobs
Fast conversational responses with token streamingA vendor chat model (e.g. 'claude-sonnet-4-6', 'gpt-5.5')
Simple Q&A over a knowledge baseA vendor chat model with knowledge bases

How it works​

  1. You select a CLI agent model for your agent and send an ask
  2. Squid starts an isolated CLI session server-side, passing your agent's instructions
  3. The agent's AI functions, connected integrations, and knowledge bases are exposed to the CLI as MCP tools
  4. The CLI plans, calls tools, and iterates until the task completes; the ask runs as a long-running job
  5. The final response is returned; conversation state persists in the CLI session for follow-up asks

Quick Start​

Step 1: Add the provider API key​

CLI agent models use your own provider API key, configured under Settings > AI Settings in the Squid Console:

  • Claude Code models require an Anthropic API key
  • Codex models require an OpenAI API key

Step 2: Select the model​

Client code
await squid.ai().agent('research-assistant').updateModel('claude-code');

Or override per-request with the model ask option.

Step 3: Ask, and track the run as a job​

CLI agent runs can take minutes, so avoid holding a single request open. Pass a job ID and await it through the jobs API:

Client code
const jobId = crypto.randomUUID();

await squid.ai().agent('research-assistant').askAsync('Audit our onboarding docs for outdated steps', jobId);

// Optionally, observe interim progress (tool calls, status messages).
const statusSubscription = squid
  .ai()
  .agent('research-assistant')
  .observeStatusUpdates(jobId)
  .subscribe((status) => console.log(status));

// An askAsync job resolves with the agent's answer as a plain string.
const answer = await squid.job().awaitJob<string>(jobId);
statusSubscription.unsubscribe();

Core Concepts​

Long-running execution​

Every CLI agent ask runs as a long-running job, with a default and maximum wall time of 30 minutes. To bound a run more tightly, set quotas.maxRuntimeSeconds in the ask options (clamped between 30 seconds and 30 minutes):

Client code
await squid
  .ai()
  .agent('research-assistant')
  .askAsync('Summarize the support tickets from this week', jobId, {
    quotas: { maxRuntimeSeconds: 300 },
  });

maxRuntimeSeconds is ignored for non-CLI-agent models.

Sessions and conversation memory​

Conversation state lives in the CLI's own session, which Squid persists and resumes across asks according to the agent's memory options. Because the CLI manages its own transcript, the conversation does not appear in Squid's chat history APIs.

Switching between variants of the same provider (for example claude-code to claude-code-opus) resumes the same session, so a conversation can continue across model tiers.

One ask runs at a time per agent conversation. A concurrent ask for the same conversation is rejected with a busy message asking to retry shortly.

Shared workspaces​

By default each conversation works in its own isolated directory. To share files across asks, or across different agents, pass a sharedWorkspaceId in the ask options. Asks with the same workspace ID operate in the same persistent working directory:

Client code
await squid.ai().agent('report-writer').askAsync('Draft the quarterly report as report.md', jobId, {
  sharedWorkspaceId: 'q3-reporting',
});

Workspace IDs may contain letters, numbers, underscores, and dashes (up to 200 characters). The option is ignored for non-CLI-agent models.

Tools via MCP​

CLI agent models access your agent's abilities through MCP rather than native function calling:

  • AI functions and connected integrations are exposed as MCP tools the CLI can invoke
  • Knowledge bases are exposed as search tools; the CLI queries them on demand instead of receiving retrieved context in the prompt

This gives the CLI control over when and how often to consult each source during a task.

Limitations​

LimitationDetail
No token streamingThe response arrives when the run completes. Use observeStatusUpdates() for interim progress.
No file uploadThe file upload APIs are not supported with CLI agent models
Structured outputresponseFormat: 'json_object' is supported; JSON schema-guaranteed output is not
Chat history APIsTranscripts live in the CLI session and are not returned by Squid's chat history methods
One run per conversationConcurrent asks on the same conversation are rejected with a busy error; retry after the active run

Error Handling​

IssueCauseSolution
Ask fails with a missing API key messageNo provider key configured for the selected modelAdd the Anthropic (Claude Code) or OpenAI (Codex) key under Settings > AI Settings
Busy / retry responseAnother ask is already running in the same conversationWait for the active run to finish, then retry
Run ends at the time limitThe task exceeded maxRuntimeSeconds (or the 30-minute max)Split the task into smaller asks, or raise maxRuntimeSeconds up to the cap

Best Practices​

  1. Use askAsync() with a job ID. CLI agent runs routinely take minutes; awaiting the job keeps your app responsive and survives page reloads (any client with the ID can await it).
  2. Show progress. Subscribe to observeStatusUpdates(jobId) so users see tool activity instead of a silent multi-minute wait.
  3. Bound runtimes for interactive flows. Set quotas.maxRuntimeSeconds when a user is actively waiting; reserve the full 30 minutes for background tasks.
  4. Use shared workspaces for multi-step workflows. A stable sharedWorkspaceId lets successive asks (or cooperating agents) build on each other's files.
  5. Pin Codex variants for reproducibility. codex-gpt-5.5 and friends pin exact models; claude-code-* tiers track the latest release of each tier.

Next Steps​