Claude as a callable

Claude Code is not just a chat tool. It’s a CLI. That means you can call it from your own deterministic programs, treat it as a subroutine, and embed LLM judgment inside otherwise-traditional pipelines.

The CLI surface

At its simplest:

claude -p "summarize this log" < yesterday.log

Claude Code reads the prompt, optionally reads stdin, runs a one-shot session, and prints the result. No interactive REPL, no session state: just in, out.

Flags worth knowing (check the current docs for the full list):

• -p, --print: run non-interactively and print the result
• --permission-mode: control what the agent can do (default, acceptEdits, plan, auto, dontAsk, bypassPermissions)
• --allowed-tools: restrict which tools Claude can call in this invocation
• --output-format json: return structured output instead of prose

Shell scripts

A shell script can invoke Claude anywhere you’d otherwise write a bespoke rule. Example: a nightly content audit.

#!/bin/bash
claude -p "Review content/ for broken links and stale references. Output a markdown summary." \
  --permission-mode auto \
  --allowed-tools Read,Grep,Glob,WebFetch \
  > audit-$(date +%F).md

Then cron or a systemd timer fires it on a schedule. Claude sees what you point it at, does the task, writes a file.

Structured output

For pipelines that consume Claude’s output programmatically, --output-format json returns structured results (exit status, token counts, final message content, tool-call sequences) instead of free-form prose.

Common patterns:

• Classification: Claude classifies an input; your downstream code branches on the label.
• Extraction: Claude pulls structured fields from messy input (names, dates, amounts).
• Decision: Claude judges whether something passes a gate (e.g., “is this PR safe to auto-merge?”); your code acts on the verdict.

The prompt determines the schema. Claude follows it reliably if you’re explicit.

Exit codes, retries, and failure modes

A non-zero exit code from claude means the session didn’t complete successfully, usually a tool failure, auth issue, or timeout. Handle it like any other shell failure: retry, log, alert.

Common failure modes to plan for:

• Rate limits: back off and retry.
• Transient tool errors: Claude may recover, but on a one-shot call it can’t. Retry once before giving up.
• Ambiguous outputs: Claude produces valid JSON but with wrong content. Validate the result outside the call; don’t trust the first answer for critical branches.

Treat Claude calls the way you’d treat any external service: not 100% reliable, worth retrying, always worth validating.

One-shot vs. full session

When to use a callable one-shot vs. an interactive session:

• One-shot: the task is well-defined, the output is structured or summarizable, no follow-up conversation is needed. Great for cron jobs, CI hooks, automated pipelines.
• Full session: the task is exploratory, you need to iterate, or the agent needs to ask clarifying questions.

If you find yourself wanting to run a full session non-interactively, that’s usually a sign the task should be broken into smaller one-shots, or the prompt needs to be more complete upfront.

Common patterns

Real things people wire up with callable Claude:

• Nightly content audit: scan the content tree, flag stale docs, output a review list.
• Log triage: read yesterday’s logs, classify errors by type, draft an incident summary.
• PR review assistant: on PR open, run a Claude-based reviewer that posts structured comments.
• Data extraction: pull structured fields out of unstructured inbox or document queues.
• Scheduled research refresh: weekly rerun of a competitor/landscape scan, write results to docs/.

The Claude Agent SDK

For deeper programmatic use, the Claude Agent SDK packages up the same harness that powers Claude Code and makes it available in Python and TypeScript. Anthropic also offers Managed Agents: server-hosted agents where Anthropic runs the loop and the sandbox. Use the SDK when you’re building a product that needs Claude-as-agent as a first-class component.

Resources

• Anthropic: Claude Code CLI reference
• Anthropic: Building agents with the Claude Agent SDK