Fimeg/letta-code
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Charles Packer
2025-12-14 15:08:54 -08:00
committed by GitHub
parent 82518f135b
commit f4480f6f5e
1 changed files with 27 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
README.md
View File

@@ -1,423 +1,68 @@
# Letta Code (Research Preview)
A self-improving, stateful coding agent that can learn from experience and improve with use.
Letta Code is a self-improving, stateful coding agent that can learn from experience and improve with use. You can use Letta Code as a general purpose **CLI harness** to connect any Letta agent (even non-coding agents!) to your local dev environment.
Letta Code is open source and model agnostic - supporting Claude Sonnet/Opus, GPT-5, Gemini 3 Pro, GLM-4.6, and more.
**Read more about how to use Letta Code on the [official docs page](https://docs.letta.com/letta-code).**
<img width="1713" height="951" alt="letta-code" src="https://github.com/user-attachments/assets/ae546e96-368a-4a7b-9397-3963a35c8d6b" />
---
## What is Letta Code?
Letta Code is a command-line harness around the stateful [Letta API](https://docs.letta.com/api-reference/overview). 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.
Letta Code is model agnostic, and supports Sonnet 4.5, GPT-5, Gemini 2.5, GLM-4.6, and more.
> [!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](https://discord.gg/letta). Contributions welcome, join the fun.
## Quickstart
## Get started
> Get a Letta API key at: [https://app.letta.com](https://app.letta.com/)
Requirements:
* [Node.js](https://nodejs.org/en/download) (version 18+)
* A [Letta Developer Platform](https://app.letta.com/) account (if you haven’t used Letta Code before, follow the instructions on startup to login via OAuth, or manually set `LETTA_API_KEY` as an environment variable)
Install the package via [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm):
```bash
npm install -g @letta-ai/letta-code
```
Set your Letta API key via environment variable:
Then run `letta` to start Letta Code in interactive mode (see various command-line options [on the docs](https://docs.letta.com/letta-code/commands)):
```bash
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](https://app.letta.com).
## Persistence
All agents in Letta are **stateful**: they maintain context forever and can self-edit their own [memory blocks](https://www.letta.com/blog/memory-blocks).
### Project-Level Agent Persistence
**Letta Code automatically remembers the last agent used in each directory.**
When you run `letta` in a project, it resumes where you left off with the same agent.
**How it works:**
- First time running `letta` in a directory → creates new agent (with shared memory blocks across all Letta Code agents)
- Subsequent runs → automatically resumes that agent
- Agent ID stored in `.letta/settings.local.json` (gitignored, personal to you)
You can also run Letta Code in headless mode, making it easy to integrate into scripts (see the [docs](https://docs.letta.com/letta-code/headless) for more):
```bash
letta # Auto-resumes project agent (or creates new if first time)
letta --new # Create new agent with new memory blocks
letta --agent <id> # Use specific agent ID
letta -p "Look around this repo and write a README.md documenting it at the root level"
```
### Memory Configuration
## Memory
Letta Code uses a hierarchical memory system:
**Global** (`~/.letta/settings.json`)
- API keys and credentials
- `persona` block - defines agent behavior
- `human` block - stores user coding preferences
**Project** (`./.letta/settings.local.json`)
- Last agent ID for this directory (auto-resumes)
- Gitignored - personal to you, not shared with your team
**Project Shared** (`./.letta/settings.json`)
- `project` block - stores project-specific context
- Can be committed - shared with team
Memory blocks are highly configurable — see our [docs](https://docs.letta.com/guides/agents/memory-blocks) for advanced configuration options.
Join our [Discord](https://discord.gg/letta) to share feedback on persistence patterns for coding agents.
## Skills
**Skills are automatically discovered from a `.skills` directory in your project.**
Skills allow you to define custom capabilities that the agent can reference and use. When you start a new session, Letta Code recursively scans for `SKILL.MD` files and loads any skill definitions found.
### Creating Skills
Create a `.skills` directory in your project root and organize skills in subdirectories:
All agents in Letta are **stateful**: they maintain context forever and can self-edit their own [memory blocks](https://www.letta.com/blog/memory-blocks).
If you’re using Letta Code for the first time, you will likely want to run the `/init` command to initialize the agent’s memory system:
```bash
mkdir -p .skills/data-analysis
> /init
```
Each skill is defined in a file named `SKILL.MD`. The directory structure determines the skill ID:
```
.skills/
├── data-analysis/
│ └── SKILL.MD # skill id: "data-analysis"
└── web/
└── scraper/
└── SKILL.MD # skill id: "web/scraper"
```
Create a skill file (`.skills/data-analysis/SKILL.MD`):
```markdown
---
name: Data Analysis Skill
description: Analyzes CSV files and generates statistical reports
category: Data Processing
tags:
- analytics
- statistics
- csv
---
# Data Analysis Skill
This skill analyzes data files and generates comprehensive reports.
## Usage
Use this skill to analyze CSV files and generate statistical summaries...
```
**Skill File Format:**
- **File name:** Must be named `SKILL.MD` (case-insensitive)
- **Required frontmatter:**
- `name` - Display name for the skill
- `description` - Brief description of what the skill does
- **Optional frontmatter:**
- `category` - Category for organizing skills (skills are grouped by category in the agent's memory)
- `tags` - Array of tags for filtering/searching
- **Body:** Additional details and documentation about the skill
Skills are automatically loaded into the agent's memory on startup, making them available for reference throughout your session.
### Custom Skills Directory
You can specify a custom skills directory using the `--skills` flag:
Over time, the agent will update its memory as it learns. To actively guide your agents memory, you can use the `/remember` command:
```bash
letta --skills /path/to/custom/skills
letta -p "Use the custom skills" --skills ~/my-skills
> /remember [optional instructions on what to remember]
```
## Usage
## Connecting to an existing Letta agent
### Interactive Mode
To connect to an existing agent, use the `--agent` flag:
```bash
letta # Auto-resume project agent (or create new if first time)
letta --new # Create new agent with new memory blocks
letta --agent <id> # Use specific agent ID
letta --model <model> # Specify model (e.g., claude-opus-4.5, claude-sonnet-4.5, gpt-4o)
letta -m <model> # Short form of --model
letta --continue # Resume global last agent (deprecated, use project-based)
# Managing tools (requires --agent flag)
letta --agent <id> --link # Attach Letta Code tools to agent, then start session
letta --agent <id> --unlink # Remove Letta Code tools from agent, then start session
letta --agent [existing-agent-id]
```
> **Note:** The `--model` flag is inconsistent when resuming sessions. We recommend using the `/model` command instead to change models in interactive mode.
## Skill learning
#### Interactive Commands
While in a session, you can use these commands:
**Agent Management:**
- `/agent` - Show current agent link
- `/resume` - Switch to a different agent (prompts with agent selector)
- `/rename` - Rename the current agent
- `/download` - Download agent file locally (exports agent configuration as JSON)
- `/profile` - List saved profiles
- `/profile save <name>` - Save current agent to a named profile
- `/profile load <name>` - Load a saved profile (switches to that agent)
- `/profile delete <name>` - Delete a saved profile
**Configuration:**
- `/model` - Switch models (prompts with model selector)
- `/toolset` - Switch toolsets (codex/default/gemini)
- `/system` - Switch system prompt (change agent behavior preset)
- `/stream` - Toggle token streaming on/off
**Tools & Memory:**
- `/link` - Attach Letta Code tools to current agent (enables Read, Write, Edit, Bash, etc.)
- `/unlink` - Remove Letta Code tools from current agent
- `/init` - Initialize agent memory for this project (guides agent to organize memory blocks based on current context)
**Skills:**
- `/skill` - Enter skill creation mode (optionally: `/skill <description>`)
**Background Processes:**
- `/bashes` - Show background shell processes (displays shells started with `run_in_background=true`)
**Session Management:**
- `/clear` - Clear conversation history
- `/exit` - Exit and show session stats
- `/logout` - Clear credentials and exit
#### Background Shell Processes
When running long-running commands (like dev servers, test watchers, or builds), the agent can use `run_in_background=true` with the Bash tool. Use `/bashes` to view all background processes:
Skills are reusable modules that teach your agent new capabilities. They’re automatically discovered from your project’s `.skills` directory and loaded into the agent’s memory at session start.'
The easiest way to create a skill is using the interactive skill creation mode:
```bash
/bashes # Shows running background shells with their IDs and commands
> /skill
```
The agent can monitor background process output using the `BashOutput` tool and terminate them with `KillBash`.
#### Memory Initialization
The `/init` command helps the agent organize its memory blocks based on your project context:
```bash
/init # Guides agent to analyze project and structure its memory
```
This is useful when:
- Starting fresh in a new project
- Reorganizing an existing agent's memory structure
- After sharing project documentation (like AGENTS.md or README)
The agent will analyze available context and create/update memory blocks like:
- **`project`** - Build commands, architecture, conventions
- **`human`** - Your coding preferences and communication style
- **`ticket`/`context`** - Current task or debugging context
See [Memory Configuration](#memory-configuration) for more details on memory blocks.
#### Skill Creation
The `/skill` command enters an interactive mode for creating new skills:
```bash
/skill # Enter skill creation mode
/skill "Python testing helper" # Start with a description
```
Skills are modular packages that extend Letta Code with specialized knowledge or workflows. The agent will guide you through:
1. Defining the skill's purpose and scope
2. Creating the skill structure (SKILL.md + optional resources)
3. Writing effective instructions and bundled scripts
4. Validating and packaging the skill
Created skills are saved to your `.skills` directory and automatically discovered on next session.
#### Managing Letta Code Tools
Letta Code provides tools like `Bash`, `Read`, `Write`, `Edit`, `Grep`, `Glob`, and more. You can attach or remove these tools from any agent:
**Via CLI flags** (before starting session):
```bash
letta --agent <id> --link # Attach Letta Code tools
letta --agent <id> --unlink # Remove Letta Code tools
```
**Via interactive commands** (during session):
```bash
/link # Attach Letta Code tools to current agent
/unlink # Remove Letta Code tools from current agent
```
When you attach tools with `/link` or `--link`, they are added to the agent with approval rules enabled (human-in-the-loop). This means the agent can use these tools, but you'll be prompted to approve each tool call. Use permission modes to control approval behavior (see Permissions section below).
### Toolsets
Letta Code includes different toolsets optimized for different model providers:
1. **Default Toolset** (Anthropic-optimized, best for Claude models)
2. **Codex Toolset** (OpenAI-optimized, best for GPT models)
3. **Gemini Toolset** (Google-optimized, best for Gemini models)
**Automatic Selection:**
When you specify a model, Letta Code automatically selects the appropriate toolset:
```bash
letta --model haiku # Loads default toolset
letta --model gpt-5-codex # Loads codex toolset
letta --model gemini-3-pro # Loads gemini toolset
```
**Manual Override:**
You can force a specific toolset regardless of model:
```bash
# CLI flag (at startup)
letta --model haiku --toolset codex # Use Codex-style tools with Claude Haiku
letta --model gpt-5-codex --toolset gemini # Use Gemini-style tools with GPT-5-Codex
letta --toolset gemini # Use Gemini tools with default model
# Interactive command (during session)
/toolset # Opens toolset selector
```
The `/model` command automatically switches toolsets when you change models. Use `/toolset` if you want to manually override the automatic selection.
### Headless Mode
```bash
letta -p "Run bun lint and correct errors" # Auto-resumes project agent
letta -p "Pick up where you left off" # Same - auto-resumes by default
letta -p "Start fresh" --new # Create new agent with new memory blocks
letta -p "Run all the test" --allowedTools "Bash" # Control tool permissions
letta -p "Just read the code" --disallowedTools "Bash" # Control tool permissions
letta -p "Explain this code" -m gpt-4o # Use specific model
# Pipe input from stdin
echo "Explain this code" | letta -p
cat file.txt | letta -p
gh pr diff 123 | letta -p --yolo
# Output formats
letta -p "Analyze this codebase" --output-format json # Structured JSON at end
letta -p "Analyze this codebase" --output-format stream-json # JSONL stream (one event per line)
```
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.
```bash
letta -p "Run all tests" --tools "Bash,Read" # Only load specific tools
letta -p "Just analyze the code" --tools "" # No tools (analysis only)
```
Use `--output-format json` to get structured output with metadata:
```bash
# regular text output
$ letta -p "hi there"
Hi! How can I help you today?
# structured output (single JSON object at end)
$ letta -p "hi there" --output-format json
{
"type": "result",
"subtype": "success",
"is_error": false,
"duration_ms": 5454,
"duration_api_ms": 2098,
"num_turns": 1,
"result": "Hi! How can I help you today?",
"agent_id": "agent-8ab431ca-63e0-4ca1-ba83-b64d66d95a0f",
"usage": {
"prompt_tokens": 294,
"completion_tokens": 97,
"total_tokens": 391
}
}
```
Use `--output-format stream-json` to get streaming outputs, in addition to a final JSON response.
This is useful if you need to have data flowing to prevent automatic timeouts:
```bash
# streaming JSON output (JSONL - one event per line, token-level streaming)
# Note: Messages are streamed at the token level - each chunk has the same otid and incrementing seqId.
$ letta -p "hi there" --output-format stream-json
{"type":"init","agent_id":"agent-...","model":"claude-sonnet-4-5-20250929","tools":[...]}
{"type":"message","messageType":"reasoning_message","reasoning":"The user is asking","otid":"...","seqId":1}
{"type":"message","messageType":"reasoning_message","reasoning":" me to say hello","otid":"...","seqId":2}
{"type":"message","messageType":"reasoning_message","reasoning":". This is a simple","otid":"...","seqId":3}
{"type":"message","messageType":"reasoning_message","reasoning":" greeting.","otid":"...","seqId":4}
{"type":"message","messageType":"assistant_message","content":"Hi! How can I help you today?","otid":"...","seqId":5}
{"type":"message","messageType":"stop_reason","stopReason":"end_turn"}
{"type":"message","messageType":"usage_statistics","promptTokens":294,"completionTokens":97,"totalTokens":391}
{"type":"result","subtype":"success","result":"Hi! How can I help you today?","agent_id":"agent-...","usage":{...}}
```
### Permissions
**Tool selection** (controls which tools are loaded):
```bash
--tools "Bash,Read,Write" # Only load these tools
--tools "" # No tools (conversation only)
```
**Permission overrides** (controls tool access, applies to loaded tools):
```bash
--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`:
```json
{
"permissions": {
"allow": ["Bash(npm run lint)", "Read(src/**)"],
"deny": ["Bash(rm -rf:*)", "Read(.env)"]
}
}
```
## Updates
Letta Code automatically checks for updates on startup and installs them in the background.
### Auto updates
* **Update checks**: Performed on startup
* **Update process**: Downloads and installs automatically in the background
* **Applying updates**: Updates take effect the next time you start Letta Code
**Disable auto-updates:**
Set the `DISABLE_AUTOUPDATER` environment variable in your shell:
```bash
export DISABLE_AUTOUPDATER=1
```
### Update manually
```bash
letta update
```
Read the docs to learn more about [skills and skill learning](https://docs.letta.com/letta-code/skills).
## Self-hosting
@@ -449,7 +94,7 @@ bun link
# 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.
Whenever you change source files, rerun `bun run build` before using the linked `letta` binary so it picks up your edits.
---