- Adding Models
- This skill guides you through adding a new LLM model to Letta Code.
- Quick Reference
- Key files
- :
- src/models.json
- - Model definitions (required)
- .github/workflows/ci.yml
- - CI test matrix (optional)
- src/tools/manager.ts
- - Toolset detection logic (rarely needed)
- Workflow
- Step 1: Find Valid Model Handles
- Query the Letta API to see available models:
- curl
- -s
- https://api.letta.com/v1/models/
- |
- jq
- '.[] | .handle'
- Or filter by provider:
- curl
- -s
- https://api.letta.com/v1/models/
- |
- jq
- '.[] | select(.handle | startswith("google_ai/")) | .handle'
- Common provider prefixes:
- anthropic/
- - Claude models
- openai/
- - GPT models
- google_ai/
- - Gemini models
- google_vertex/
- - Vertex AI
- openrouter/
- - Various providers
- Step 2: Add to models.json
- Add an entry to
- src/models.json
- :
- {
- "id"
- :
- "model-shortname"
- ,
- "handle"
- :
- "provider/model-name"
- ,
- "label"
- :
- "Human Readable Name"
- ,
- "description"
- :
- "Brief description of the model"
- ,
- "isFeatured"
- :
- true
- ,
- // Optional: shows in featured list
- "updateArgs"
- :
- {
- "context_window"
- :
- 180000
- ,
- "temperature"
- :
- 1.0
- // Optional: provider-specific settings
- }
- }
- Field reference
- :
- id
-
- Short identifier used with
- --model
- flag (e.g.,
- gemini-3-flash
- )
- handle
-
- Full provider/model path from the API (e.g.,
- google_ai/gemini-3-flash-preview
- )
- label
-
- Display name in model selector
- description
-
- Brief description shown in selector
- isFeatured
-
- If true, appears in featured models section
- updateArgs
- Model-specific configuration (context window, temperature, reasoning settings, etc.)
Provider prefixes
:
anthropic/
- Anthropic (Claude models)
openai/
- OpenAI (GPT models)
google_ai/
- Google AI (Gemini models)
google_vertex/
- Google Vertex AI
openrouter/
- OpenRouter (various providers)
Step 3: Test the Model
Test with headless mode:
bun run src/index.ts
--new
--model
<
model-id
-p "hi, what model are you?" Example: bun run src/index.ts --new --model gemini-3-flash -p "hi, what model are you?" Step 4: Add to CI Test Matrix (Optional) To include the model in automated testing, add it to .github/workflows/ci.yml :
Find the headless job matrix around line 122
- model
- :
- [
- gpt
- -
- 5
- -
- minimal
- ,
- gpt
- -
- 4.1
- ,
- sonnet
- -
- 4.5
- ,
- gemini
- -
- pro
- ,
- your
- -
- new
- -
- model
- ,
- glm
- -
- 4.6
- ,
- haiku
- ]
- Toolset Detection
- Models are automatically assigned toolsets based on provider:
- openai/*
- →
- codex
- toolset
- google_ai/*
- or
- google_vertex/*
- →
- gemini
- toolset
- Others →
- default
- toolset
- This is handled by
- isGeminiModel()
- and
- isOpenAIModel()
- in
- src/tools/manager.ts
- . You typically don't need to modify this unless adding a new provider.
- Common Issues
- "Handle not found" error
-
- The model handle is incorrect. Run the validation script to see valid handles.
- Model works but wrong toolset
- Check src/tools/manager.ts to ensure the provider prefix is recognized.