Claude Code — Execution Methods

Ten ways to trigger Claude Code to execute, from interactive to fully automated.

Why / When to Use

Use this to decide which execution method fits your use case — whether you want to explore interactively, automate CI/CD, embed in a service, or schedule unattended tasks.

Core Concept

The foundation for all non-interactive execution is the -p flag or the SDK. Everything else (hooks, routines, CI) is built on top of that.

The 10 Methods

1. Interactive Terminal (REPL)

Default mode. Run claude in terminal. Type prompts, Claude responds turn-by-turn.

claude

2. Headless / Non-Interactive (-p flag)

Runs task, prints to stdout, exits. Core of all automation.

claude -p "Find and fix the bug in auth.py"

3. Piped Stdin

Pipe data in, redirect output out — works like any Unix tool.

cat build-error.txt | claude -p "Explain the root cause" > output.txt
git diff HEAD~1 | claude -p "Review this diff"

4. Shell Scripts / Batch Automation

Multi-step pipelines. Use --resume with a session ID to chain calls while preserving context.

SESSION=$(claude -p "Analyze architecture" --output-format json | jq -r '.session_id')
claude -p "Now generate missing tests" --resume "$SESSION"

5. GitHub Actions (Event-Triggered)

Official Claude Code GitHub Action. Triggers on pull_request.opened, issue_comment, push, etc. Turns natural language requests in issues/PRs into code changes.

on:
  pull_request:
    types: [opened, synchronize]

6. Python / TypeScript SDK

Claude Code SDK (released June 11 2025). Structured outputs, tool approval callbacks, native message objects. Embed in any backend service.

# Production-ready agent integration

7. Hooks (Lifecycle Event Triggers)

Deterministic shell commands at specific points in Claude Code’s workflow. Unlike prompting, hooks guarantee execution regardless of model behaviour.

Key hook events:

• PreToolUse — fires before any tool execution (can block/approve)
• PostToolUse — fires after tool completion
• UserPromptSubmit — fires when a prompt is submitted
• Stop / SubagentStop — fires when Claude or a subagent finishes

8. Claude Code Routines (Scheduled / API / GitHub Triggers)

A saved configuration (prompt + repositories + connectors + trigger) that runs autonomously on Anthropic-managed infrastructure.

Three trigger types:

• Scheduled — hourly, daily, weekdays, or weekly cadence
• API trigger — called programmatically (e.g., from a monitoring alert)
• GitHub trigger — fires on events like PR merge or pull_request.opened

9. CI/CD Pipeline Integration

Embed claude -p as a step in GitHub Actions, GitLab CI, or Jenkins. Enables AI at every stage of the development cycle.

10. Docker / Containerised Execution

Run Claude Code in Docker — clean, reproducible environment each execution.

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
ENTRYPOINT ["claude", "-p"]

Pass API key as environment variable.

Summary Table

Method	Interactive?	Use Case
claude (REPL)	Yes	Development, exploration
claude -p "..."	No	Scripts, one-shots
Piped stdin	No	Unix pipelines
Shell scripts	No	Multi-step automation
GitHub Actions	No	PR/issue events
Python/TS SDK	No	Backend embedding
Hooks	Hybrid	Lifecycle enforcement
Routines	No	Scheduled/unattended work
CI/CD pipeline	No	Quality gates
Docker	No	Isolated/reproducible runs

Gotchas

• Multi-turn sessions via --resume require --output-format json to capture the session ID
• Hooks guarantee execution; prompting does not — use hooks for anything that must always run
• Routines run on Anthropic infrastructure; your code and secrets go to Anthropic servers

Source

Conversation: “How many ways to trigger Claude Code” — 2026-05-14

Updates — 2026-05-16

Speckit — Spec-Driven Layer (sits above all execution methods)

Speckit provides a structured specification framework that feeds into Claude Code’s execution. It’s not an execution method itself — it’s the input layer that produces the tasks.md or CLAUDE.md that autonomous methods consume.

Commands:

/speckit.constitution  → define project rules & standards
/speckit.specify       → define what to build (requirements file)
/speckit.plan          → architecture decisions
/speckit.build         → execute everything

The bridge is CLAUDE.md — Claude Code reads this at every session start. Encode Speckit’s vocabulary there so Claude behaves consistently across sessions.

Ralph Loop — Recommended for Overnight Local Execution

while true; do
  claude --dangerously-skip-permissions \
    "Check tasks.md, pick the next uncompleted task, implement it, \
     run tests, commit, mark done. Output 'complete' only when ALL tasks done."
  sleep 2
done

• Each iteration is a completely new Claude session (stateless)
• tasks.md is the only persistent memory
• Stop hook checks for “complete” promise word — prevents premature exit
• Can run for days; truly autonomous

Recommended Stack

Local overnight (laptop stays on):

Speckit → generates tasks.md → Ralph loop → implements → tests → commits → next task

Cloud / laptop closed:

Push spec file to GitHub → GitHub Actions triggers → claude -p "read specs/current.md, implement all tasks"

Or use Claude Code Routines for fully cloud-hosted nightly runs.

Updates — 2026-05-19

Agentic Concurrency — 1 Session ≠ 1 API Request

A single Claude Code agentic session is NOT the same as one concurrent API request. When a user runs an agentic task (e.g. “refactor my codebase”), Claude Code spawns multiple parallel tool calls in a single turn:

User: "refactor my entire codebase"

Claude Code spawns:
├── Read file A ──┐
├── Read file B ──┤  3 concurrent API requests within 1 session
└── Read file C ──┘

Practical implication for capacity planning:

Session type	Concurrent API calls
Simple question / single answer	1
Agentic task with parallel tool calls	2–5+

If a gateway limit is set to 10 concurrent requests, and each active agentic session uses 2–5 requests, the real user capacity is 2–3 simultaneous active agentic users, not 10.

Rule of thumb: 1 active agentic session ≈ 2–5 concurrent requests when estimating gateway capacity.

Updates — 2026-05-17

/loop Command (Built-in Cron Scheduler)

Native Claude Code cron-style scheduler. Runs tasks at fixed intervals (minutes/hours/days) while a session is active. Supports up to 50 concurrent scheduled tasks per session.

Limitation: Session-dependent — /loop dies when you close Claude Code. Use a real cron job or Routines for anything that must survive restarts or machine sleep.

GSD (Get Shit Done) — Most Feature-Complete Autonomous Option

Spawns parallel researchers, planners, executors, and verifiers — each in a fresh 200K-token context window. Manages context rotation, quality gates, and planning state across sessions. Has a TypeScript SDK for headless/CI use.

Best for: large projects with parallel workstreams. More overhead than Ralph Loop for simple sequential tasks.

Autonomous Options Comparison

Method	Laptop needed?	Self-decides?	Spec-driven?	Best for
/loop command	Yes (session open)	Yes	Via CLAUDE.md	Simple monitoring tasks
Ralph bash loop	Yes (terminal open)	Yes	Via tasks.md	Overnight local coding
Subagents + Task tool	Yes	Yes	Via spec files	Complex multi-part features
GSD	Yes	Yes	Built-in	Large projects, parallel work
Claude Code Routines	No	Yes	Via prompt	Scheduled cloud automation
GitHub Actions	No	Yes	Via spec file trigger	CI/CD + spec-push triggers

Claude Code Channels (Discord/Telegram — Mar 2026)

Official native Discord and Telegram integration (research preview, v2.1.80+). Send messages from Discord → Claude processes using your local dev environment → replies in same channel. Requires Pro/Max subscription; session must be actively running.