Mods

Mods let you customize Letta Code with trusted local code. They run inside your local Letta Code process and are useful when you want to change the app around the agent: custom commands, UI/status customizations, or local provider adapters.

Mods are for changing the harness itself. If you want to teach your agent how to do a task, ask it to write a skill. If you want a new local capability that Letta Code should load every time it starts, ask it to write a mod.

Ask your agent to write mods

In most cases, you should not hand-write mods from this page. Letta Code agents have access to the deeper mod documentation inside the codebase, and can create the mod for you in the right place.

For example, ask:

Write a Letta Code mod that adds a /review command for reviewing my current git diff.

Your agent can inspect any existing files in ~/.letta/mods/, write the new mod, and tell you to run /reload when it is ready.

Setup

Mods live in your global Letta directory:

~/.letta/mods/

Each .js, .mjs, .ts, or .tsx file in that directory is loaded on startup. After editing a mod, run /reload to reload it without restarting Letta Code.

Mods are trusted code. They run locally with the same access as Letta Code, so only install or write mods you trust.

Example

A mod exports an activate function. Inside activate, register the capabilities you want and return a cleanup function if the mod owns timers, UI, or subscriptions.

~/.letta/mods/whereami.ts

export default function activate(letta) {
  if (!letta.capabilities.commands) return;

  return letta.commands.register({
    id: "whereami",
    description: "Show the active agent and working directory",
    run(ctx) {
      return {
        type: "output",
        output: `Agent: ${ctx.agent.name ?? ctx.agent.id}\nCWD: ${ctx.cwd}`,
      };
    },
  });
}

Now /whereami is available in Letta Code.

What mods can do

Mods can add explicit user actions, like /whereami, or change how Letta Code behaves around a session. For example, a mod might turn /review into your preferred review prompt, show project state in the UI, or connect a local model provider.

Mods can also react to events. For example, a mod can update local status when a conversation opens, rewrite a tool argument before execution, or add focused context before a turn starts. These event hooks are powerful, so keep them narrow and predictable.

For model providers, mods are local-only. They can make a custom provider available to local agents, but they do not add providers for Constellation/cloud agents.

Debugging

If a mod breaks startup or command handling, start Letta Code with mods disabled:

letta --no-mods

or:

LETTA_DISABLE_MODS=1 letta

Diagnostics are written to:

~/.letta/mods/diagnostics/latest.json

Keep mods focused. Prefer one clear owner for one clear behavior, and use skills for long-lived agent instructions.