Create Your First Custom AI Agent in Minutes

Turn Your AI Agent into a Reusable Command-Line Tool

Create a Single-Purpose AI 'Planner' Agent

Build an Autonomous Agent with Pre-Approved Tools

Automate Repetitive Tasks by Piping Your Shell History to an AI Agent

Unleash Claude’s raw power directly in your terminal. Search million-line codebases instantly. Turn hours-long workflows into a single command. Your tools. Your workflow. Your codebase, evolving at thought speed.

claude-code

A collection of practical recipes for automating your development workflow with custom-built Claude Code agents. This course provides a hands-on guide where you'll learn to craft precise system prompts to create reliable, single-purpose agents, package them as simple command-line tools using bun build, and grant them the autonomy to complete multi-step tasks like web research and file creation.

Stop repeating yourself and start automating. This lesson is your first step into building specialized AI agents. You'll learn the foundational skill of creating a simple, reusable "French-speaking" agent by spawning the Claude CLI with a custom system prompt. We'll cover the essential mechanics of using `Bun.spawn` to create an interactive session, how to externalize prompts in markdown files for easy editing, and the TypeScript setup needed to tie it all together. This is the core workflow we'll build on throughout the course.

## How it Works

1.  **Spawn a Process:** Use `Bun.spawn` to run the `claude` CLI, inheriting standard I/O to create an interactive session directly in your terminal.
2.  **Externalize Prompts:** Store system prompts in simple markdown (`.md`) files. This separates the agent's "personality" from the code.
3.  **Import Prompts as Text:** Leverage Bun's ability to import non-JavaScript files. We'll import the `.md` file with a `type: "text"` assertion.
4.  **Handle TypeScript Types:** Create a custom type declaration file (`types.d.ts`) to inform TypeScript how to handle `.md` module imports, resolving any "Cannot find module" errors.
5.  **Dynamically Build Flags:** Construct command-line arguments programmatically from a configuration object. This makes it easy to add or change the flags passed to the `claude` process.
6.  **Launch the Agent:** Run the script to launch a custom Claude agent that consistently follows the instructions from your external prompt file.

This workflow provides a powerful and scalable pattern for building a suite of specialized AI agents, making your development process with AI more organized and efficient.

### Spoken Prompts

Dictating the content for the markdown prompt file:
~~~markdown
Please always speak in French.
~~~

Querying the French-speaking agent:
~~~markdown
How are you doing today?
~~~

### Terminal Commands

Initialize a new Bun project:
~~~bash
bun init
~~~

Run the agent script:
~~~bash
bun run agents/french.ts
~~~

### Code Snippets

Creating a custom type declaration in `types.d.ts` to allow importing `.md` files as modules in TypeScript.
~~~typescript
declare module "*.md" {
  const content: string;
  export default content;
}
~~~

Importing the content of a markdown file as a text string using Bun's import attributes.
~~~typescript
import prompt from "../prompts/french.md" with {
  type: "text"
};
~~~

Dynamically creating an array of command-line arguments from a configuration object to be passed to `Bun.spawn`.
~~~typescript
const flags = {
  "append-system-prompt": prompt
}

const flagsArray = Object.entries(flags).flatMap(([key, value]) => {
  return [`--${key}`, value]
})
~~~

Spawning the `claude` CLI process with the dynamically generated arguments using the spread operator.
~~~typescript
Bun.spawn(["claude", ...flagsArray], {
  stdio: ["inherit", "inherit", "inherit"],
});
~~~

cursor

A custom agent is only useful if it's easy to run. In this lesson, we'll level up our "French" agent by compiling it into a standalone executable with `bun build`. You'll learn how to transform a clunky `bun run agents/french.ts` command into a simple, memorable `french` command that you can run from anywhere in your terminal. We'll walk through adding the agent to your system's PATH, making your custom AI tools feel like a natural part of your command-line environment.

## The Workflow

1.  **Compile the Agent:** A single Bun command transforms your TypeScript file into a native executable.
2.  **Update System PATH:** The directory containing your new executable is added to your shell's `PATH` environment variable.
3.  **Reload and Run:** After reloading your shell configuration, your custom agent is available as a system-wide command.

## Key Benefits

*   **Simplicity:** Convert complex `bun run ...` commands into a single, memorable command (e.g., `french`).
*   **Portability:** The compiled executable is a single file, making it easy to manage and distribute.
*   **System-Wide Access:** Run your custom tools from any directory in your terminal without needing to specify the full path.
*   **Professional Tooling:** Package your scripts in a way that makes them feel like native, professional command-line applications.

## Commands and Code

First, compile the TypeScript agent into an executable file located in a `bin` directory.

~~~bash
bun build agents/french.ts --compile --outfile bin/french
~~~

You can now run the agent directly by referencing the new executable file.

~~~bash
bin/french
~~~

To make this command globally accessible, open your shell's configuration file. In this case, it's `.zshrc`.

~~~bash
cursor ~/.zshrc
~~~

Add a line to export the path to your `bin` directory, appending it to the existing `PATH`.

~~~bash
export PATH="$PATH:/Users/johnlindquist/dev/agents/bin"
~~~

Reload your shell's configuration to apply the changes immediately.

~~~bash
source ~/.zshrc
~~~

Now, you can run your agent from anywhere on your system by simply typing its name.

~~~bash
french
~~~

You can interact with your newly created global agent.

~~~markdown
> testing
~~~

~~~markdown
> hello
~~~

General-purpose AI is powerful, but often unpredictable. This lesson tackles how to build a specialized AI "planner" agent that reliably sticks to its one and only job: creating plans. You'll learn how to write a strong, directive system prompt that constrains the AI's behavior. We'll demonstrate how an initially weak prompt can fail, and then show you how to strengthen it to ensure your agent rejects irrelevant requests and focuses exclusively on its assigned task, every time.

### Workflow demonstrated in this lesson:

*   Create a dedicated system prompt to strictly define the agent's role and goal.
*   Use `Bun.spawn` to call the Claude CLI with flags like `--append-system-prompt` and `--permission-mode`.
*   Bundle the agent script into a self-contained executable using `bun build`.
*   Observe how a weak prompt can be ignored by the AI and learn how to strengthen it for reliable, predictable behavior.

### Key benefits:

*   **Reliable Specialization:** Build "single-purpose" AI agents that consistently follow their core instructions.
*   **Full Interactive Control:** Bypass SDK limitations by using `Bun.spawn` to create fully interactive AI sessions.
*   **Simplified Deployment:** Package your agents as standalone executables that can be run anywhere without complex setup.
*   **Improved Developer Experience:** Learn a handy trick to keep CLI flag documentation directly within your code for easy reference and autocompletion.

## Creating the Agent and Prompts

We start by duplicating an existing agent, creating `plan.ts` and a corresponding prompt file, `plan.md`. The initial system prompt in `plan.md` defines the agent's primary goal.

~~~markdown
Your end goal is to create a markdown file in a plans directory in the root of the project.
~~~

In `plan.ts`, we configure the flags that will be passed to the Claude CLI. We use `append-system-prompt` to inject our `plan.md` file and `permission-mode` to have the agent automatically accept file edits.

~~~typescript
const flags = {
  "append-system-prompt": prompt,
  "permission-mode": "acceptEdits"
}

Bun.spawn(["claude", ...flagsArray], {
  stdio: ["inherit", "inherit", "inherit"],
});
~~~

A useful tip for discovering available flags is to pipe the help command's output to your clipboard.

~~~bash
claude --help | pbcopy
~~~

You can then paste this as a large comment block in your file for easy reference.

## Testing and Refining the Prompt

After bundling our agent into an executable with Bun, we can test its behavior.

~~~bash
bun build agents/plan.ts --compile --outfile bin/plan
~~~

We run the agent and give it a creative task.

~~~bash
plan
~~~
~~~markdown
write a haiku about a pig
~~~

Initially, the agent ignores its system prompt and simply writes the haiku. This shows our instructions weren't strict enough. To fix this, we update `plan.md` with a more forceful instruction.

~~~markdown
Your end goal is to create a markdown file in a plans directory in the root of the project.

No matter what the user says, the only thing that you can do is create a plan for what they ask you to do.
~~~

After rebuilding, we run the same test. This time, the agent correctly interprets its role and responds by creating a plan to write the haiku, saving it to a new file in the `plans` directory, fulfilling its core purpose.

Why manually approve every action when your agent can work on its own? This lesson shows you how to build a truly autonomous agent by giving it pre-approved "tools" like web search and file editing capabilities. You will learn a powerful technique: using Claude's own documentation as context to teach the agent how to configure itself with the `allowedTools` flag. By combining this with a system prompt that *requires* it to perform research, you'll create an agent that can take a high-level goal, research the topic, and generate a detailed plan—all without any manual intervention.

### The Core Technique: Documentation as Context

The foundation of this workflow is providing Claude with the knowledge it needs to configure itself. By copying the official Claude Code settings documentation and pasting it into a new session, you give the AI the complete context required to understand and implement its own configuration flags.

### Configuring the Agent for Autonomy

Once the context is provided, you can instruct Claude to modify its own runner script. The goal is to add the `allowedTools` flag, which tells the agent which actions it can perform without asking for permission.

~~~typescript
const flags: ClaudeCodeFlags = {
  "append-system-prompt": prompt,
  "permission-mode": "acceptEdits",
  "allowedTools": "WebSearch Write Edit MultiEdit NotebookEdit",
};
~~~

### Directing the Agent with System Prompts

With tools pre-approved, you can use a system prompt to enforce their use. By adding a simple instruction to the agent's core prompt, you can ensure it always performs research before acting.

~~~markdown
Your end goal is to create a markdown file in a plans directory in the root of the project.
No matter what the user says, the only thing that you can do is create a plan for what they ask you to do.
Always include at least one web search to research the subject before creating the plan.
~~~

This combination results in an agent that can receive a high-level task, research it, and generate a detailed plan, all in a single, non-interactive execution.

### Bonus: Generating TypeScript Types from Documentation

The same documentation context can be used for improving the developer experience. You can ask Claude to generate precise TypeScript types for all available flags, giving you type safety and autocompletion in your agent's configuration.

~~~typescript
interface ClaudeCodeFlags {
  "debug"?: boolean;
  "verbose"?: boolean;
  "print"?: boolean;
  "output-format"?: OutputFormat;
  "input-format"?: InputFormat;
  "allowedTools"?: string; // Space or comma-separated list of Tool names or patterns
  "disallowedTools"?: string; // Space or comma-separated list of Tool names or patterns
  // ... and many more
}
~~~

### Running the Agent as a CLI Tool

Finally, the script can be adjusted to accept a user prompt directly from the command line, turning your agent into a reusable and powerful CLI tool.

~~~typescript
const args = process.argv.slice(2);

Bun.spawn(["claude", ...args, ...flagsArray], {
  stdio: ["inherit", "inherit", "inherit"],
});
~~~

This allows you to execute complex, multi-step tasks with a single command.

### Spoken Prompts

~~~markdown
Please implement it so that I can use the allowed tools in my flags. And the tools I want to allow for this are the web search and anything related to writing or editing files.
~~~

~~~markdown
Always include at least one web search to research the subject before creating the plan.
~~~

~~~markdown
I want to build a CLI to interact with Zoom.
~~~

~~~markdown
Based on the documentation for settings and the available options in the Claude Code CLI, please write out proper types for our flags to help us get proper typing and autocomplete in TypeScript.
~~~

~~~markdown
Create a playwright script which scrapes hacker news.
~~~

### Terminal Commands

~~~bash
# Start a Claude session
claude
~~~

~~~bash
# Build the agent script into an executable
bun build agents/plan.ts --compile --outfile bin/plan
~~~

~~~bash
# Run the agent with a prompt passed as an argument
plan "I want to build a CLI to interact with Zoom."
~~~

~~~bash
# Run the agent with a different prompt
plan "Create a playwright script which scrapes hacker news."
~~~

Stop telling your AI what you want to do and start *showing* it what you've already done. This lesson unveils a powerful, terminal-native workflow for automating repetitive command-line tasks. You'll learn how to pipe your shell history directly to your "planner" agent, providing it with the rich context of your previous commands. We'll walk through creating a `watch` script by combining your build history with a simple natural language request, demonstrating the "plan-then-execute" pattern where the AI first generates a plan for your review and then implements it, turning a tedious manual process into an elegant, automated solution.

### The Plan-Then-Execute Workflow

This lesson highlights a robust two-step pattern for working with AI:

1.  **Generate a Plan:** First, provide the AI with context (your command history and your goal) and ask it to create a detailed, step-by-step plan in a markdown file. This allows you to review the proposed approach before any code is written.
2.  **Execute the Plan:** Once you're happy with the plan, you simply feed the generated markdown file back into the AI. The agent will then follow its own instructions to create directories, write code, and update configuration files to implement the solution.

By leveraging standard shell tools like piping (`|`) and redirection (`<`), you can orchestrate this entire process without ever leaving your terminal, turning a repetitive annoyance into a powerful, automated workflow.

### User Prompts

The user provides a combination of command history and a natural language instruction to the AI agent to generate a plan.

~~~markdown
In my package JSON, please create a watch script, which will trigger a build anytime any of our agent or prompt files change.
~~~

### Terminal Commands

The core of this workflow relies on chaining commands and piping their output to the AI agent.

First, the user constructs a rich context by combining the output of their shell history with a natural language prompt, and pipes it all into the `plan` command.

~~~bash
(atuin history list | grep "bun build"; echo "In my package JSON, please create a watch script, which will trigger a build anytime any of our agent or prompt files change.") | plan
~~~

After an update message appears, the user updates the AI tool.

~~~bash
npm i -g @anthropic-ai/claude-code@latest
~~~

To execute the generated plan, the user redirects the plan file as standard input to the `claude` command.

~~~bash
claude < plans/watch-script-development-plan.md
~~~

Finally, the newly created watch script is run.

~~~bash
bun watch
~~~

### Generated Development Plan Snippet

The AI agent first produces a detailed markdown plan, which outlines the current setup and the proposed implementation.

~~~markdown
# Watch Script Development Plan

## Overview
Add a watch script to package.json that automatically rebuilds agent binaries whenever agent or prompt files change.

## Current Setup
- **Agent files**: Located in `agents/` directory (`.ts` files)
- **Prompt files**: Located in `prompts/` directory (`.md` files)
- **Build output**: Compiled binaries in `bin/` directory
- **Build command**: `bun build agents/{agent}.ts --compile --outfile bin/{agent}`

## Implementation Plan

### Option 1: Simple Watch Script with Bun (Recommended)
Create a watch script that uses Bun's built-in watch flag to monitor and rebuild on changes.

**Steps:**
1. Create a `scripts/watch.ts` file that:
    - Uses `Bun.Glob` to find all agent files
    - Sets up file watchers using `fs.watch`
    - Triggers rebuild when files change
    - Handles multiple concurrent rebuilds efficiently
2. Add scripts to package.json:
    ```json
    "scripts": {
      "build": "bun scripts/build.ts",
      "watch": "bun scripts/watch.ts",
      "dev": "bun --hot scripts/watch.ts"
    }
    ```
~~~

Claude Code Automation Cookbook: Recipes for AI Agents

[00:00] We'll initialize a new bun project, just a blank one, and then we'll create a file in an agent's directory and we'll call this French.ts. Now from here we're going to bun spawn and to spawn clod with the standard I O set to inherit. That's just shorthand for a standard in, standard out, standard error. So if we run this, just fire up bun run agents and run French, we'll have a standard cloud code interactive session, which is even integrated with our IDE. You can see it's referencing the French file.

[00:33] So what we can do next is create a prompts directory and create a file called French.md and say please always speak in French and then hop back over here and we can import this prompt from that path with a type of text. I'm going to stop cursor from jumping ahead. And you can see that it can't find this module because the file type of MD. So we'll create a file called types.d.ts and declare that all markdown files just export default content of string which fixes that error. So now we've completely inlined our prompt and I'm going to set up an object called flags.

[01:09] And flags is going to, again jumping ahead, map the flag key to the prompt. And because of the required syntax here, this needs to be an array of strings. We're going to make our flags array where it loops through all the entries. Let me word wrap this. It loops through all the entries of flags and flat maps them so that a dash dash append system prompt is assigned to the value here.

[01:34] I'll just console log this out so it's a bit more obvious what's happening, and exit before it runs. If I run this you can see we get append system prompt and please always speak in French in an array. And if we let this run now where we destructure our array and hop into our terminal, then we'll run our French file again. We'll say, how are you doing today? And you'll see it always responds in French.



https://app.egghead.io/api/v1/lessons/create-your-first-custom-ai-agent-in-minutes~vmw0i/transcript

[00:00] So now we can take our little agent here and run bon build and we'll point to our agent file. So we'll say agents French. We want to compile this to an out file of bin slash French. So now we have a file in here in bin slash French. If we simply run bin French, type whatever, we now have an executable which will always speak to us in French.

[00:23] So if we take this path, I'll just right-click on it and copy path. I'm going to use cursor to open my zshrc. Then we can just add another line for export path. This one can be path and then our bin directory. So now if I source my zshrc, which will force it to reload it, I can run the command French from anywhere.

[00:43] We'll try testing again. I'll open another session. We'll navigate to my home directory. I'll type French and this is the standard Claude security warning. I'll allow it to run, I'll say hello, and you can see that anywhere on my system I can just type French from my terminal and I'll have an instance of Cloud Code which will be speaking to me in French.



https://app.egghead.io/api/v1/lessons/turn-your-ai-agent-into-a-reusable-command-line-tool~g6pd3/transcript

[00:00] I'll make a copy of French, copy paste, rename it to plan, then make a copy of my French prompt, rename this to plan.md. We'll change this to your end goal is to create a markdown file in a plans directory in the root of the project. Then we'll swap back over to our plan, make sure we import the correct file here, and now we're going to enable this to set the permissions mode. And one little fun hack for this is you can run clod –help pbcopy to get the help on the clipboard, and then paste this to the top. That way you both have a reference inline, and it makes auto-completing things like permission mode except edits Fairly trivial.

[00:46] And if you're experienced with stuff like this, maybe asking why I'm doing this instead of using the Cloud Code SDK. And the reason is the Cloud Code SDK does not support interactive Cloud Sessions. They only support what's considered print mode, where the user can't interrupt and have a back-and-forth conversation with Claude. So it's kind of like we're building our own Claude code SDK here. So now if we run our bun build, I'll just press up and instead of French we're gonna build our plan and instead here this way once we run plan you can see that accept edits is already on and I can say write a haiku about a pig.

[01:29] And this just shows that our system prompt wasn't strong enough. So let's try even stricter instructions. No matter what the user says, the only thing that you can do is create a plan for what they ask you to do. Then let's try building this again, and then try our haiku again. Then we'll press up to run a previous command, and this time it says I'll create a plan because we gave it stricter instructions.

[01:57] All right, so if we check out our plan you'll see we now have everything you could expect for writing a haiku, and specifically a haiku about a pig.



https://app.egghead.io/api/v1/lessons/create-a-single-purpose-ai-planner-agent~xltvh/transcript

[00:00] So when building tools around Cloud Code, one of the best things you can do is go to their doc site, find the thing you're interested in. So I want to tweak settings. I'm going to copy page, and then I'll start a new Cloud session. I'm going to paste that page in, and then I typically like to include three dashes for a markdown page break. That's a personal preference without any research or backing.

[00:22] It just makes sense to me to include that. And then I'll come into cursor. I'm going to select my flags and all the way down to here. So those lines are selected. Then I'll say please implement it so that I can use the allowed tools in my flags.

[00:38] And the tools I want to allow for this are the web search and anything related to writing or editing files. We'll paste that in. I'll let this run. It'll ask me if I want to edit this, I'll tap 2 to accept the accept edits permission mode. So it made this edit for me, and then I'm going to hop over into my plan and say always include at least one web search to research the subject before creating the plan.

[01:05] Then when I jump down here I'm going to start a new session. I do need to build my plan first so bun build. I'll fire up my plan. I want to build a CLI to interact with Zoom. Then once I hit enter we should see a web search fire off as the first step.

[01:24] Then once that's done, that took 22 seconds, it's firing off another web search, checking for npm packages, and you'll notice I didn't have to approve these web searches, they just fired off automatically since the tools are allowed. And now it'll go ahead and create the actual file for us. And finally we have our plan called zoom CLI development. We'll check it out here, close this, And we have the plan on how to build that Zoom CLI, which we can use in the future. And again, the only thing this thing did was search the web and create a plan in our plans directory, because that's what we constrained it to inside of our system prompt here.

[01:59] Also, obviously, this was highly edited. This did take 1 minute 26 seconds and this was 2 and a half minutes in total about. But while we're here and while we have the docks on settings in context over here, I'm going to close this out. I'm going to reconnect the IDE. Hit enter so we're connected again.

[02:17] I'm going to select in our plan, I'll select our flags, and then tell it based on the documentation for settings and the available options in the Cloud Code CLI, please write out proper types for our flags to help us get proper typing and auto-complete in TypeScript. Then I'll sit back and let this run, maybe go grab a sandwich. That actually went much faster than expected. So we have our permission modes, our output formats, input tools, and our flags, and it looks like everything's pretty good to go here. So while we're here, if we want to pass in any values like a default user prompt, let's just grab the args from the argv and we're going to put those in front of our flags array.

[03:00] So this would look like clod do something flag whatever. So now if we build this again, I'll run our build and then we'll fire off a plan to create a playwright script which scrapes hacker news. Then let this run, You'll see that this string will be passed in as the user submitting something, and then the conversation will start. Now it's going to run the, let me get more area here, run the web search, and then eventually create that plan. So it's doing our web searches, it's updating the to-dos, creating the plan, and our plan is ready.

[03:38] We'll check it out, hide our terminal, and we have an entire research plan based on the web searches and everything we wanted. And that was executed without me ever having to put any input or accept any tools or accept edits into this prompt here. It did the entire thing just because I wrote this simple text of plan and then the plan I wanted it to create.



https://app.egghead.io/api/v1/lessons/build-an-autonomous-agent-with-pre-approved-tools~r4wx0/transcript

[00:00] Now because I'm getting sick of typing bun build over and over again, let's go ahead and create a plan for that. I'm actually gonna look through my command history. You can use history on most shells. I use a tool called Atuin, which is a history list. And I'm going to type history list and grep for bun build.

[00:17] And I'm going to group that command. So I'll select again. I'm going to group this command with a command of echo in my package.json. Please create a watch script which will trigger a build anytime any of our agent or prompt files change. And then I'm going to pipe the result of these grouped commands into our plan.

[00:41] And once I hit enter, because this inherits from standard in, Our command history with all of the previous commands we ran and then our user prompt, which we just echoed out, will be piped into Claude here and piped into our planner, which will fire off the web searching and go ahead and create a plan for us. It looks like there was just an update a couple seconds ago, I'll go ahead and update after this, but for now I'll just sit back and let this take care of this task I performed over and over again and allow Clawd to figure out a better way for me to do this because it can see the patterns that we established. So anytime you do something like two or three times and you think I need a script for this and that output and the script is in the terminal you can just pull up your history and throw it at Claude and tell you to build something for you. So now we should have a plan built out for us. If I scroll back up, it should be right around here.

[01:34] If we look at this plan and assume everything looks right, if we want to implement this after reading through it, I'll open our terminal again, shut down our current session, I'm going to update Claude code, maybe there's something new and fun in there. Then we can run Clawed and redirect our plans, slash, and grab our script development plan, hit enter, and that will pipe the file in. I'm going to hit shift tab to enable the accept edit modes automatically, and that piped the file in so it has that plan and it's running that plan, and I could fire that entire thing up from the terminal. So our plan did want to create a scripts directory, so we need to allow that. Then we'll go ahead and test the script, allow it to hornswoggle for a bit.

[02:14] Then it will test our watch mode. It verified watch was working. Checking the binaries exist. So now it says it's done. I'll go ahead and exit out.

[02:22] We'll fire off bun watch. So anytime we come into one of our prompts, I'll just add a new line here, hit save. You'll see everything recompiled and I no longer have to build each time, I can just let my tool build for me.



https://app.egghead.io/api/v1/lessons/automate-repetitive-tasks-by-piping-your-shell-history-to-an-ai-agent~jcohu/transcript

Claude Code Automation Cookbook: Recipes for AI Agents

John Lindquist

Course Content