create-agent-app

Start with a minimal TypeScript LangChain CLI agent, then grow it into an API or chat app.

pnpm dlx @bell_008/create-agent-app my-agent

Quick Start

pnpm dlx @bell_008/create-agent-app my-agent
cd my-agent
cp .env.example .env
pnpm install
pnpm run typecheck
pnpm run test
pnpm run dev "What's the weather in San Francisco?"

Set OPENAI_API_KEY in .env before running the agent.

Why

LangChain and LangGraph already provide strong TypeScript SDKs, examples, and a LangGraph Server template via npm create langgraph.

create-agent-app focuses on a different path: app-first TypeScript agent projects. Start with a minimal CLI createAgent core, then choose whether you want an HTTP API, a Next.js chat shell, or a deployable single-user product shell.

Use npm create langgraph when you want a LangGraph Server project first. Use create-agent-app when you want a TypeScript agent app that can start small and grow into a product shape.

Want A Web App?

Generate a deployable single-user chat product shell with local Markdown RAG:

pnpm dlx @bell_008/create-agent-app my-chat \
  --template agent-chat-product \
  --capability rag \
  --provider openai \
  --package-manager pnpm \
  --yes
cd my-chat
cp .env.example .env
pnpm install
pnpm run ingest
pnpm run dev

Open http://localhost:3000. The generated project includes data/company-handbook.md, a search_knowledge_base tool, and Sources in the Web UI when the agent uses retrieved context.

Templates

Template	Shape	Use it for
basic-agent	CLI agent core	Learning createAgent, typed tools, env setup, tests
api-agent	HTTP API	Calling the agent from an existing frontend or backend
web-chat-agent	Next.js chat app	Teaching, demos, and lightweight prototypes
agent-chat-product	Next.js product shell	A deployable single-user chat app starting point

Capabilities

Capabilities add agent behavior without changing the product shell.

Capability	What it adds
rag	Local Markdown knowledge base, sample handbook, search_knowledge_base tool, and pnpm run ingest

Example:

pnpm dlx @bell_008/create-agent-app my-agent --template agent-chat-product --capability rag --provider openai --package-manager pnpm --yes

Product Chat Example

pnpm dlx @bell_008/create-agent-app my-chat --template agent-chat-product --provider openai --package-manager pnpm --yes
cd my-chat
cp .env.example .env
pnpm install
pnpm run dev

Open http://localhost:3000.

The product shell includes:

• Next.js app router
• Streaming /api/chat route
• Browser message history
• Loading, error, clear, and abort states
• Vercel deployment notes
• LangSmith-ready env variables

It intentionally does not include auth, billing, a database, or multi-user conversation persistence.

RAG Example

pnpm dlx @bell_008/create-agent-app my-rag-chat --template agent-chat-product --capability rag --provider openai --package-manager pnpm --yes
cd my-rag-chat
cp .env.example .env
pnpm install
pnpm run ingest
pnpm run dev

Replace src/rag/retrieve.ts when you are ready to use pgvector, Pinecone, Supabase, or another vector store.

Non-Interactive Usage

pnpm dlx @bell_008/create-agent-app my-agent \
  --template web-chat-agent \
  --capability rag \
  --provider openai \
  --package-manager pnpm \
  --yes

Template Internals

The generator composes templates from reusable parts:

templates/parts/agent-core
templates/parts/cli-shell
templates/parts/api-shell
templates/parts/next-chat-shell
templates/parts/product-chat-shell
templates/capabilities/rag

This keeps every template on the same agent core while allowing different product shells.

Development

pnpm install
pnpm run typecheck
pnpm test
pnpm run test:generated

test:generated builds the CLI and verifies that every public template can generate the expected files. To also install and test each generated project, run:

VERIFY_GENERATED_INSTALL=1 pnpm run test:generated

Publish Check

npm_config_cache=/private/tmp/create-agent-app-npm-cache pnpm run pack:check

The temporary npm cache avoids local npm cache permission issues.

Package Name

This package is published as @bell_008/create-agent-app.

The unscoped npm package name create-agent-app is already published by another owner, so the README uses pnpm dlx @bell_008/create-agent-app as the stable invocation.

License

MIT