Configuration

Letta Code uses a hierarchical configuration system with global and project-level settings.

Authentication

Letta API (default)

On first run, Letta Code prompts you to authenticate via OAuth:

1. Run letta
2. Follow the browser prompt to log in at app.letta.com

API key

Alternatively, set an API key directly:

export LETTA_API_KEY=your-api-key

Docker

See Docker setup to use Letta Code with a Letta server running in Docker.

Configuration files

Global settings (~/.letta/settings.json)

Applies to all projects:

{
  "tokenStreaming": true,
  "globalSharedBlockIds": {
    "persona": "block-id-...",
    "human": "block-id-..."
  }
}

Project settings (.letta/settings.local.json)

Personal, gitignored - your agent for this project:

{
  "lastAgent": "agent-id-..."
}

Shared project settings (.letta/settings.json)

Can be committed to share with your team:

{
  "permissions": {
    "allow": ["Bash(pnpm lint)", "Bash(pnpm test)"]
  }
}

Settings reference

Setting	Type	Description
tokenStreaming	boolean	Enable real-time token streaming
enableSleeptime	boolean	Enable sleeptime agents for passive memory updates (default: false)
lastAgent	string	ID of last used agent (for auto-resume)
globalSharedBlockIds	object	IDs of global memory blocks
permissions.allow	string[]	Patterns to auto-allow
permissions.deny	string[]	Patterns to always deny

Environment variables

Variable	Description
LETTA_API_KEY	API key for authentication (alternative to OAuth)
LETTA_BACKFILL	Load message history on agent resume. Set to 0 or false to start with clean chat. Default: true
LETTA_ENABLE_LSP	Enable LSP diagnostics for type error detection. Set to 1 to enable
DISABLE_AUTOUPDATER	Disable automatic updates. Set to 1 to disable

LSP Diagnostics

LSP integration is experimental. Behavior may change in future releases.

Letta Code can integrate with Language Server Protocol (LSP) servers to provide automatic type error detection when reading files.

Enable LSP

export LETTA_ENABLE_LSP=1

Supported languages

Language	Extensions	LSP Server
TypeScript/JavaScript	.ts, .tsx, .js, .jsx, .mjs, .cjs	typescript-language-server
Python	.py, .pyi	pyright

How it works

When LSP is enabled and you read a supported file:

1. Letta Code starts the appropriate LSP server (auto-installed if missing)
2. The file is analyzed for type errors, syntax errors, and other diagnostics
3. Any errors are appended to the file content in a <file_diagnostics> block

This file has errors, please fix
<file_diagnostics>
ERROR [10:5] Cannot find name 'foo'
ERROR [15:3] Type 'string' is not assignable to type 'number'
</file_diagnostics>

Behavior

• Auto-included for files under 500 lines
• Manual control via include_types parameter on the Read tool:
  • include_types: true - Force include diagnostics (even for large files)
  • include_types: false - Skip diagnostics (even for small files)

This helps the agent catch type errors before making edits, reducing iteration cycles.

Updates

Letta Code automatically keeps itself up to date to ensure you have the latest features and fixes.

• Update checks: Performed on startup and periodically while running
• Update process: Downloads and installs automatically in the background
• Applying updates: Updates take effect the next time you start Letta Code

Disable auto-updates

export DISABLE_AUTOUPDATER=1

Manual update

letta update

Recommended .gitignore

# Letta Code personal settings
.letta/settings.local.json

Keep .letta/settings.json tracked to share project context with your team.