@letta-ai/letta-code 0.25.11 → 0.26.0

package/README.md

@@ -15,33 +15,64 @@ Letta Code is a frontier coding agent and can also be used as a long-lived perso
 ![](https://github.com/letta-ai/letta-code/blob/main/assets/letta-code-demo.gif)
 
 ## Feature Overview
+
 > [!TIP]
 > Letta Code agents are designed to be self-configuring. If you want to configure something (e.g. skills, behavior, hooks, permissions), try asking your agent to do it for you.
 
 | Feature | Description |
 |---|---|
-| [Self-improvement & Learning](https://docs.letta.com/letta-code/self-improvement) | Agents programmatically rewrite their context to improve and adapt over time, including system prompt learning (through [memory blocks](https://www.letta.com/blog/memory-blocks)) and [skill learning](https://www.letta.com/blog/skill-learning). Configure periodic dreaming with `/sleeptime`, audit memory quality with `/doctor`, and view memory with `/palace`   |
+| [Self-improvement & Learning](https://docs.letta.com/letta-code/self-improvement) | Agents programmatically rewrite their context to improve and adapt over time, including system prompt learning (through [memory blocks](https://www.letta.com/blog/memory-blocks)) and [skill learning](https://www.letta.com/blog/skill-learning). Configure periodic dreaming with `/sleeptime`, audit memory quality with `/doctor`, and view memory with `/palace` |
 | [Message search](https://docs.letta.com/letta-code/conversation-search) | Search across all messages and agents with `/search`. Agent can also search their own conversations or the conversations of other agents |
 | [MemFS](https://docs.letta.com/letta-code/memfs) | All context (including memory blocks) is tracked via git. Sync context to a custom GitHub repository by setting `/memory-repository set git@github.com:...` |
 | [Skills](https://docs.letta.com/letta-code/skills) | Loads global skills (`~/.letta`), project-scoped skills (`.agents/skills`), and agent-scoped skills (stored in MemFS). View skills with `/skills` and create with `/skill-creator` |
-| [Subagents & Multi-agent](https://docs.letta.com/letta-code/subagents) | Call built-in subagents (general-purpose, forked, recall, history-analyzer) async or sync. Agents can call any other agent (including themselves) as subagents  |
+| [Subagents & Multi-agent](https://docs.letta.com/letta-code/subagents) | Call built-in subagents (general-purpose, forked, recall, history-analyzer) async or sync. Agents can call any other agent (including themselves) as subagents |
 | [Messaging Integrations](https://docs.letta.com/letta-code/channels) | Chat with the same agent from Slack, Telegram, your browser (chat.letta.com) including mobile, and through [custom channels](https://github.com/letta-ai/skills/blob/main/letta/creating-letta-code-channels/SKILL.md) |
 | [Hooks](https://docs.letta.com/letta-code/hooks) | Run custom scripts at key points of agent execution to automate workflows |
 | [Permissions](https://docs.letta.com/letta-code/permissions) | Set permission modes and customize what actions are auto-approved or auto-denied |
 | [Crons & Schedules](https://docs.letta.com/letta-code/scheduling) | Configure heartbeats and crons, and let agents work across time with self-managed schedules |
-| [Remote & Multi-Env](https://docs.letta.com/letta-code/client-server-architecture) | Agents work across multiple environments. Make any machine available as a remote environment by running `letta server --env-name "..."`|
-| [Secrets](https://docs.letta.com/letta-code/secrets) | Make secrets available as environment variables (across machines) while obfuscating their values from context |
+| [Remote & Multi-Env](https://docs.letta.com/letta-code/client-server-architecture) (requires Constellation login) | Agents work across multiple environments. Make any machine available as a remote environment by running `letta server --env-name "..."` |
+| [Secrets](https://docs.letta.com/letta-code/secrets) (requires Constellation login) | Make secrets available as environment variables (across machines) while obfuscating their values from context |
 
 See the full list of slash commands in our [documentation](https://docs.letta.com/letta-code/slash-commands).
 
 ## Get started
+
 Install the package via [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm):
+
 ```bash
 npm install -g @letta-ai/letta-code
 ```
-Navigate to your project directory and run `letta` (see various command-line options [on the docs](https://docs.letta.com/letta-code/commands)).
 
-Run `/connect` to configure your own LLM API keys (OpenAI / ChatGPT, Anthropic, zAI coding plan, etc.), and use `/model` to swap models.
+Navigate to your project directory and run `letta` (see command-line options [in the docs](https://docs.letta.com/letta-code/commands)).
+
+On first run, choose how you want to start:
+
+* **Proceed locally** keeps agent state on this device. This is the local-first path and does not require a Constellation login.
+* **Login to Constellation** syncs agent state through Constellation so you can access the same agents from `chat.letta.com`, the desktop app, and other machines — and agents can work across multiple machines.
+
+Run `/connect` to configure your own LLM API keys (OpenAI / ChatGPT, Anthropic, Z.ai coding plan, etc.), and use `/model` to swap models.
+
+You can also download the [**desktop app**](https://docs.letta.com/letta-code/desktop-app) for macOS, Windows, and Linux. Agents created in the CLI are available via the desktop app, and vice versa.
+
+## Local mode
+
+Local mode runs an embedded stateful agent server inside Letta Code. Agents, conversations, memory, provider connections, and secrets are stored on your machine.
+
+You can enter local mode from the first-run setup menu, or explicitly with:
+
+```bash
+letta --backend local
+```
+
+Connect a provider from inside the TUI with `/connect`, or from the shell with `letta --backend local connect`:
+
+```bash
+letta --backend local connect anthropic --api-key "$ANTHROPIC_API_KEY"
+letta --backend local connect ollama
+letta --backend local connect lmstudio
+letta --backend local connect llama-cpp
+letta --backend local connect chatgpt
+```
 
 For slow local inference servers, configure a provider-level timeout when connecting. For example, LM Studio-compatible llama-server backends that need up to 10 minutes for large-context compaction can use:
 
@@ -51,46 +82,72 @@ letta --backend local connect lmstudio --base-url http://127.0.0.1:1234/v1 --tim
 
 Timeouts are stored per local provider in milliseconds; pass `--no-timeout` or `--timeout false` to disable the provider timeout.
 
-You can also download the [**desktop app**](https://docs.letta.com/letta-code/desktop-app) for MacOS, Windows, and Linux. Agents created in the CLI are available via the desktop app, and vice versa.
+Then create a local agent:
+
+```bash
+letta --backend local --new-agent --model anthropic/claude-sonnet-4-6
+```
 
-## Philosophy
-Letta Code is built around long-lived agents that persist across sessions and improve with use. Rather than working in independent sessions, each session is tied to a persisted agent that learns.
+Local backend state is stored by default in:
 
-**Claude Code / Codex / Gemini CLI** (Session-Based)
-- Sessions are independent
-- No learning between sessions
-- Context = messages in the current session + `AGENTS.md`
-- Relationship: Every conversation is like meeting a new contractor
+```text
+~/.letta/lc-local-backend
+```
 
-**Letta Code** (Agent-Based)
-- Same agent across sessions
-- Persistent memory and learning over time
-- `/clear` starts a new conversation (aka "thread" or "session"), but memory persists
-- Relationship: Like having a coworker or mentee that learns and remembers
+You can override this location for isolated experiments:
 
-## Agent Memory & Learning
-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
-> /init
+export LETTA_LOCAL_BACKEND_DIR="$PWD/.letta-local"
+letta --backend local --new-agent
 ```
 
-Over time, the agent will update its memory as it learns. To actively guide your agents memory, you can use the `/remember` command:
-```bash
-> /remember [optional instructions on what to remember]
+Local agents do not appear in the Constellation, but their memory is still a normal git repository under `~/.letta/lc-local-backend/memfs/<agent-id>/memory`.
+
+## 🌌 Constellation
+
+Agents created with Constellation can be accessed from any machine: your laptop, [GitHub Actions](https://github.com/letta-ai/letta-code-action), a sandbox, remote VM, or a Mac Mini. You can also chat with agents through [chat.letta.com](https://chat.letta.com/) or through the desktop app.
+
+```mermaid
+graph TD
+    Constellation["🌌 Constellation"]
+    Constellation --> A["💻 Your Laptop"]
+    Constellation --> B["☁️ Cloud VM"]
+    Constellation --> C["🖥️ Mac Mini"]
+    Constellation --> D["📦 Sandbox"]
 ```
-Letta Code works with skills (reusable modules that teach your agent new capabilities in a `.skills` directory), but additionally supports [skill learning](https://www.letta.com/blog/skill-learning). You can ask your agent to learn a skill from its current trajectory with the command:
+
+### Remote environments
+
+If you're interacting with an agent from desktop or chat.letta.com, you can set agents to run on any available environment. Any machine can be made into an available environment by running:
+
 ```bash
-> /skill [optional instructions on what skill to learn]
+letta server
+letta server --env-name "work-laptop"
 ```
 
-Read the docs to learn more about [skills and skill learning](https://docs.letta.com/letta-code/skills).
+See our guides for using [Railway](https://docs.letta.com/letta-code/remote#railway), [DigitalOcean](https://docs.letta.com/letta-code/remote#digitalocean), and [Fly.io](https://docs.letta.com/letta-code/remote#flyio) as remote environments.
+
+## Research
+
+Letta Code is developed by the creators of [MemGPT](https://arxiv.org/abs/2310.08560) and [sleep-time compute](https://arxiv.org/abs/2504.13171) (now called "dreaming"), and driven by our [research](https://www.letta.com/research) in AI memory and continual learning.
+
+## Other
 
 Community maintained packages are available for Arch Linux users on the [AUR](https://aur.archlinux.org/packages/letta-code):
+
 ```bash
 yay -S letta-code # release
 yay -S letta-code-git # nightly
 ```
 
+Nix users can run or install Letta Code through the repository flake:
+```bash
+nix run github:letta-ai/letta-code
+nix profile install github:letta-ai/letta-code
+```
+
+See [docs/nix.md](docs/nix.md) for Home Manager and NixOS service examples.
+
 ---
 
 Made with 💜 in San Francisco

package/dist/types/protocol.d.ts

@@ -255,7 +255,7 @@ export type QueueItemSource = "user" | "task_notification" | "cron" | "channel"
  * - message: User or system text to send to the agent
  * - task_notification: Background task completed notification
  * - approval_result: Tool approval/denial result
- * - overlay_action: Plan mode, AskUserQuestion, etc.
+ * - overlay_action: AskUserQuestion or other overlay action
  */
 export type QueueItemKind = "message" | "task_notification" | "cron_prompt" | "approval_result" | "overlay_action";
 /**
@@ -320,7 +320,7 @@ export interface QueueBatchDequeuedEvent extends MessageEnvelope {
  * Why the queue cannot dequeue right now.
  * - streaming: Agent turn is actively running/streaming (request, response, or local tool execution)
  * - pending_approvals: Waiting for HITL approval decisions
- * - overlay_open: Plan mode, AskUserQuestion, or other overlay is active
+ * - overlay_open: AskUserQuestion or other overlay is active
  * - command_running: Slash command is executing
  * - interrupt_in_progress: User interrupt (Esc) is being processed
  * - runtime_busy: Generic busy state (e.g., listen-client turn in flight)

package/docs/nix.md

@@ -0,0 +1,105 @@
+# Nix and NixOS installation
+
+Letta Code ships a flake for Nix users who want a native install path instead of a global npm install.
+
+## Try once
+
+From a machine with flakes enabled:
+
+```bash
+nix run github:letta-ai/letta-code
+```
+
+To run from a local checkout:
+
+```bash
+nix run .
+```
+
+## Install into a profile
+
+```bash
+nix profile install github:letta-ai/letta-code
+letta
+```
+
+## Home Manager
+
+Add Letta Code as a flake input and enable the module:
+
+```nix
+{
+  inputs.letta-code.url = "github:letta-ai/letta-code";
+
+  outputs = { nixpkgs, home-manager, letta-code, ... }: {
+    homeConfigurations.example = home-manager.lib.homeManagerConfiguration {
+      pkgs = import nixpkgs { system = "x86_64-linux"; };
+      modules = [
+        letta-code.homeManagerModules.default
+        {
+          programs.letta-code.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+## NixOS service
+
+For an always-on listener or channel host, enable the NixOS module and provide secrets through a root-readable environment file:
+
+```nix
+{
+  inputs.letta-code.url = "github:letta-ai/letta-code";
+
+  outputs = { nixpkgs, letta-code, ... }: {
+    nixosConfigurations.agent-host = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        letta-code.nixosModules.default
+        {
+          services.letta-code = {
+            enable = true;
+            environmentFile = "/run/secrets/letta-code.env";
+            extraArgs = [ "listen" ];
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+The environment file can contain values such as:
+
+```dotenv
+LETTA_API_KEY=...
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+SLACK_BOT_TOKEN=...
+SLACK_SIGNING_SECRET=...
+```
+
+Use your normal NixOS secret manager, such as sops-nix or agenix, to materialize that file.
+
+## What this provides
+
+The flake exposes:
+
+- `packages.<system>.default` / `packages.<system>.letta-code`
+- `apps.<system>.default` / `apps.<system>.letta`
+- `homeManagerModules.default` and the compatibility alias `homeModules.default`
+- `nixosModules.default`
+
+The package builds the Letta Code CLI from this repository with Bun. Dependency resolution is driven by the checked-in `bun.lock`; the generated `bun.nix` file lets the flake prefetch those Bun dependencies reproducibly for offline Nix builds. The resulting `letta` binary is wrapped with common runtime tools, and agent configuration and credentials stay in the normal Letta Code locations.
+
+When `bun.lock` changes, regenerate the Nix dependency expression before opening the PR:
+
+```bash
+bunx bun2nix -o bun.nix
+```
+
+## Follow-up packaging work
+
+This in-repository flake is the fastest path for Nix users to try and deploy Letta Code. A future nixpkgs or Home Manager upstream package should reuse the same shape, but may need additional hardening around native Node dependencies such as `node-pty`, `sharp`, and optional ripgrep binaries.

package/docs/plans/discord-channel-policy-consolidation.md

@@ -0,0 +1,35 @@
+# Discord channel policy consolidation plan
+
+This branch consolidates the overlapping Discord channel work from PR #2045 and PR #2306.
+
+## Direction
+
+- Use PR #2306 as the architectural base for per-channel Discord behavior.
+- Keep the per-channel `allowed_channels` mode map instead of the account-level `channelPolicy` field from PR #2045.
+- Keep `thread_policy_by_channel`, delivery-time `allowed_channels` enforcement, `parentChannelId`, route reconciliation, and route cleanup gated by `remove_stale_routes`.
+- Preserve legacy-safe defaults unless a breaking behavior change is made deliberately in a later PR.
+- Port the useful orthogonal pieces from PR #2045: Discord audio transcription and setup-flow coverage for the new options.
+
+## Keep from PR #2306
+
+- `allowed_channels` as either the legacy `string[]` allowlist or a per-channel mode map of `open` / `mention-only`.
+- `thread_policy_by_channel` for per-channel mention-thread behavior.
+- Delivery-time route gating using `parentChannelId` so stale routes cannot bypass current channel policy.
+- `letta channels route reconcile --channel discord` with `--apply` guarded by `remove_stale_routes`.
+- Typing indicators for Discord while an agent response is in flight.
+- `acknowledge_message_reaction` as an explicit opt-in/out knob.
+- Snake-case persisted config migration for newly added account fields.
+
+## Port from PR #2045
+
+- Discord `transcribe_voice` support for inbound audio attachments.
+- Discord setup prompts for guild channel mode, mention thread behavior, debounce, reaction acknowledgments, and audio transcription.
+- Mention-preserving debounce semantics so an explicit mention in a buffered burst is not lost.
+
+## Fix before opening the PR
+
+- Keep `autoThreadOnMention` defaulting to `false`; Discord thread creation is opt-in.
+- Keep `inboundDebounceMs` defaulting to `0` / disabled; open-channel debounce remains opt-in.
+- Do not overload `isMention` for open-channel routing; carry `isOpenChannel` separately.
+- Remove the unrelated Discord MessageChannel tool-result format change.
+- Add/update targeted tests for defaults, routing semantics, transcription, setup config, and websocket/config round trips.