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 live and maintain context forever, and can self-edit their own memory blocks via memory tools. Different agents in Letta can share the same memory blocks: for example, you can have multiple agents working on different coding projects that all share a memory about the user's general coding style preferences, while also having independent memory blocks storing memory specific to their own project.

In Letta Code, we provide a default memory configuration that has both globally and locally shared blocks:

\ ~/.letta/settings.json (shared across all agents spawned on your device)
--> persona block (determines the behavior of your coding agent)
--> human block (tracks important information about user coding preferences)

\ [your-current-dir]/.letta/settings.json (shared across agents spawned specifically in this directory)
--> project block (tracks important information about this specific coding project)

There are three main ways to start Letta:

Run letta: creates a new agent, looks in settings.json files for shared memory blocks IDs to connect to (creates new if they don't exist).
Run letta --continue: will resume your connection with your last recently used agent
Run letta --agent <agent-id>: will resume your connection with a specific agent

Memory blocks in Letta are incredibly general and highly configurable (see our docs), and you can reconfigure the persistence behavior to be more to your liking. We're still experimenting with figuring out the right way to do persistence for coding agents, so let us know on our Discord if you have any suggestions!

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%