npm package: @locus-technologies/create-locus-app
Description: Create a Locus-powered application with a single command
Author: Locus Technologies
Latest version: 0.2.0

# Create Locus App

Create a Locus-powered AI payment application with a single command.

## Quick Start

```bash
npx @locus-technologies/create-locus-app my-app
```

Or let the CLI prompt you for the project name:

```bash
npx @locus-technologies/create-locus-app
```

## What You Get

This CLI creates a ready-to-run Locus application with:

- **Interactive chat interface** - REPL-style conversation with your AI agent
- **Secure authentication** configured (OAuth or API Key)
- **AI agent setup** with your choice of framework and language
- **MCP tool integration** for Locus payment capabilities
- **Conversation history** for context-aware responses
- **Dependencies installed** automatically

## Framework Options

### LangChain (with OAuth)

Uses OAuth Client Credentials for secure machine-to-machine authentication with the Locus MCP server.

**Features:**
- Secure OAuth authentication (Client Credentials flow)
- LangChain ReAct agent with streaming responses
- Full MCP tool integration
- Support for Anthropic Claude or OpenAI GPT
- TypeScript or JavaScript

**Perfect for:** Production applications requiring secure authentication

### Claude SDK (with API Key)

Uses the Claude Agent SDK with API key authentication for direct Claude integration.

**Features:**
- Simple API key authentication
- Native Claude Agent SDK integration
- Auto-approval of Locus tools with `canUseTool` callback
- TypeScript or JavaScript

**Perfect for:** Quick prototypes and Claude-native development

## Interactive Chat Interface

All generated apps include an interactive chat interface where you can:

- Send natural language commands to your AI agent
- See tool calls as they happen
- Maintain conversation context across messages
- Use built-in commands:
  - `help` - List available tools
  - `clear` - Reset conversation history
  - `exit` or `quit` - Close the chat

Example session:

```
Locus Payment Agent - Interactive Chat

Type your commands below. Examples:
  "send 5 usdc to john@example.com"
  "what is my payment context?"
  "help" - list available tools

You: send 10 usdc to alice@example.com

Thinking...

  Calling: locus_send_payment
  Tool completed

Agent: I've initiated a payment of 10 USDC to alice@example.com. The transaction is being processed.

You: exit

Goodbye!
```

## Usage

### Interactive Mode

```bash
npx @locus-technologies/create-locus-app
```

The CLI will prompt you for:
1. Project name
2. Framework choice (LangChain or Claude SDK)
3. Language (TypeScript or JavaScript)
4. Model provider (Anthropic or OpenAI - LangChain only)
5. Required credentials

### With Project Name

```bash
npx @locus-technologies/create-locus-app my-awesome-app
```

### What Happens Next

The CLI will:
1. Create your project directory
2. Copy template files based on your choices
3. Configure environment variables securely
4. Install dependencies
5. Initialize git repository
6. Show next steps

## After Creation

```bash
cd my-app
npm start
```

Your interactive chat app is ready to run immediately!

## Requirements

- Node.js 14 or higher
- npm
- Locus credentials (Client ID/Secret for LangChain, or API Key for Claude SDK)
- Anthropic API key (or OpenAI API key if using OpenAI with LangChain)

## Get Credentials

### Locus Credentials
Visit [Locus Dashboard](https://paywithlocus.com) to get your:
- OAuth Client ID and Secret (for LangChain)
- API Key (for Claude SDK)

### Anthropic API Key
Get your API key from [Anthropic Console](https://console.anthropic.com)

### OpenAI API Key (optional)
Get your API key from [OpenAI Platform](https://platform.openai.com)

## Security

- All credentials are entered securely (hidden input)
- Environment variables are never logged or stored in bash history
- `.env` files have restrictive permissions (0600)
- `.env` is automatically added to `.gitignore`

## Project Structure

After creation, your project will have:

```
my-app/
├── index.ts (or index.js)  # Interactive chat application
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript config (TS only)
├── .env                    # Environment variables (not committed)
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore rules
└── README.md               # Project documentation
```

## Customization

The generated code is well-commented and designed to be extended:

1. **Modify the system prompt** - Change agent personality and behavior
2. **Add custom tools** - Extend beyond Locus payment tools
3. **Adjust tool permissions** - Fine-tune which tools are auto-approved
4. **Add persistence** - Save conversation history to a database
5. **Build a web interface** - Use the agent logic in a web application

## Learn More

- [Locus Documentation](https://docs.paywithlocus.com)
- [LangChain Documentation](https://js.langchain.com)
- [Claude Agent SDK Documentation](https://docs.anthropic.com)
- [Anthropic Documentation](https://docs.anthropic.com)

## Support

For issues or questions:
- [GitHub Issues](https://github.com/locus-technologies/create-locus-app/issues)
- [Locus Documentation](https://docs.paywithlocus.com)

## License

MIT

---

Built by Locus Technologies