Automating Multi-Step Workflows with Headless Claude Code and Flag-Controlled Tools

Hello! Welcome back to the course.

In our last lesson, we mastered the fundamentals of running Claude Code in headless mode. You learned how to execute non-interactive prompts, pipe data via stdin, and—most critically—parse structured JSON output to make Claude's responses usable in scripts.

Today, we will assemble those building blocks into a powerful, automated workflow. You will learn how to build a shell script that orchestrates a sequence of related tasks with Claude Code. We'll introduce two crucial concepts for this: maintaining context across multiple headless calls and controlling tool access with precision using flags. By the end of this lesson, you'll be able to create scripts that automate complex, multi-step development tasks, moving you closer to building professional-grade automations.

Chaining Commands: The Essence of Shell Scripting

First, let's quickly reinforce the core idea of using Claude Code as a command-line tool that can be part of a larger chain.

Maintaining Context in a Multi-Step Workflow

A key challenge in creating a multi-step workflow is ensuring context is not lost between steps. If you make two separate claude -p calls, they are independent by default. The second call has no memory of the first. To build a coherent workflow, we need to link them.

This is achieved using session management flags:

• --session-id <ID>: Starts a new headless session with a specific, unique identifier.
• --resume <ID>: Resumes a previously created session, loading its entire conversation history.

The following resource demonstrates this concept beautifully by building a script that performs an initial check and then "escalates" to a second step if needed, all while preserving context.

As you saw in the check.sh script, a session ID acts as a handle to a persistent conversation, allowing your script to build context incrementally across multiple, independent claude invocations.

Controlling Tool Access for Safety and Intent

When you automate tasks, especially those that modify your filesystem, you need precise control over what the AI is allowed to do. Granting unrestricted access is risky. Claude Code allows you to grant specific permissions for each call using the --allow-tools flag.

This next video provides a clear explanation of how to use this flag.

The syntax is straightforward and powerful:

• --allow-tools write: Allows Claude to create or overwrite files.
• --allow-tools edit: Allows Claude to apply changes to existing files.
• --allow-tools read: Allows Claude to read files. (Often implicitly available, but good to be explicit).
• --allow-tools bash:"<command>": Allows Claude to run a specific shell command, like bash:"pytest" or bash:"npm run build".
• --allow-tools <mcp-tool-name>: Allows access to a configured MCP tool.

You can provide a comma-separated list to allow multiple tools: --allow-tools write,bash:"pytest".

This image shows a practical example of this flag in a command line.

Practical Application: A FastAPI Scaffolding Script

Now, let's combine these concepts to build a practical, multi-step script that automates a common task from your world of FastAPI development: scaffolding a new API resource.

Our script, create_resource.sh, will:

1. Accept a resource name (e.g., "product").
2. Step 1: Generate a Pydantic model for the resource and save it to models/{resource_name}.py.
3. Step 2: Generate a FastAPI router with basic CRUD endpoints for that model, saving it to routers/{resource_name}.py.
4. Step 3: Automatically import and include the new router in your main main.py application file.

This workflow requires session management to link the steps and precise tool control (write for new files, edit for modifying main.py).

Before we dive into our script, let's look at a well-structured example of a similar automation to see what a production-ready script might look like.

The create_resource.sh Script

Inspired by the best practices we've seen, here is the complete script for our FastAPI resource scaffolder. Create a file named create_resource.sh, make it executable (chmod +x create_resource.sh), and then you can run it with ./create_resource.sh <resource_name>.

#!/bin/bash




# Exit immediately if a command exits with a non-zero status.
set -e




# Check if a resource name was provided.
if [ -z "$1" ]; then
  echo "Usage: ./create_resource.sh <resource_name>"
  exit 1
fi

RESOURCE_NAME=$1
MODEL_NAME=$(echo "$RESOURCE_NAME" | awk '{print toupper(substr($0,1,1))substr($0,2)}') # Capitalize first letter
SESSION_ID=$(uuidgen)

echo "🚀 Starting to scaffold resource: $RESOURCE_NAME"




# --- Step 1: Generate Pydantic Model ---
echo "   1. Generating Pydantic model..."
MODEL_PROMPT="Create a Pydantic model named '${MODEL_NAME}' for a '${RESOURCE_NAME}' resource. It should have an 'id' (UUID), 'name' (string), and 'created_at' (datetime). Save it to 'models/${RESOURCE_NAME}.py'."

claude -p "$MODEL_PROMPT" --session-id "$SESSION_ID" --allow-tools write --output-format json > /dev/null

echo "      ✅ Model file 'models/${RESOURCE_NAME}.py' created."





# --- Step 2: Generate FastAPI Router ---
echo "   2. Generating FastAPI router..."
ROUTER_PROMPT="Now, create a FastAPI router for the '${MODEL_NAME}' model. Include basic GET (list and by ID), POST, and DELETE endpoints. Use in-memory storage for this example. Save the complete router code to 'routers/${RESOURCE_NAME}.py'."

claude -p "$ROUTER_PROMPT" --resume "$SESSION_ID" --allow-tools write,read --output-format json > /dev/null

echo "      ✅ Router file 'routers/${RESOURCE_NAME}.py' created."





# --- Step 3: Update main.py to include the new router ---
echo "   3. Integrating router into main.py..."
INTEGRATION_PROMPT="Finally, edit the 'main.py' file. Import the new router from 'routers.${RESOURCE_NAME}' and include it in the FastAPI app using 'app.include_router'."

claude -p "$INTEGRATION_PROMPT" --resume "$SESSION_ID" --allow-tools edit --output-format json > /dev/null

echo "      ✅ 'main.py' updated to include the new router."

echo "🎉 Scaffolding complete for resource: $RESOURCE_NAME"

Breakdown of the Script:

• set -e: A standard shell practice to ensure the script fails immediately if any command fails.
• SESSION_ID=$(uuidgen): We generate a unique ID to link all subsequent claude calls.
• Step 1 (Model): We use --session-id to start the conversation and --allow-tools write because we are creating a new file. The JSON output is redirected to /dev/null as we only care about the side effect (file creation).
• Step 2 (Router): We use --resume to continue the conversation. Claude now has the context of the model it just created. We need --allow-tools read,write so it can conceptually "read" the model definition for context while writing the new router file.
• Step 3 (Integration): We again --resume the session. This time, we use --allow-tools edit to grant permission to modify an existing file, main.py.

This script is a tangible example of how you can automate away boilerplate code generation, enforcing consistency and saving time—a true "power-user" workflow.

Conclusion

In this lesson, you've bridged the gap from running single headless commands to orchestrating complex, automated workflows. You now have the tools to build scripts that mirror and accelerate your own development processes.

Key Takeaways:

• Multi-Step Workflows Need Context: Use --session-id and --resume to create a persistent conversation that links multiple claude calls together.
• Control is Paramount: The --allow-tools flag is essential for creating safe and predictable automations. Grant permissions (like write, edit, or bash:<cmd>) on a per-call basis.
• Structure Your Scripts: Model your scripts after robust examples by handling inputs, checking for errors, and providing clear feedback to the user.

Next Up:

You've successfully automated a workflow on your local machine. The next logical step is to take this automation into the cloud. In our next lesson, we will adapt what you've learned today to a CI/CD environment by setting up Claude Code in a GitHub Actions workflow to automate tasks directly within your development pipeline.