Create Locus App

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

Quick Start

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

Or let the CLI prompt you for the project name:

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 [email protected]"
  "what is my payment context?"
  "help" - list available tools

You: send 10 usdc to [email protected]

Thinking...

  Calling: locus_send_payment
  Tool completed

Agent: I've initiated a payment of 10 USDC to [email protected]. The transaction is being processed.

You: exit

Goodbye!

Usage

Interactive Mode

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

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

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 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

OpenAI API Key (optional)

Get your API key from OpenAI Platform

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
• LangChain Documentation
• Claude Agent SDK Documentation
• Anthropic Documentation

Support

For issues or questions:

• GitHub Issues
• Locus Documentation

License

MIT

Built by Locus Technologies