Chạy Claude Code theo hướng lập trình

Agent SDK cung cấp cùng bộ tool, agent loop, và quản lý ngữ cảnh vốn vận hành Claude Code. Có thể dùng qua CLI cho script và CI/CD, hoặc qua package Python và TypeScript để kiểm soát lập trình đầy đủ.

Muốn chạy Claude Code ở chế độ non-interactive, truyền -p cùng prompt và bất kỳ CLI option nào:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Trang này nói về dùng Agent SDK qua CLI (claude -p). Với package Python/TypeScript có structured output, callback duyệt tool, và message object native, xem tài liệu đầy đủ về Agent SDK.

Dùng cơ bản

Thêm cờ -p (hoặc --print) vào bất kỳ lệnh claude nào để chạy non-interactive. Mọi CLI option đều dùng được với -p, gồm:

• --continue để tiếp tục hội thoại
• --allowedTools để tự động duyệt tool
• --output-format cho structured output

claude -p "What does the auth module do?"

Khởi động nhanh hơn với bare mode

Thêm --bare để giảm thời gian khởi động bằng cách bỏ qua tự động tìm hooks, skills, plugins, MCP server, auto memory, và CLAUDE.md. Nếu không có --bare, claude -p nạp cùng ngữ cảnh như một phiên interactive, gồm cả những gì cấu hình trong thư mục làm việc hay ~/.claude.

Bare mode hữu ích cho CI và script cần kết quả giống nhau trên mọi máy - một hook trong ~/.claude của đồng nghiệp hay MCP server trong .mcp.json của dự án sẽ không chạy vì bare mode không đọc chúng. Chỉ cờ bạn truyền tường minh mới có hiệu lực.

claude --bare -p "Summarize this file" --allowedTools "Read"

Ở bare mode, Claude vẫn có Bash và các tool đọc/sửa file. Truyền ngữ cảnh cần thiết qua cờ:

Muốn nạp	Dùng
Bổ sung system prompt	--append-system-prompt, --append-system-prompt-file
Settings	--settings <file-or-json>
MCP server	--mcp-config <file-or-json>
Custom agent	--agents <json>
Plugin	--plugin-dir <path>, --plugin-url <url>

Bare mode bỏ qua OAuth và keychain. Với xác thực Anthropic, đặt ANTHROPIC_API_KEY hoặc cấu hình apiKeyHelper trong JSON truyền cho --settings. Amazon Bedrock, Google Cloud’s Agent Platform, và Microsoft Foundry dùng credential provider thường lệ của họ.

Ghi chú

--bare là chế độ khuyến nghị cho các lời gọi script và SDK, và sẽ trở thành mặc định cho -p trong một bản phát hành tương lai.

Task chạy nền lúc thoát

Nếu Claude khởi động một Bash task chạy nền trong một lần chạy claude -p (ví dụ dev server hay watch build), shell đó bị chấm dứt khoảng 5 giây sau khi Claude trả kết quả cuối và stdin đã đóng. Khoảng nghỉ này cho task vừa hoàn thành ngay sau kết quả vẫn kịp gửi output.

Subagent và workflow chạy nền được miễn khỏi khoảng nghỉ 5 giây vì kết quả của chúng là một phần của output cuối, nên claude -p chờ chúng hoàn thành - mặc định giới hạn 10 phút, chỉnh bằng CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS (đặt 0 để chờ không giới hạn).

Nếu bạn dừng claude -p bằng SIGTERM (ví dụ kill, process supervisor, hay SDK host đóng phiên), Claude Code huỷ lượt đang chạy, chấm dứt cây process của Bash command đang chạy, chạy hook SessionEnd, và thoát với mã 143.

Ví dụ

Các ví dụ dưới đây minh hoạ pattern CLI thường dùng. Với CI và các lời gọi có script khác, thêm --bare để không vô tình nạp cấu hình cục bộ.

Pipe dữ liệu qua Claude

Chế độ non-interactive đọc stdin, nên bạn có thể pipe dữ liệu vào và redirect phản hồi ra như bất kỳ lệnh dòng lệnh nào khác.

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Với --output-format json, payload phản hồi có total_cost_usd và breakdown chi phí theo từng model, nên script gọi có thể theo dõi chi phí mỗi lần gọi.

Chú ý

Từ Claude Code v2.1.128, stdin qua pipe giới hạn ở 10MB. Vượt giới hạn, Claude Code thoát với lỗi rõ ràng và mã trạng thái khác 0. Với input lớn hơn, ghi nội dung ra file và tham chiếu đường dẫn trong prompt thay vì pipe. Kiểm tra lại con số này với phiên bản bạn đang dùng.

Thêm Claude vào build script

Bọc một lời gọi non-interactive trong script để dùng Claude như một linter hay reviewer riêng cho dự án. Script package.json sau pipe diff so với main vào Claude và yêu cầu báo lỗi chính tả:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Lấy structured output

Dùng --output-format để kiểm soát cách phản hồi trả về:

• text (mặc định): output văn bản thuần
• json: JSON có cấu trúc gồm result, session ID, metadata
• stream-json: JSON newline-delimited để stream theo thời gian thực

claude -p "Summarize this project" --output-format json

Muốn output theo một schema cụ thể, dùng --output-format json cùng --json-schema và định nghĩa JSON Schema. Phản hồi gồm metadata (session ID, usage…) với structured output nằm trong trường structured_output:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Nếu giá trị không phải JSON Schema hợp lệ, claude thoát với lỗi kèm chẩn đoán. Claude Code chấp nhận schema dùng từ khoá format (như "format": "email") nhưng xem đó là annotation, không thực thi kiểm tra.

Mẹo

Dùng công cụ như jq để parse phản hồi và trích trường cụ thể:

claude -p "Summarize this project" --output-format json | jq -r '.result'

Stream phản hồi

Dùng --output-format stream-json cùng --verbose và --include-partial-messages để nhận token khi chúng được sinh ra. Mỗi dòng là một JSON object đại diện một sự kiện:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

Dòng cuối của stream là message result chứa văn bản phản hồi cuối, chi phí, và metadata phiên.

Theo dõi message của subagent

Message từ subagent xuất hiện trong stream là các message assistant và user có trường parent_tool_use_id là ID của tool call đã spawn subagent đó. Message của hội thoại chính mang null ở trường này.

Mặc định, Claude Code chỉ phát ra block tool_use và tool_result của subagent. Truyền --forward-subagent-text hoặc đặt CLAUDE_CODE_FORWARD_SUBAGENT_TEXT để phát cả block text và thinking, giúp bạn dựng lại transcript của mỗi subagent.

Xử lý retry của API

Khi một request API thất bại với lỗi có thể retry, Claude Code phát ra sự kiện system/api_retry trước khi thử lại - dùng để hiển thị tiến độ retry hoặc tự viết logic backoff riêng.

Đọc metadata phiên

Sự kiện system/init báo cáo metadata phiên gồm model, tool, MCP server, và plugin đã nạp - thường là sự kiện đầu tiên trong stream.

Phát hiện plugin hoặc MCP server không nạp được trong CI

Dùng các trường plugin trong sự kiện system/init (plugins, plugin_errors) và MCP server (mcp_servers, mcp_server_errors) để phát hiện plugin hay server nào không nạp thành công, phục vụ việc gate CI.

Tự động duyệt tool

Dùng --allowedTools để Claude dùng một số tool mà không hỏi. Ví dụ chạy test suite và tự sửa lỗi:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Muốn đặt baseline cho cả phiên thay vì liệt kê từng tool, truyền permission mode. dontAsk từ chối mọi thứ không nằm trong permissions.allow hay tập lệnh chỉ-đọc, hữu ích cho các lần chạy CI khoá chặt. acceptEdits cho phép Claude ghi file mà không hỏi, và tự duyệt các lệnh filesystem phổ biến (mkdir, touch, mv, cp).

Tạo commit

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Cờ --allowedTools dùng cú pháp permission rule. Dấu * cuối bật khớp tiền tố, nên Bash(git diff *) cho phép mọi lệnh bắt đầu bằng git diff. Khoảng trắng trước * quan trọng - thiếu nó, Bash(git diff*) sẽ khớp cả git diff-index.

Ghi chú

Skill và custom command do người dùng gọi vẫn hoạt động ở chế độ -p: đưa /skill-name vào chuỗi prompt và Claude Code sẽ mở rộng nó trước khi chạy. Lệnh có sẵn chỉ chạy ở giao diện terminal, như /login, thì không dùng được ở chế độ -p.

Tuỳ biến system prompt

Dùng --append-system-prompt để thêm chỉ dẫn trong khi giữ hành vi mặc định của Claude Code:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Tiếp tục hội thoại

Dùng --continue để tiếp tục hội thoại gần nhất, hoặc --resume kèm session ID để tiếp tục một hội thoại cụ thể:

# Lần gọi đầu
claude -p "Review this codebase for performance issues"

# Tiếp tục hội thoại gần nhất
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Nếu chạy nhiều hội thoại song song, lưu lại session ID để resume đúng cái:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Chạy cả hai lệnh từ cùng thư mục - việc tra cứu session ID chỉ giới hạn trong thư mục dự án hiện tại và các git worktree của nó.

Bước tiếp theo

• Agent SDK quickstart: xây agent đầu tiên với Python hoặc TypeScript
• CLI reference: toàn bộ cờ và tuỳ chọn CLI
• GitHub Actions: dùng Agent SDK trong GitHub workflow
• GitLab CI/CD: dùng Agent SDK trong pipeline GitLab

Nguồn

Dịch và biên soạn từ Run Claude Code programmatically.