AI Agent CLI Template for Node.js / ChatBotKit

A standalone command-line AI agent template that uses the ChatBotKit Agent SDK to run bespoke agents with built-in tools for file manipulation, code editing, and shell command execution.

Note: This template is deliberately bare-bones. It provides the minimal structure and wiring needed to get a working app, intentionally leaving styling, layout, and architectural choices open so you can build on top without fighting existing opinions.

Why ChatBotKit?

Building a capable AI agent typically means sourcing models, setting up tool execution, managing state, and handling all the plumbing yourself. The cost adds up fast - not just in money, but in engineering time.

ChatBotKit brings models, tools, conversation management, and more into one platform. This template gets you started with a working CLI agent that includes built-in tools, multi-iteration execution, and optional platform integration out of the box.

Features

• Custom tools - Add domain-specific tools in src/tools.js using zod schemas
• Built-in file tools - Read, write, and edit files with line-range support
• Shell execution - Run non-interactive shell commands with timeout control
• Streaming output - Real-time token streaming in interactive terminals
• JSON output - Structured JSON output for piping and automation
• Platform bots - Optionally use a pre-configured ChatBotKit bot with all its platform capabilities

Setup

Prerequisites

• Node.js 20+
• A ChatBotKit account and API token

Quick Start

# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env and add your CHATBOTKIT_API_SECRET# (get a token from https://chatbotkit.com/tokens)# Run the agent
node src/index.js "List all JavaScript files in the current directory"

Usage

# Basic usage - pass a prompt as an argument
node src/index.js "Summarize the contents of README.md"# Use a custom agent definition file
node src/index.js -a my-agent.md "Review the code in src/"# Specify a model
node src/index.js -m claude-sonnet-4-20250514 "Explain this codebase"# Use a ChatBotKit platform bot
node src/index.js -b bot_abc123 "Help me with my project"# Disable built-in tools (only custom tools available)
node src/index.js --no-builtin-tools "What time is it?"# Debug mode - print raw stream events
node src/index.js -d "Debug this issue"# Pipe-friendly JSON output (non-TTY)
node src/index.js "List files"| jq .

CLI Options

Option	Description
-a, --agent <path>	Path to an agent markdown file
-m, --model <model>	Model to use (default: gpt-5.4-mini)
-b, --bot <id>	Use a ChatBotKit bot by ID
-i, --max-iterations <n>	Maximum iterations (default: 100)
--no-builtin-tools	Disable built-in file and exec tools
-d, --debug	Print raw stream events to stderr

Project Structure

template-node-agent-cli-js/
src/
index.js # CLI entry point and agent execution loop
tools.js # Custom tool definitions (add your own here)
.env.example # Environment variable template
package.json

Customization

Custom Tools

Add tools to src/tools.js. Each tool needs a description, a zod input schema, and a handler:

import{z}from'zod'exportconstcustomTools={fetchUrl: {description: 'Fetch the contents of a URL',input: z.object({url: z.string().url().describe('The URL to fetch'),}),handler: async(input)=>{constresponse=awaitfetch(input.url)consttext=awaitresponse.text()return{success: true,content: text.slice(0,5000)}},},}

Environment Variables

Variable	Required	Description
CHATBOTKIT_API_SECRET	Yes	Your ChatBotKit API token

License

MIT - see LICENSE