Building headless automation with Claude Code

Key Concepts

• Cloud Code SDK: A way to programmatically access the power of the Cloud Code agent in headless mode.
• GitHub Action: Automates tasks within your software development workflow.
• claude-b: Command-line tool to interact with the Cloud Code SDK.
• -d-allow_tools: Flag to preconfigure Claude with permissions.
• -d-output_format: Flag to specify the output format (JSON or stream JSON).
• -d-system_prompt: Flag to configure the system prompt.
• Session ID: Used to resume session state and build user interactive features.
• -d-permission_prompt_tool: Flag to offload permission management to an MCP server.
• Cloud Code Base Action: A thin layer that talks to Cloud Code and returns the response.
• PR Action: Responsible for making comments, creating to-do lists, rendering the output, and adding PR links.

1. Introduction to Cloud Code SDK and GitHub Action

• Sedara, an engineer on the Cloud Code team, introduces the Cloud Code SDK and the newly announced Cloud Code GitHub Action.
• The agenda includes a quick start for the SDK, a live demo of the GitHub Action, advanced features of the SDK, and instructions for setting up the GitHub Action.
• The Cloud Code SDK allows programmatic access to the Cloud Code agent in headless mode, enabling new types of applications.
• The GitHub Action is built on top of the SDK and serves as an example of what can be achieved with the SDK.

2. Basic Examples of Using the Cloud Code SDK

• Calling Claude is as simple as using the claude-b command followed by the string you want to ask Claude.
  • Example: claude-b "write me a Fibonacci sequence generator" -d-allow_tools write
• Piping logs to Claude for summarization: cat app.log | claude-b "summarize log failures"
• Using Claude to understand the output of ifconfig.
• Outputting Claude's response in JSON format using -d-output_format JSON for parsing and building on top of it.

3. Live Demo of the Cloud Code GitHub Action

• The Cloud Code GitHub Action can be used to review code, create new features, and triage bugs.
• A demo is performed on an open-source quiz app.
• An issue requesting power-ups (50/50 elimination and skip questions) is addressed using the GitHub Action.
• The command @cloud please implement this feature and comment on it is used to trigger the action.
• Claude responds with a comment on the GitHub issue and a link to the job run.
• The job run logs show JSON output from the SDK.
• Claude creates a to-do list and implements the power-up feature.
• Another issue regarding a per-question timer is also addressed.
• Claude is instructed to change the background color of an existing pull request from blue to green using @cloud please change this to green.
• The demo shows Claude adding a commit to the pull request to change the color.

4. Deep Dive into the Features of the SDK

• By default, claude-b has no edit or destructive permissions.
• The -d-allow_tools option allows preconfiguring Claude with necessary permissions.
  • Example: -d-allow_tools "npm run build, npm test, write"
• Structured output is available in two modes: stream JSON and JSON.
  • Stream JSON streams messages as they are available.
  • JSON provides one giant blob of JSON at the end.
• The -d-system_prompt option allows configuring the system prompt.
  • Example: -d-system_prompt "talk like a pirate"
• User interaction features:
  • Resuming session state using session IDs returned in JSON mode.
  • -d-permission_prompt_tool allows offloading permission management to an MCP server, prompting users for tool acceptance or rejection in real-time.

5. Demo Results and Functionality of the GitHub Action

• Claude successfully implemented the power-up feature in the quiz app, adding a power-up section to the config page and 50/50 and skip buttons during gameplay.
• Claude also successfully changed the background color in the pull request from blue to green.
• The Cloud Code GitHub Action can read code, create PRs from GitHub issues, create commits for existing PRs, answer questions, and review code.
• The action runs on existing GitHub runners, eliminating the need for additional infrastructure.

6. How the GitHub Action is Built

• The GitHub Action is built on top of the Cloud Code SDK.
• It consists of three layers:
  • Cloud Code Base Action: Implements the communication with Cloud Code and returns the response.
  • PR Action: Handles comments, to-do lists, rendering, and PR links.
• Both the base action and the PR action are open-sourced.

7. Installing the Cloud Code GitHub Action

• The easiest way to install the GitHub Action is to open Cloud Code in a terminal in the desired repository and run slash install github action.
• This presents a flow for configuring the GitHub Action and merging a YAML file.
• Bedrock and Vertex users have slightly different, more manual instructions.

8. Resources and Feedback

• Links to the open-source repos for the base action and the Cloud Code action are provided.
• Feedback on the SDK, GitHub Action, and Cloud Code is encouraged through the public Cloud Code GitHub repo.

9. Conclusion

• The Cloud Code SDK and GitHub Action provide powerful tools for automating development tasks and leveraging AI in the development workflow. The demo showcased the ability to generate code, modify existing code, and answer questions, all within the GitHub environment. The open-source nature of the project encourages community contributions and further development.