@jigonr/letta-switch

v0.1.0

Published

23 days ago

Comprehensive configuration manager for Letta CLI (agents + models + memory blocks)

0High
0Medium
0Low

jigonr

letta cli agent switch ai profile memory model

letta-switch

Comprehensive configuration manager for Letta CLI - manage agents, models, and memory blocks.

Features

Agent Management: Sync, search, filter, and favorite agents from Letta API
Profile System: Save and reuse agent+model+memory configurations
Memory Blocks: Configure custom memory block combinations
Project-Aware: Auto-detect .letta-switch.json in projects
Type-Safe: Built with TypeScript, Zod validation, and strict types
Model Support: Works with all Letta-supported models (claude-pro-max/, anthropic/, etc.)

Installation

npm install -g @jigonr/letta-switch

Quick Start

Authenticate with Letta (if not already done):
```
letta
```
Sync agents from Letta API:
```
letta-switch sync
```
List available agents:
```
letta-switch list
```

Launch an agent:

letta-switch my-agent --model claude-pro-max/claude-opus-4-5

Save a profile:

letta-switch my-agent --model claude-pro-max/claude-opus-4-5 --memory human,persona --save-as dev-profile

Launch using a profile:
```
letta-switch --profile dev-profile
```

Commands

Default Command: Launch Agent

letta-switch [agent] [options]

# Launch agent with custom model
letta-switch my-agent --model anthropic/claude-3-5-sonnet-20241022

# Launch with custom memory blocks
letta-switch my-agent --memory human,persona,context

# Launch and save as profile
letta-switch my-agent --model claude-pro-max/claude-opus-4-5 --save-as my-profile

# Launch using saved profile
letta-switch --profile my-profile

# Show current status (no arguments)
letta-switch

Options:

--profile <name> - Use saved profile
--model <model> - Model to use (e.g., claude-pro-max/claude-opus-4-5, anthropic/claude-3-5-sonnet-20241022)
--memory <blocks> - Comma-separated memory blocks (e.g., human,persona)
--init-blocks <blocks> - Comma-separated init blocks
--base-tools <tools> - Comma-separated base tools
--save-as <name> - Save this configuration as a profile
--json - Output in JSON format

`letta-switch sync`

Sync agents from Letta API:

# Sync from default API
letta-switch sync

# Sync from custom API URL
letta-switch sync --api-url https://custom-letta-api.com

`letta-switch agents` / `letta-switch list`

List all agents:

# List all agents
letta-switch agents

# Search agents
letta-switch agents --search "coding"

# Filter by tag
letta-switch agents --tag production

# JSON output
letta-switch agents --json

`letta-switch profiles`

List all saved profiles:

# List profiles
letta-switch profiles

# JSON output
letta-switch profiles --json

`letta-switch save <name>`

Save a new profile:

letta-switch save dev-profile \
  --agent my-agent \
  --model claude-pro-max/claude-opus-4-5 \
  --memory human,persona \
  --description "Development profile"

`letta-switch delete <name>`

Delete a saved profile:

letta-switch delete dev-profile

`letta-switch favorite <agent>`

Mark an agent as favorite:

letta-switch favorite my-agent

`letta-switch info <agent>`

Show detailed agent information:

letta-switch info my-agent

# JSON output
letta-switch info my-agent --json

`letta-switch status`

Show current configuration status:

letta-switch status

# JSON output
letta-switch status --json

Configuration

Global Configuration

Configuration is stored in ~/.letta/letta-config.json:

{
  "version": "1.0",
  "currentProfile": "dev-profile",
  "profiles": {
    "dev-profile": {
      "agent": "my-agent",
      "model": "claude-pro-max/claude-opus-4-5",
      "memoryBlocks": ["human", "persona"],
      "description": "Development profile"
    }
  },
  "agents": [
    {
      "id": "agent-123",
      "name": "my-agent",
      "description": "My custom agent",
      "created": "2025-01-01T00:00:00Z",
      "tags": ["coding"],
      "favorite": true,
      "lastLaunched": "2025-01-02T00:00:00Z"
    }
  ],
  "models": {},
  "filters": {
    "excludePatterns": ["-sleeptime$", "^test-"]
  },
  "lastSync": "2025-01-02T00:00:00Z"
}

Project-Specific Configuration

Create .letta-switch.json in your project directory:

{
  "version": "1.0",
  "currentProfile": "project-profile",
  "profiles": {
    "project-profile": {
      "agent": "project-agent",
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "memoryBlocks": ["human", "persona", "project-context"]
    }
  }
}

letta-switch will automatically detect and merge project configs with global settings.

Letta API Authentication

The Letta API key is stored separately in ~/.letta/settings.json:

{
  "env": {
    "LETTA_API_KEY": "your-api-key-here"
  }
}

This is automatically created when you run letta for the first time.

Agent Filtering

By default, letta-switch filters out agents matching these patterns:

-sleeptime$ - Agents ending with -sleeptime
^test- - Agents starting with test-

You can customize filters in your config file:

{
  "filters": {
    "excludePatterns": ["-sleeptime$", "^test-", "^temp-"]
  }
}

Model Support

letta-switch supports all Letta-compatible models:

Subscription Models (claude-pro-max/*)

letta-switch my-agent --model claude-pro-max/claude-opus-4-5
letta-switch my-agent --model claude-pro-max/claude-sonnet-4-5

API Models (anthropic/*)

letta-switch my-agent --model anthropic/claude-3-5-sonnet-20241022
letta-switch my-agent --model anthropic/claude-3-5-haiku-20241022

OpenAI Models

letta-switch my-agent --model openai/gpt-4-turbo

Memory Blocks

Configure custom memory block combinations:

# Default memory blocks
letta-switch my-agent --memory human,persona

# Custom blocks
letta-switch my-agent --memory human,persona,context,knowledge

# Save for reuse
letta-switch my-agent --memory human,persona,context --save-as my-memory-profile

Examples

Development Workflow

# First time setup
letta-switch sync

# Create development profile
letta-switch coding-agent \
  --model claude-pro-max/claude-opus-4-5 \
  --memory human,persona,code-context \
  --save-as dev

# Use the profile
letta-switch --profile dev

Multiple Projects

# Project A
cd ~/projects/project-a
cat > .letta-switch.json <<EOF
{
  "version": "1.0",
  "profiles": {
    "project-a": {
      "agent": "project-a-agent",
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "memoryBlocks": ["human", "persona", "project-a-context"]
    }
  },
  "currentProfile": "project-a"
}
EOF

# Project B
cd ~/projects/project-b
cat > .letta-switch.json <<EOF
{
  "version": "1.0",
  "profiles": {
    "project-b": {
      "agent": "project-b-agent",
      "model": "claude-pro-max/claude-opus-4-5",
      "memoryBlocks": ["human", "persona", "project-b-context"]
    }
  },
  "currentProfile": "project-b"
}
EOF

# letta-switch will auto-detect the correct config in each directory
cd ~/projects/project-a && letta-switch  # Uses project-a-agent
cd ~/projects/project-b && letta-switch  # Uses project-b-agent

Favorite Agents

# Mark agents as favorites for quick access
letta-switch favorite my-main-agent
letta-switch favorite coding-helper

# List agents (favorites shown first with ★)
letta-switch agents

Troubleshooting

"Letta settings not found"

Run letta to authenticate first:

letta

"LETTA_API_KEY not found in settings"

Check your Letta settings file:

cat ~/.letta/settings.json

Make sure it contains:

{
  "env": {
    "LETTA_API_KEY": "your-api-key"
  }
}

"Agent not found"

Make sure you've synced agents from the API:

letta-switch sync
letta-switch agents  # Verify agent exists

"Profile not found"

List available profiles:

letta-switch profiles

API Connection Issues

Test with custom API URL:

letta-switch sync --api-url https://api.letta.com/v1

Development

Requirements

Node.js 18+
Bun (for development)

Setup

# Clone repository
git clone https://github.com/jigonr/letta-switch.git
cd letta-switch

# Install dependencies
bun install

# Build
bun run build

# Test locally
node dist/index.js --help

Project Structure

letta-switch/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── commands/             # Command implementations
│   │   ├── launch.ts         # Launch agent
│   │   ├── sync.ts           # Sync from API
│   │   └── list.ts           # List agents/profiles
│   ├── config/               # Configuration management
│   │   ├── schema.ts         # Zod schemas
│   │   └── manager.ts        # Profile manager
│   ├── agents/               # Agent management
│   │   ├── registry.ts       # Agent registry
│   │   └── filter.ts         # Filtering logic
│   ├── api/                  # API client
│   │   └── client.ts         # Letta API client
│   └── utils/                # Utilities
│       ├── errors.ts         # Error types
│       └── logger.ts         # Logging
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── biome.json

Scripts

# Build
bun run build

# Lint and format
bun run lint

# Type check
bun run typecheck

Security

API keys are stored separately in ~/.letta/settings.json (not in config files)
File permissions: settings files are chmod 600 (read/write for owner only)
Path validation: all file paths are validated to prevent traversal attacks
API key redaction: API keys are redacted in logs

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run bun run lint and bun run typecheck
Submit a pull request

License

MIT - see LICENSE

Changelog

0.1.0 (2025-01-02)

Initial release:

Agent management with sync, search, filter, favorites
Profile system for saving configurations
Memory block configuration
Project-specific config detection
Type-safe with Zod validation
Support for all Letta-compatible models