From f4480f6f5ed003782c6048a9a5b6ddb797920417 Mon Sep 17 00:00:00 2001 From: Charles Packer Date: Sun, 14 Dec 2025 15:08:54 -0800 Subject: [PATCH] Update README.md --- README.md | 409 ++++-------------------------------------------------- 1 file changed, 27 insertions(+), 382 deletions(-) diff --git a/README.md b/README.md index 28f091c..274e54c 100644 --- a/README.md +++ b/README.md @@ -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).** letta-code ---- - -## 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 # 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 # Use specific agent ID -letta --model # Specify model (e.g., claude-opus-4.5, claude-sonnet-4.5, gpt-4o) -letta -m # Short form of --model -letta --continue # Resume global last agent (deprecated, use project-based) - -# Managing tools (requires --agent flag) -letta --agent --link # Attach Letta Code tools to agent, then start session -letta --agent --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 ` - Save current agent to a named profile -- `/profile load ` - Load a saved profile (switches to that agent) -- `/profile delete ` - 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 `) - -**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 --link # Attach Letta Code tools -letta --agent --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. ---