### Example Onboarding Message Source: https://docs.letta.com/letta-code/skills Provides a template for effective first-time user messages, including a concise product description, a single clear next action, and a help option. ```text "[Product] helps you [value prop]. Click 'New Project' to begin, or visit our docs if you need help." ``` -------------------------------- ### Run Letta Code Source: https://docs.letta.com/letta-code/selfhosting This command starts the Letta Code application. It assumes that the LETTA_BASE_URL environment variable has already been set to point to a self-hosted Letta server. ```bash letta ``` -------------------------------- ### Using Custom Subagents (Natural Language Examples) Source: https://docs.letta.com/letta-code/subagents These examples demonstrate how to invoke a custom subagent, 'security-reviewer', using natural language commands. They illustrate specifying the agent and the target of its review. ```text > Use the security-reviewer agent to review the authentication module > Run security-reviewer on the entire src/api directory ``` -------------------------------- ### Run Letta Server with Docker Source: https://docs.letta.com/letta-code/selfhosting This command starts a Letta server using Docker. It mounts a local directory for PostgreSQL data persistence, exposes port 8283, and sets the OpenAI API key as an environment variable. Ensure you replace 'your_openai_api_key' with your actual key. ```bash docker run \ -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \ -p 8283:8283 \ -e OPENAI_API_KEY="your_openai_api_key" \ letta/letta:latest ``` -------------------------------- ### Automated Tasks and Scripting with Letta Code Headless Mode Source: https://docs.letta.com/letta-code/headless Provides examples of using Letta Code in headless mode for automated tasks and structured output. This includes running linters with `--yolo`, parsing JSON output with `jq` for programmatic access, restricting agents to read-only operations using `--tools`, and scheduling tasks with cron jobs. ```bash letta -p "Run the linter and fix any errors" --yolo ``` ```bash result=$(letta -p "What is the main entry point of this project?" --output-format json) echo $result | jq '.result' ``` ```bash letta -p "Review this codebase for potential security issues" --tools "Read,Glob,Grep" ``` ```bash 0 9 * * * cd /path/to/project && letta -p "Review recent changes and summarize any issues" --tools "Read,Glob,Grep" --output-format json >> /var/log/letta-review.log 2>&1 ``` ```bash 0 10 * * 1 cd /path/to/project && letta -p "Check for outdated dependencies and security vulnerabilities" --yolo >> /var/log/letta-deps.log 2>&1 ``` -------------------------------- ### Create New Letta Code Agent Source: https://docs.letta.com/letta-code/memory This command explicitly starts a new Letta Code agent session, bypassing the automatic resumption of a previous agent. This is useful when you want to start fresh or create a dedicated agent for a specific task or context. ```bash letta --new ``` -------------------------------- ### Parallel Subagent Execution Source: https://docs.letta.com/letta-code/subagents This example illustrates how to launch multiple subagents concurrently to handle independent tasks in parallel. This can significantly speed up complex workflows by distributing the workload across several agents. ```text > Spawn two explore agents: one to search the frontend for React components, and another to find all API routes in the backend ``` -------------------------------- ### Manually Update Letta Code Source: https://docs.letta.com/letta-code/configuration Perform a manual update of Letta Code using the command-line interface. This command fetches and installs the latest version of the application. ```shell letta update ``` -------------------------------- ### Permission Control: YOLO, Tool Restriction, and Modes in Letta Code Source: https://docs.letta.com/letta-code/headless Details various permission control mechanisms for Letta Code's headless mode. It includes the `--yolo` flag for bypassing all permission prompts (use with caution), the `--tools` flag to restrict available tools, and examples of different `--permission-mode` settings like `acceptEdits` and `plan`. ```bash letta -p "Refactor this file" --yolo ``` ```bash letta -p "Analyze this codebase" --tools "Read,Glob,Grep" ``` ```bash letta -p "What do you think about this approach?" --tools "" ``` ```bash letta -p "Fix the type errors" --permission-mode acceptEdits ``` ```bash letta -p "Review this PR" --permission-mode plan ``` -------------------------------- ### Explicit Subagent Request Prompting Source: https://docs.letta.com/letta-code/subagents This example shows how to explicitly request the use of a specific subagent type through natural language prompting. The agent then interprets this prompt and delegates the task to the appropriate subagent. ```text > Use the explore subagent to find all database connection code ``` -------------------------------- ### Subagent Definition Example (YAML Frontmatter) Source: https://docs.letta.com/letta-code/subagents This snippet shows the YAML frontmatter structure for defining a subagent. It includes common fields like name, description, tools, model, and memoryBlocks, which configure the subagent's behavior and capabilities. ```yaml --- name: security-reviewer description: Reviews code for security vulnerabilities and suggests fixes tools: Glob, Grep, Read model: sonnet-4.5 memoryBlocks: human, persona --- ``` -------------------------------- ### Configure Letta Code Base URL Source: https://docs.letta.com/letta-code/selfhosting Set the LETTA_BASE_URL environment variable to configure Letta Code to connect to your self-hosted Letta server. This example points to a local server running on port 8283. You can set this variable persistently or inline. ```bash export LETTA_BASE_URL="http://localhost:8283" ``` ```bash LETTA_BASE_URL="http://localhost:8283" letta ``` -------------------------------- ### Authentication Script Usage Source: https://docs.letta.com/letta-code/skills Demonstrates how to use the authentication helper script to manage tokens. Specifically, it shows the command to refresh the token. ```bash scripts/auth.py refresh ``` -------------------------------- ### Show Session Usage Statistics Source: https://docs.letta.com/letta-code/commands The `/usage` command displays detailed session statistics, including total duration, session steps, token usage (input/output), available credits, and plan information. It also provides a link to the Letta app for managing usage and upgrading plans. ```text ● /usage ⎿ Total duration (API): 43.6s Total duration (wall): 1m 14s Session usage: 4 steps, 80,574 input, 1,358 output Available credits: ◎34,634 ($34.63) Plan: [pro] Monthly credits: ◎19,930 ($19.93) Purchased credits: ◎14,704 ($14.70) https://app.letta.com/settings/organization/usage ``` -------------------------------- ### Load Skills with Skill Tool Source: https://docs.letta.com/letta-code/skills Demonstrates how to load one or multiple skills into the agent's active memory using the 'skill' tool with the 'load' command. This makes the skill's content available for the agent to use. ```python skill(command='load', skills=['api-client']) skill(command='load', skills=['testing', 'deployment']) # batch load ``` -------------------------------- ### Initialize Project Memory Source: https://docs.letta.com/letta-code/memory This command initializes or re-initializes the agent's memory for the current project. It prompts the user for details like research depth, identity, related repositories, workflow preferences, and communication style to help the agent understand the codebase and user needs. ```bash > /init ``` -------------------------------- ### Output Formats: Text, JSON, and Stream JSON with Letta Code Source: https://docs.letta.com/letta-code/headless Explains and demonstrates the three output formats available in Letta Code's headless mode: default plain text, structured JSON with metadata, and line-delimited JSON events for real-time streaming to prevent timeouts and show incremental progress. Each format serves different use cases for scripting and automation. ```bash letta -p "What files are in this directory?" ``` ```bash letta -p "List all TypeScript files" --output-format json ``` ```json { "type": "result", "result": "Found 15 TypeScript files...", "agent_id": "agent-abc123", "usage": { "prompt_tokens": 1250, "completion_tokens": 89 } } ``` ```bash letta -p "Explain this codebase" --output-format stream-json ``` ```json {"type":"init","agent_id":"agent-...","model":"claude-sonnet-4-5","tools":[...]} {"type":"message","messageType":"reasoning_message","reasoning":"The user is asking...","otid":"...","seqId":1} {"type":"message","messageType":"assistant_message","content":"Here's an overview...","otid":"...","seqId":5} {"type":"message","messageType":"stop_reason","stopReason":"end_turn"} {"type":"message","messageType":"usage_statistics","promptTokens":294,"completionTokens":97} {"type":"result","subtype":"success","result":"Here's an overview...","agent_id":"agent-...","usage":{...}} ``` -------------------------------- ### Basic Usage: Prompting and Piping in Letta Code Source: https://docs.letta.com/letta-code/headless Demonstrates how to run Letta Code non-interactively by passing a prompt directly using the `-p` flag or by piping input. This is fundamental for scripting and automation. ```bash letta -p "Look around this repo and write a README.md documenting it" ``` ```bash echo "Explain this error" | letta -p ``` -------------------------------- ### Configure Custom Skills Directory with Letta CLI Source: https://docs.letta.com/letta-code/skills This command demonstrates how to specify a custom directory for Letta Code skills using the CLI. Ensure the provided path points to a valid directory containing your skills. ```bash letta --skills ~/my-global-skills ``` -------------------------------- ### Refresh Skills List with Skill Tool Source: https://docs.letta.com/letta-code/skills Shows how to update the agent's list of available skills by rescanning the .skills directory using the 'skill' tool with the 'refresh' command. This is necessary after adding new skills. ```python skill(command='refresh') ``` -------------------------------- ### Agent and Model Selection in Letta Code Headless Mode Source: https://docs.letta.com/letta-code/headless Covers how to manage agent and model selection when running Letta Code in headless mode. It shows how to use `--new` or `--agent ` to control agent persistence and memory, and flags like `--model`, `-m` to specify the desired LLM for the task. ```bash letta -p "..." --new ``` ```bash letta -p "..." --agent ``` ```bash letta -p "..." --model sonnet-4.5 ``` ```bash letta -p "..." -m gpt-5-codex ``` ```bash letta -p "..." -m haiku ``` -------------------------------- ### Pin Agent for Quick Access Source: https://docs.letta.com/letta-code/memory This command pins the current or a specified agent for quick access across different projects. Pinning allows you to easily switch to frequently used agents without needing to remember their IDs. ```bash > /pin ``` -------------------------------- ### Configure Letta Environment Variables Source: https://docs.letta.com/letta-code/commands This snippet shows how to set environment variables for the Letta project. These variables are used for API key authentication, specifying the base URL for self-hosted servers, enabling debug logging, and controlling telemetry and auto-updates. It demonstrates setting `LETTA_API_KEY` and `LETTA_BASE_URL` using export commands, typically added to shell profiles or .env files. ```shell export LETTA_API_KEY="your-key-here" export LETTA_BASE_URL="http://localhost:8283" ``` -------------------------------- ### Best Practices Source: https://docs.letta.com/letta-code/permissions Recommendations for effectively using Letta Code's permission system. ```APIDOC ## Best Practices 1. **Start with defaults**: Use the default human-in-the-loop mode for safety while learning. 2. **Pre-approve common commands**: Add your frequent linting or testing scripts to the allow list for efficiency. 3. **Use plan mode for review**: Employ `plan` mode for code analysis without the risk of unintended modifications. 4. **Reserve `--yolo` for trusted contexts**: Use the `bypassPermissions` mode (`--yolo`) cautiously, primarily in automated pipelines or sandboxed environments. ``` -------------------------------- ### Launch Subagent with Task Tool Source: https://docs.letta.com/letta-code/subagents This code snippet demonstrates how to launch a subagent using the Task tool. It specifies the subagent type, a description, and a prompt for the subagent to execute. The subagent runs autonomously and returns a report to the main agent. ```python Task( subagent_type="explore", description="Find auth code", prompt="Search for all authentication-related files in src/. List paths and summarize the approach." ) ``` -------------------------------- ### Using Permission Modes with Letta CLI Source: https://docs.letta.com/letta-code/permissions Demonstrates how to use the Letta CLI to specify different permission modes for agent tasks. These modes control the level of approval required for tool execution, ranging from full manual approval to automatic execution. ```bash letta -p "Fix the type errors" --permission-mode acceptEdits ``` ```bash letta -p "Review this codebase" --permission-mode plan ``` ```bash letta -p "Run the full test suite and fix failures" --yolo ``` -------------------------------- ### Restricting Available Tools with Letta CLI Source: https://docs.letta.com/letta-code/permissions Demonstrates how to use the Letta CLI to restrict the set of tools available to the agent. This is different from permissions, as it removes tools from the agent's context entirely, rather than just controlling their execution. ```bash letta -p "Analyze this code" --tools "Read,Glob,Grep" ``` ```bash letta -p "Explain this concept" --tools "" ``` -------------------------------- ### Allowing and Disallowing Specific Tools with Letta CLI Source: https://docs.letta.com/letta-code/permissions Shows how to use the Letta CLI to specify which tools are allowed or disallowed for agent execution. This provides fine-grained control over agent capabilities, enabling or restricting specific commands or patterns. ```bash letta --allowedTools "Bash(npm run lint),Bash(npm run test)" ``` ```bash letta --disallowedTools "Bash(rm -rf:*)" ``` -------------------------------- ### Resume from Pinned Agents List Source: https://docs.letta.com/letta-code/memory This command allows you to resume an agent directly from the list of pinned agents. It provides a streamlined way to switch between your most frequently used agents without needing to remember their IDs. ```bash > /resume ``` -------------------------------- ### View Available Subagents Command Source: https://docs.letta.com/letta-code/subagents This command allows you to view a list of all available subagents, including both built-in and any custom subagents that have been configured for the project. This is useful for understanding the capabilities of your agent environment. ```text > /subagents ``` -------------------------------- ### List Pinned Agents Source: https://docs.letta.com/letta-code/memory This command lists all locally pinned agents, allowing you to see which agents are readily available for quick access and resumption. This helps in managing your agent workflow and selecting the appropriate agent for your current task. ```bash > /pin -l ``` -------------------------------- ### View and Manage Pinned Agents Source: https://docs.letta.com/letta-code/memory This command displays a list of all pinned agents, providing an interface to manage them. From this view, you can switch to an agent, pin/unpin it locally, or unpin it from all locations. ```bash > /pinned ``` -------------------------------- ### View memory blocks with /memory Source: https://docs.letta.com/letta-code/memory The `/memory` command displays all memory blocks associated with an agent. It offers a list view with previews and a detail view for full content inspection. Navigation within the viewer is done using keyboard controls or by clicking a provided link to the Letta ADE. ```shell > /memory ``` -------------------------------- ### Set API Key for Letta Code Authentication Source: https://docs.letta.com/letta-code/configuration Configure Letta Code by setting an API key directly. This is an alternative to the default OAuth authentication. The API key should be exported as an environment variable. ```shell export LETTA_API_KEY=your-api-key ``` -------------------------------- ### Unload Skills with Skill Tool Source: https://docs.letta.com/letta-code/skills Illustrates how to remove skills from the agent's active memory using the 'skill' tool with the 'unload' command. This frees up context tokens by making the skill's content unavailable. ```python skill(command='unload', skills=['api-client']) skill(command='unload', skills=['testing', 'deployment']) # batch unload ``` -------------------------------- ### Manually remember information with /remember Source: https://docs.letta.com/letta-code/memory The `/remember` command allows agents to explicitly store information. It can be used with specific text to remember or without arguments to reflect on recent interactions and update memory. The prompt used for this command is also accessible. ```shell > /remember Always use pnpm instead of npm in this project ``` ```shell > /remember ``` -------------------------------- ### Persistent Permissions Configuration in .letta/settings.json Source: https://docs.letta.com/letta-code/permissions Illustrates the structure of the `.letta/settings.json` file for defining persistent permission rules. This allows setting default allow and deny lists for tools and patterns that apply across all agent sessions. ```json { "permissions": { "allow": [ "Bash(pnpm lint)", "Bash(pnpm test)", "Read(src/**)" ], "deny": [ "Bash(rm -rf:*)", "Bash(git push --force:*)", "Read(.env)" ] } } ``` -------------------------------- ### Client-side Tool Execution in Letta Code Source: https://docs.letta.com/letta-code/how-it-works Demonstrates how Letta Code handles tool execution locally. An agent requests a tool, Letta Code prompts for approval, executes the tool, and sends the result back to the agent. This process involves creating messages, approving tool calls, and handling results. ```typescript const response = await client.agents.messages.create(agentId, { messages: [{ role: "user", content: userInput }] }); for (const msg of response.messages) { if (msg.message_type === "approval_request_message") { // Execute the tool locally const result = await executeToolLocally(msg.tool_call); // Send the result back to the agent await client.agents.messages.create(agentId, { messages: [{ type: "approval", approvals: [{ type: "tool", tool_call_id: msg.tool_call.tool_call_id, tool_return: result, status: "success", }], }], }); } } ``` -------------------------------- ### Project-Specific Letta Code Settings Source: https://docs.letta.com/letta-code/configuration Configure personal, gitignored settings for a specific project using the .letta/settings.local.json file. This is typically used to store the ID of the last used agent for auto-resume functionality. ```json { "lastAgent": "agent-id-..." } ``` -------------------------------- ### Streaming Responses in Letta Code Source: https://docs.letta.com/letta-code/how-it-works Illustrates how Letta Code uses the SDK's streaming API to display reasoning, messages, and tool calls in real-time. It iterates over a stream of chunks, processing and writing them to standard output. ```typescript const stream = await client.agents.messages.stream(agentId, { messages: [{ role: "user", content: userInput }], stream_tokens: true, }); for await (const chunk of stream) { if (chunk.message_type === "reasoning_message") { process.stdout.write(chunk.reasoning); } else if (chunk.message_type === "assistant_message") { process.stdout.write(chunk.content); } } ``` -------------------------------- ### Unpin All Pinned Agents Source: https://docs.letta.com/letta-code/memory This command unpins all locally pinned agents, effectively clearing your quick-access list. This can be useful for resetting your pinned agents or when you want to re-evaluate which agents to pin. ```bash > /unpin -l ``` -------------------------------- ### Custom Subagent File Structure Source: https://docs.letta.com/letta-code/subagents This shows the file structure for creating custom subagents. Custom subagents are defined in Markdown files with YAML frontmatter and placed within the .letta/agents/ directory. Global subagents can be placed in ~/.letta/agents/. ```text .letta/ └── agents/ └── my-subagent.md ``` -------------------------------- ### Global Letta Code Settings Source: https://docs.letta.com/letta-code/configuration Define global settings for Letta Code that apply to all projects. This JSON file, located at ~/.letta/settings.json, can configure token streaming and shared block IDs for personas. ```json { "tokenStreaming": true, "globalSharedBlockIds": { "persona": "block-id-...", "human": "block-id-..." } } ``` -------------------------------- ### Unpin Agent Source: https://docs.letta.com/letta-code/memory This command unpins a specific agent, removing it from the list of quick-access agents. Unpinning is useful for managing your pinned agents and removing those that are no longer frequently used. ```bash > /unpin ``` -------------------------------- ### Add Letta Code Settings to .gitignore Source: https://docs.letta.com/letta-code/configuration Configure your .gitignore file to exclude personal Letta Code settings from version control. This prevents sensitive information like agent IDs from being committed. ```gitignore # Letta Code personal settings .letta/settings.local.json ``` -------------------------------- ### Permission Modes Source: https://docs.letta.com/letta-code/permissions Control the level of approval required for tool execution. Modes range from requiring approval for every tool call to automatically allowing all actions. ```APIDOC ## Permission Modes ### Description Adjust the approval process for tool calls. ### Modes | Mode | Behavior | |---------------------|-----------------------------------------------| | `default` | Prompt for approval on every tool call | | `acceptEdits` | Auto-allow file edits, prompt for others | | `plan` | Read-only mode, no file modifications | | `bypassPermissions` | Auto-allow everything (use with caution) | ### Usage Examples ```bash # Use 'acceptEdits' mode letta -p "Fix the type errors" --permission-mode acceptEdits # Use 'plan' mode for read-only analysis letta -p "Review this codebase" --permission-mode plan # Use 'bypassPermissions' mode (shorthand --yolo) letta -p "Run the full test suite and fix failures" --yolo ``` **Note:** `--yolo` is a shorthand for `--permission-mode bypassPermissions`. ``` -------------------------------- ### Rename Agent During Pinning Source: https://docs.letta.com/letta-code/memory This command allows you to pin an agent and simultaneously assign it a custom alias or name. Renaming during pinning makes it easier to identify and recall specific agents based on their project or task context. ```bash > /pin MyAgent ``` -------------------------------- ### Shared Project Letta Code Settings Source: https://docs.letta.com/letta-code/configuration Define shared project settings in .letta/settings.json that can be committed to version control to share with a team. This configuration allows specifying permissions for auto-allowed commands. ```json { "permissions": { "allow": ["Bash(pnpm lint)", "Bash(pnpm test)"] } } ``` -------------------------------- ### Resume Specific Letta Code Agent Source: https://docs.letta.com/letta-code/memory This command allows you to resume a specific Letta Code agent session using its unique agent ID. This is useful for switching to a different agent than the one automatically resumed or for accessing a particular agent across different projects. ```bash letta --agent ``` -------------------------------- ### Restricting Available Tools Source: https://docs.letta.com/letta-code/permissions Control the set of tools that are loaded and available to the agent, independently of permissions. ```APIDOC ## Restricting Available Tools ### Description Control which tools are loaded into the agent's context using the `--tools` flag. ### Usage Examples ```bash # Load only Read, Glob, and Grep tools letta -p "Analyze this code" --tools "Read,Glob,Grep" # Load no tools letta -p "Explain this concept" --tools "" ``` **Note:** This removes tools entirely from the agent's context, not just permission-gating them. ``` -------------------------------- ### Fine-grained Control Source: https://docs.letta.com/letta-code/permissions Specify which tools or patterns of tool invocations are allowed or denied. ```APIDOC ## Fine-grained Control ### Description Gain granular control over tool permissions using allow/deny patterns and persistent rules. ### Allow/Deny Specific Patterns Control permissions for specific tool invocations using command-line flags. **Usage Examples:** ```bash # Allow only specific lint and test commands letta --allowedTools "Bash(npm run lint),Bash(npm run test)" # Disallow a potentially dangerous command letta --disallowedTools "Bash(rm -rf:*)" ``` ### Persistent Rules Set rules in `.letta/settings.json` that apply across sessions. **File: `.letta/settings.json`** ```json { "permissions": { "allow": [ "Bash(pnpm lint)", "Bash(pnpm test)", "Read(src/**)" ], "deny": [ "Bash(rm -rf:*)", "Bash(git push --force:*)", "Read(.env)" ] } } ``` ### Pattern Syntax | Pattern | Matches | |-------------------|-----------------------------------| | `ToolName` | All uses of a tool | | `ToolName(pattern)` | Specific arguments | | `**` | Wildcard for paths | | `:*` | Wildcard for command arguments | ``` -------------------------------- ### Background Mode Streaming in Letta Code Source: https://docs.letta.com/letta-code/how-it-works Details how Letta Code employs background mode streaming for long-running agents, decoupling execution from the client connection. This enables resumable streams and crash recovery by persisting the stream server-side. It shows how to enable background mode and resume disconnected streams using `run_id` and `seq_id`. ```typescript // Background mode persists the stream server-side const stream = await client.agents.messages.stream(agentId, { messages: [{ role: "user", content: userInput }], stream_tokens: true, background: true, // Enable background mode }); // Each chunk includes run_id and seq_id for resumption let runId, lastSeqId; for await (const chunk of stream) { if (chunk.run_id && chunk.seq_id) { runId = chunk.run_id; lastSeqId = chunk.seq_id; } // Process chunk... } // If disconnected, resume from last position for await (const chunk of client.runs.stream(runId, { starting_after: lastSeqId, })) { // Continue processing... } ``` -------------------------------- ### Override Default Model for Subagent Source: https://docs.letta.com/letta-code/subagents This demonstrates how to override the default language model for a subagent. By specifying a different model (e.g., Sonnet, Opus, Haiku) in the prompt, you can control the reasoning capabilities and cost associated with the subagent's execution. ```text > Use a plan agent with Sonnet to design the migration > Spawn an explore agent with Opus for a thorough codebase analysis > Use a general-purpose agent with Haiku for this quick fix ``` -------------------------------- ### Enable sleeptime memory agent Source: https://docs.letta.com/letta-code/memory Sleeptime agents offload memory operations to an asynchronous agent, passively updating memories while the primary agent works. This can be enabled when creating a new agent or set as a default in `~/.letta/settings.json`. ```shell letta --new --sleeptime ``` ```json { "enableSleeptime": true } ``` -------------------------------- ### Disable Letta Code Auto-Updates Source: https://docs.letta.com/letta-code/configuration Prevent Letta Code from automatically updating by setting the DISABLE_AUTOUPDATER environment variable to 1. This ensures that updates are not applied in the background. ```shell export DISABLE_AUTOUPDATER=1 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.