@letta-ai/letta-code 0.1.19 → 0.4.2

package/README.md

@@ -2,13 +2,13 @@
 
 A self-improving, stateful coding agent that can learn from experience and improve with use.
 
-https://github.com/user-attachments/assets/5561a3ff-afd9-42a9-8601-55d245946394
+<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 [Agents 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 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.
 
@@ -76,6 +76,75 @@ Letta Code uses a hierarchical memory system:
 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:
+
+```bash
+mkdir -p .skills/data-analysis
+```
+
+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:
+
+```bash
+letta --skills /path/to/custom/skills
+letta -p "Use the custom skills" --skills ~/my-skills
+```
+
 ## Usage
 
 ### Interactive Mode
@@ -83,13 +152,79 @@ Join our [Discord](https://discord.gg/letta) to share feedback on persistence pa
 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-sonnet-4.5, gpt-4o)
+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
 ```
 
 > **Note:** The `--model` flag is inconsistent when resuming sessions. We recommend using the `/model` command instead to change models in interactive mode.
 
+#### Interactive Commands
+
+While in a session, you can use these commands:
+- `/agent` - Show current agent link
+- `/model` - Switch models
+- `/toolset` - Switch toolsets (codex/default)
+- `/rename` - Rename the current agent
+- `/stream` - Toggle token streaming on/off
+- `/link` - Attach Letta Code tools to current agent (enables Read, Write, Edit, Bash, etc.)
+- `/unlink` - Remove Letta Code tools from current agent
+- `/clear` - Clear conversation history
+- `/exit` - Exit and show session stats
+- `/logout` - Clear credentials and exit
+
+#### 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