Adding Models
Guide for adding new LLM models to Letta Code. Use when the user wants to add support for a new model, needs to know valid model handles, or wants to update model-specific compatibility behavior. Covers runtime catalog sources, CI test matrices, and handle validation.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Adding Models when an AI agent needs a reusable SKILL.md workflow for this job: Guide for adding new LLM models to Letta Code. Use when the user wants to add support for a new model, needs to know valid model handles, or wants to update model-specific compatibility behavior. Covers runtime catalog sources, CI test matrices, and handle validation.
When not to use it
Skip Adding Models when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/adding-models # Save SKILL.md to ~/.claude/skills/adding-models/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/adding-models/SKILL.md. For a shared project, commit the folder at .claude/skills/adding-models/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Adding Models skill for this task: Use Adding Models when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- geminiinferred
The skill text mentions Gemini or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- copilotinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Adding Models
This skill guides you through adding a new LLM model to Letta Code.
## Quick Reference
**Key files**: - `src/agent/remote-model-catalog.ts` - Runtime catalog loading and projection - `src/agent/model-catalog.ts` - Model lookup and compatibility aliases - `.github/workflows/ci.yml` - CI test matrix (optional) - `src/tools/manager.ts` - Toolset detection logic (rarely needed)
## Workflow
### Step 1: Find Valid Model Handles
First identify the agent source. These inputs are deliberately different:
| Agent source | Rows shown | Labels, presets, and capabilities | |---|---|---| | Cloud hosted | `GET /v1/models/catalog` only | `GET /v1/models/catalog` | | Cloud organization BYOK | BYOK rows from `GET /v1/models` | Match to catalog metadata using provider metadata and model name; retain the BYOK handle for selection | | Local | pi-ai inventory | pi-ai metadata | | Custom App Server | Server runtime inventory | Server runtime metadata |
In Cloud mode, never use base/hosted rows from `GET /v1/models` to filter, supplement, delay, or provide a fallback for the hosted catalog. This once made GPT-4o appear in a selector even though the Cloud catalog deliberately omitted it. `GET /v1/models` remains necessary for organization-specific BYOK rows.
Query the Cloud hosted catalog to see hosted preset IDs, handles, and capabilities:
```bash curl -s https://api.letta.com/v1/models/catalog | jq '.models[] | [.id, .handle]' ```
To inspect organization BYOK rows from a Cloud backend, query its model inventory and filter by `provider_category`:
```bash curl -s https://api.letta.com/v1/models/ \ | jq '.[] | select(.provider_category == "byok") | [.handle, .provider_type]' ```
Do not use this response as a second hosted catalog.
Common provider prefixes: - `anthropic/` - Claude models - `openai/` - GPT models - `google_ai/` - Gemini models - `google_vertex/` - Vertex AI - `openrouter/` - Various providers
### Step 2: Update the Owning Catalog
Letta Code does not bundle a model catalog:
- Cloud hosted rows and presets come from the server's `GET /v1/models/catalog` response. - Cloud `GET /v1/models` contributes only organization BYOK rows to selectors. - Local model inventory comes from pi-ai and the active provider runtimes.
Add the model at the source that owns it. A hosted preset belongs in the server catalog. A local provider model belongs in pi-ai or that provider's discovery runtime.
Only change this repository when the model needs Letta Code-specific compatibility behavior, such as preserving an established CLI alias or recognizing a new provider for toolset selection. Keep that logic narrow and derive the handle and metadata from the runtime catalog rather than copying model definitions here.
### Step 3: Test the Model
Test with headless mode:
```bash bun run src/index.ts --new --model <model-id> -p "hi, what model are you?" ```
Example: ```bash 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`:
```yaml # 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.
Intended uses
- Use Adding Models when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.