Letta Code is a command-line harness around the stateful Letta Agents API. You can use Letta Code to create and connect with any Letta agent (even non-coding agents!) - Letta Code simply gives your agents the ability to interact with your local dev environment, directly in your terminal.

Important

Letta Code is a research preview in active development, and may have bugs or unexpected issues. To learn more about the roadmap and chat with the dev team, visit our Discord at discord.gg/letta. Contributions welcome, join the fun.

Quickstart

Get a Letta API key at: https://app.letta.com

Install the package via npm:

npm install -g @letta-ai/letta-code

Make sure you have your Letta API key set in your environment:

export LETTA_API_KEY=...

Then run letta to start Letta Code (see various command-line options below):

letta

Any of the agents you create in Letta Code will be viewable (and fully interactable!) inside the Agent Development Environment.

Persistence

All agents in Letta are stateful: they maintain context forever and can self-edit their own memory blocks. Agents can share memory blocks across projects—for example, multiple agents can share user coding preferences while maintaining project-specific memories independently.

Memory Configuration

Letta Code uses a hierarchical memory system with both global and local blocks:

Global (~/.letta/settings.json)

persona block - defines agent behavior
human block - stores user coding preferences

Local (./.letta/settings.json)

project block - stores project-specific context

Starting Letta

letta                    # New agent (attaches to existing memory blocks or creates new)
letta --continue         # Resume last agent session
letta --agent <id>       # Resume specific agent session

When you start a new agent, it automatically connects to existing memory block IDs from your settings files. If none exist, it creates them.

Memory blocks are highly configurable — see our docs for advanced configuration options. Join our Discord to share feedback on persistence patterns for coding agents.

Usage

Interactive Mode

letta                    # Start new session (new agent with shared memory blocks)
letta --continue         # Resume last session (last recently used agent)
letta --agent <id>       # Open specific agent

Headless Mode

letta -p "your prompt"                           # Run non-interactive
letta -p "commit changes" --continue             # Continue previous session
letta -p "run tests" --allowedTools "Bash"       # Control tool permissions
letta -p "run tests" --disallowedTools "Bash"    # Control tool permissions

# Pipe input from stdin
echo "Explain this code" | letta -p
cat file.txt | letta -p
gh pr diff 123 | letta -p --yolo                 # Review PR changes

You can also use the --tools flag to control the underlying attachment of tools (not just the permissions). Compared to disallowing the tool, this will additionally remove the tool schema from the agent's context window.

letta -p "run tests" --tools "Bash,Read"         # Only load specific tools
letta -p "analyze code" --tools ""               # No tools (analysis only)

Permissions

Tool selection (controls which tools are loaded):

--tools "Bash,Read,Write"                        # Only load these tools
--tools ""                                       # No tools (conversation only)

Permission overrides (controls tool access, applies to loaded tools):

--allowedTools "Bash,Read,Write"                 # Allow specific tools
--allowedTools "Bash(npm run test:*)"            # Allow specific commands
--disallowedTools "Bash(curl:*)"                 # Block specific patterns
--permission-mode acceptEdits                    # Auto-allow Write/Edit tools
--permission-mode plan                           # Read-only mode
--permission-mode bypassPermissions              # Allow all tools (use carefully!)
--yolo                                           # Alias for --permission-mode bypassPermissions

Permission modes:

default - Standard behavior, prompts for approval
acceptEdits - Auto-allows Write/Edit/NotebookEdit
plan - Read-only, allows analysis but blocks modifications
bypassPermissions - Auto-allows all tools (for trusted environments)

Permissions are also configured in .letta/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(src/**)"],
    "deny": ["Bash(rm -rf:*)", "Read(.env)"]
  }
}

Installing from source

First, install Bun if you don't have it yet: https://bun.com/docs/installation

Run directly from source (dev workflow)

# install deps
bun install

# run the CLI from TypeScript sources (pick up changes immediately)
bun run dev:ui
bun run dev:ui -- -p "Hello world"  # example with args

Build + link the standalone binary

# build bin/letta (includes prompts + schemas)
bun run build

# expose the binary globally (adjust to your preference)
bun link --global   # or: bun add --global .

# now you can run the compiled CLI
letta

Whenever you change source files, rerun bun run build before using the linked letta binary so it picks up your edits.

Made with 💜 in San Francisco

Languages

TypeScript 98.2%

Python 1%

Shell 0.5%

JavaScript 0.2%

MDX 0.1%