# CLI Agent Starter Kit

A TypeScript CLI agent with AI SDK, Anthropic Claude, and Phoenix observability. Demonstrates a Phoenix documentation assistant with declarative tool architecture.

## Quick Start

```bash
# Install and setup
pnpm install
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env

# Run (auto-starts Phoenix)
pnpm dev
```

**Requirements:** Node.js 22+ (see `.nvmrc`), pnpm, Docker Desktop, Anthropic API key

**Commands:** `/help`, `/exit`

**Phoenix UI:** http://localhost:6006

## Project Structure

```
src/
├── cli.ts              # Entry point
├── agent/              # Agent factory
├── tools/              # Tool definitions
│   ├── index.ts        # Tool exports
│   ├── datetime.ts     # Utility tool
│   └── mcp.ts          # Phoenix docs MCP
├── prompts/            # System instructions
└── ui/                 # CLI interface
```

## Adding Tools

**1. Create tool file** (`src/tools/mytool.ts`):

```typescript
import { tool } from "ai";
import { z } from "zod";

export const myTool = tool({
  description: "What the tool does",
  inputSchema: z.object({/* params */}),
  execute: async (params) => {
    /* logic */
  },
});
```

**2. Export** (`src/tools/index.ts`):

```typescript
export { myTool } from "./mytool.js";
```

**3. Register** (`src/cli.ts`):

```typescript
const tools = { my: myTool };
```

## Naming Convention

| Type      | Pattern         | Example        |
| --------- | --------------- | -------------- |
| Export    | `camelCaseTool` | `dateTimeTool` |
| File      | `camelcase.ts`  | `datetime.ts`  |
| Agent key | `camelCase`     | `dateTime`     |

## Tool Types

- **Utility**: Simple helpers (datetime.ts)
- **MCP**: External integrations via Model Context Protocol (mcp.ts)

## Scripts

```bash
pnpm dev              # Run in development
pnpm build            # Compile TypeScript
pnpm start            # Run production build
pnpm phoenix:logs     # View Phoenix logs
pnpm eval             # Run all evaluations
```

## Evaluations

Built-in evaluation harness for testing agent quality. Create evaluators, datasets, and experiments in `evals/`:

```bash
pnpm eval                      # Run all evaluations
pnpm eval:terminal-format      # Run specific eval
```

See `evals/README.md` for creating custom evaluators and experiments.

## Troubleshooting

**No traces?** Check Phoenix: `pnpm phoenix:logs`

**Phoenix won't start?** Ensure Docker is running, port 6006 is available

## Resources

- [AI SDK Docs](https://sdk.vercel.ai/docs)
- [Phoenix Docs](https://arize.com/docs/phoenix)
