@letta-ai/letta-code 0.23.11 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.23.11",
+  "version": "0.24.0",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/initializing-memory/SKILL.md

@@ -535,7 +535,7 @@ Explore based on chosen depth.
 
 For medium-to-large repos, parallel exploration is the preferred strategy after your initial scan.
 
-Use parallel subagents to investigate different subsystems simultaneously. Prefer a **read-only exploration subagent** when available. If your environment or user instructions discourage using an exploration subagent, do the equivalent exploration directly with Bash/Glob/Grep/Read.
+Use parallel `general-purpose` subagents to investigate different subsystems simultaneously. If your environment or user instructions discourage using subagents, do the equivalent exploration directly with Bash/Glob/Grep/Read.
 
 Good subsystem boundaries include:
 - `server/`, `client/`, `shared/`
@@ -561,7 +561,7 @@ Launch exploration subagents in a **single message** so they run concurrently.
 ```
 # After initial scan reveals key areas, launch parallel explorers in the background:
 Task({
-  subagent_type: "explore",
+  subagent_type: "general-purpose",
   description: "Explore API layer",
   run_in_background: true,
   prompt: `Read the implementation in src/api/.
@@ -574,7 +574,7 @@ Return:
 5. file paths worth storing in memory`
 })
 Task({
-  subagent_type: "explore",
+  subagent_type: "general-purpose",
   description: "Explore frontend layer",
   run_in_background: true,
   prompt: `Read the implementation in src/ui/.
@@ -587,7 +587,7 @@ Return:
 5. file paths worth storing in memory`
 })
 Task({
-  subagent_type: "explore",
+  subagent_type: "general-purpose",
   description: "Explore shared systems",
   run_in_background: true,
   prompt: `Read the implementation in src/shared/.

package/skills/messaging-agents/SKILL.md

@@ -33,8 +33,8 @@ This skill enables you to send messages to other agents on the same Letta server
 **Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Task tool instead to deploy them as a subagent:
 ```typescript
 Task({
-  agent_id: "agent-xxx",           // Deploy this existing agent
-  subagent_type: "explore",        // "explore" = read-only, "general-purpose" = read-write
+  agent_id: "agent-xxx",            // Deploy this existing agent
+  subagent_type: "general-purpose", // read-write access to your local tools
   prompt: "Look at the code in src/ and tell me about the architecture"
 })
 ```

package/skills/modifying-letta-code/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: "modifying-letta-code"
+description: "Modify your own Letta Code harness: permission rules, hooks, and agent configuration (model, context window, name, toolset, system prompt). Use when you want to change your own deterministic configuration, not your memory."
+---
+
+# Modifying Letta Code (Self-Configuration)
+
+This skill tells you — the agent — how to modify your own **harness**: the deterministic configuration layer around you. Load this skill when you want to change how you run (model, permissions, hooks, toolset, system prompt, name, etc.).
+
+## Memory vs Harness
+
+Before you change anything, know which layer you're in:
+
+| Layer | What it is | How you change it |
+|-------|-----------|-------------------|
+| **Memory** | Dynamic state you learn and reorganize (`$MEMORY_DIR`, memfs, conversation history) | Memory tool, file edits in `$MEMORY_DIR`, skill operations |
+| **Harness** | Deterministic config (model, permissions, hooks, toolset, system prompt) | This skill — edit `settings.json` or call the Letta API |
+
+Memory is probabilistic: your notes evolve, your history compacts, your skills get loaded and unloaded. The harness is deterministic: given the same settings, you behave the same way. Don't conflate them — edit memory when you're learning, edit the harness when you're reconfiguring.
+
+## Where to make changes
+
+You have two places to modify harness config:
+
+### 1. Settings JSON files (you can edit these directly with Write/Edit)
+
+| File | Scope | Contents |
+|------|-------|----------|
+| `~/.letta/settings.json` | User (global) | Permissions, hooks, per-agent settings (`agents[]`), pinning, env vars |
+| `./.letta/settings.json` | Project | Permissions, hooks, shared with team via git |
+| `./.letta/settings.local.json` | Local | Permissions, hooks, personal overrides (gitignored) |
+
+Precedence (highest wins): **local > project > user**.
+
+### 2. The Letta API (for server-side agent state)
+
+Your **name**, **description**, **model**, **context window**, and **system prompt** live on the Letta server. To change them, call the Letta API.
+
+**Base URL:** `https://api.letta.com`
+**Docs:** https://docs.letta.com/api-overview/introduction
+**Auth:** `Authorization: Bearer $LETTA_API_KEY`
+
+Your own agent ID is `$LETTA_AGENT_ID` (always available in your environment).
+
+You can use the Python or TypeScript SDK, or just `curl`:
+
+```bash
+# Rename yourself
+curl -X PATCH "https://api.letta.com/v1/agents/$LETTA_AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "new-name"}'
+```
+
+If you need rich SDK examples, load the `letta-api-client` skill.
+
+---
+
+## 1. Changing your permissions
+
+Permissions control which tool calls need user approval. Edit `settings.json` directly, or use the helper script.
+
+### Rule syntax
+
+- **Bash** (prefix match with `:*`): `Bash(npm install:*)`, `Bash(git:*)`, `Bash(curl:*)`
+- **Files** (glob): `Read(src/**)`, `Edit(**/*.ts)`, `Write(*.md)`
+- **All** (dangerous): `*`, `Bash`, `Read`
+
+### Helper: add a rule
+
+```bash
+python3 <skill-dir>/scripts/add_permission.py \
+  --rule "Bash(curl:*)" \
+  --type allow \
+  --scope user
+```
+
+### Direct edit (in `settings.json`)
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm:*)", "Read(src/**)"],
+    "deny":  ["Bash(rm -rf:*)"],
+    "ask":   []
+  }
+}
+```
+
+After editing, your new rules apply on your next restart. In-session additions via the approval UI go into session-only memory and are cleared on exit.
+
+---
+
+## 2. Adding hooks
+
+Hooks let you run a shell command or LLM prompt in response to events. Use them to log activity, enforce policy, auto-format, or gate actions.
+
+### Events
+
+**Tool events** (need a `matcher`):
+- `PreToolUse` — before a tool runs (can block)
+- `PostToolUse` — after a tool succeeds
+- `PostToolUseFailure` — after a tool fails (stderr fed back to you)
+- `PermissionRequest` — when a permission dialog shows (can allow/deny)
+
+**Simple events** (no matcher):
+- `UserPromptSubmit` — user sends a prompt (can block)
+- `Stop` — you finish responding (can block)
+- `SubagentStop` — a subagent finishes
+- `PreCompact` — before context compaction
+- `SessionStart`, `SessionEnd`, `Notification`
+
+### Hook types
+
+**Command** — runs a shell command:
+```json
+{"type": "command", "command": "echo $TOOL_INPUT >> ~/audit.log", "timeout": 60000}
+```
+
+**Prompt** — sends event JSON to an LLM for evaluation:
+```json
+{"type": "prompt", "prompt": "Is this safe? Input: $ARGUMENTS", "model": "gpt-5.2"}
+```
+Supported events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`.
+
+### Helper: add a hook
+
+```bash
+python3 <skill-dir>/scripts/add_hook.py \
+  --event PreToolUse \
+  --matcher Bash \
+  --type command \
+  --command 'echo "bash: $TOOL_INPUT" >> ~/.letta/audit.log' \
+  --scope user
+```
+
+### Direct edit (in `settings.json`)
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": "echo $TOOL_INPUT >> audit.log"}]
+      }
+    ],
+    "Stop": [
+      {"hooks": [{"type": "command", "command": "say done"}]}
+    ]
+  }
+}
+```
+
+Matchers: exact (`"Bash"`), multiple (`"Edit|Write"`), all (`"*"`).
+
+---
+
+## 3. Changing your agent configuration
+
+Agent config splits between the Letta server and local settings.
+
+### Server-side fields (use the Letta API)
+
+Use `PATCH /v1/agents/{agent_id}` with `$LETTA_AGENT_ID`.
+
+**Change your model and context window:**
+```bash
+curl -X PATCH "https://api.letta.com/v1/agents/$LETTA_AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "llm_config": {
+      "model": "claude-sonnet-4.5",
+      "model_endpoint_type": "anthropic",
+      "context_window": 200000
+    }
+  }'
+```
+
+**Rename yourself:**
+```bash
+curl -X PATCH "https://api.letta.com/v1/agents/$LETTA_AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "draft-v2"}'
+```
+
+**Update your description:**
+```bash
+curl -X PATCH "https://api.letta.com/v1/agents/$LETTA_AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"description": "..."}'
+```
+
+**Update your system prompt (use with care — system prompt is structural):**
+```bash
+curl -X PATCH "https://api.letta.com/v1/agents/$LETTA_AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"system": "You are..."}'
+```
+
+For Python / TypeScript SDK usage, see `docs.letta.com/api-overview/introduction` or load the `letta-api-client` skill.
+
+### Local per-agent harness (edit `~/.letta/settings.json`)
+
+The `agents[]` array stores per-agent harness preferences you can edit directly:
+
+```json
+{
+  "agents": [
+    {
+      "agentId": "agent-abc123",
+      "baseUrl": "https://api.letta.com",
+      "pinned": true,
+      "memfs": { "enabled": true },
+      "toolset": "full",
+      "systemPromptPreset": "letta-code-v2"
+    }
+  ]
+}
+```
+
+- **`toolset`** — which tool set to load for this agent
+- **`memfs.enabled`** — whether the memory filesystem is active
+- **`systemPromptPreset`** — which preset was last applied (informational; the actual system prompt is server-side)
+- **`pinned`** — show in the quick-switch list
+
+Find your own entry by matching `agentId === $LETTA_AGENT_ID`, then edit the fields you need.
+
+---
+
+## Quick reference: what you want to change
+
+| Change | What to do |
+|--------|-----------|
+| Auto-approve `curl` commands | `add_permission.py --rule "Bash(curl:*)" --type allow --scope user` |
+| Block all `rm -rf` | Add `"Bash(rm -rf:*)"` to `permissions.deny` in `settings.json` |
+| Log every Bash command | `add_hook.py --event PreToolUse --matcher Bash --type command --command '...' --scope user` |
+| Auto-format after edits | `add_hook.py --event PostToolUse --matcher "Edit\|Write" --type command --command 'prettier ...' --scope project` |
+| Gate edits with an LLM check | `add_hook.py --event PreToolUse --matcher Edit --type prompt --prompt '...' --scope user` |
+| Change your model | `PATCH /v1/agents/$LETTA_AGENT_ID` with `llm_config.model` |
+| Change your context window | `PATCH /v1/agents/$LETTA_AGENT_ID` with `llm_config.context_window` |
+| Rename yourself | `PATCH /v1/agents/$LETTA_AGENT_ID` with `name` |
+| Update your description | `PATCH /v1/agents/$LETTA_AGENT_ID` with `description` |
+| Modify your system prompt | `PATCH /v1/agents/$LETTA_AGENT_ID` with `system` |
+| Pin yourself for quick-switch | Add `agentId` to `pinnedAgents` in `~/.letta/settings.json` |
+| Change toolset | Edit `agents[].toolset` in `~/.letta/settings.json` |
+| Disable memfs | Edit `agents[].memfs.enabled = false` in `~/.letta/settings.json` (and update system prompt via API if needed) |
+| See what's currently set | `python3 <skill-dir>/scripts/show_config.py` |
+
+---
+
+## After making changes
+
+- **`settings.json` changes** — take effect on next session restart. Your current session keeps the old values.
+- **Letta API changes** — apply immediately at the server level, but the in-memory agent config held by your current session may not reflect them until next restart.
+- **System prompt / model changes** — always start a fresh conversation after to get a clean context with the new config.
+
+## Helper scripts in this skill
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/add_permission.py` | Add an allow/deny/ask rule to any scope |
+| `scripts/add_hook.py` | Add a command or prompt hook to any event |
+| `scripts/show_config.py` | Show merged permissions, hooks, and per-agent settings across all scopes |
+
+All three accept `--scope user|project|local`. Run `--help` for full usage.

package/skills/modifying-letta-code/scripts/add_hook.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+Add a hook to Letta Code settings.
+
+Examples:
+    # Command hook for Bash tool calls
+    python3 add_hook.py --event PreToolUse --matcher Bash \
+        --type command --command 'echo "$TOOL_INPUT" >> audit.log' \
+        --scope user
+
+    # Prompt hook for pre-edit safety check
+    python3 add_hook.py --event PreToolUse --matcher "Edit|Write" \
+        --type prompt --prompt 'Is this safe? Input: $ARGUMENTS' \
+        --model gpt-5.2 --scope project
+
+    # Simple event hook (no matcher needed)
+    python3 add_hook.py --event Stop \
+        --type command --command 'say done' \
+        --scope user
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+TOOL_EVENTS = {"PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest"}
+SIMPLE_EVENTS = {
+    "UserPromptSubmit",
+    "Notification",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "SessionStart",
+    "SessionEnd",
+}
+ALL_EVENTS = TOOL_EVENTS | SIMPLE_EVENTS
+
+PROMPT_SUPPORTED = {
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "UserPromptSubmit",
+    "Stop",
+    "SubagentStop",
+}
+
+
+def get_settings_path(scope: str, working_directory: str) -> Path:
+    if scope == "user":
+        return Path.home() / ".letta" / "settings.json"
+    elif scope == "project":
+        return Path(working_directory) / ".letta" / "settings.json"
+    elif scope == "local":
+        return Path(working_directory) / ".letta" / "settings.local.json"
+    else:
+        raise ValueError(f"Unknown scope: {scope}")
+
+
+def load_settings(path: Path) -> dict:
+    if path.exists():
+        try:
+            with open(path) as f:
+                return json.load(f)
+        except json.JSONDecodeError:
+            print(f"Warning: Could not parse {path}, starting fresh", file=sys.stderr)
+            return {}
+    return {}
+
+
+def save_settings(path: Path, settings: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(settings, f, indent=2)
+    print(f"Saved to {path}")
+
+
+def build_hook_config(args) -> dict:
+    """Build the individual hook config from args."""
+    hook: dict = {"type": args.type}
+
+    if args.type == "command":
+        if not args.command:
+            raise ValueError("--command is required for type=command")
+        hook["command"] = args.command
+    elif args.type == "prompt":
+        if not args.prompt:
+            raise ValueError("--prompt is required for type=prompt")
+        if args.event not in PROMPT_SUPPORTED:
+            raise ValueError(
+                f"Event {args.event!r} does not support prompt hooks. "
+                f"Supported: {sorted(PROMPT_SUPPORTED)}"
+            )
+        hook["prompt"] = args.prompt
+        if args.model:
+            hook["model"] = args.model
+
+    if args.timeout is not None:
+        hook["timeout"] = args.timeout
+
+    return hook
+
+
+def add_hook(settings: dict, args) -> None:
+    """Add a hook entry to the settings dict."""
+    if "hooks" not in settings:
+        settings["hooks"] = {}
+
+    hooks_config = settings["hooks"]
+    event = args.event
+
+    if event not in hooks_config:
+        hooks_config[event] = []
+
+    hook = build_hook_config(args)
+
+    if event in TOOL_EVENTS:
+        # Tool events: need a matcher
+        matcher = args.matcher or "*"
+        # Find existing matcher group or create new one
+        entry = next(
+            (e for e in hooks_config[event] if e.get("matcher") == matcher), None
+        )
+        if entry is None:
+            entry = {"matcher": matcher, "hooks": []}
+            hooks_config[event].append(entry)
+        entry["hooks"].append(hook)
+    else:
+        # Simple events: no matcher, just hooks
+        if hooks_config[event]:
+            # Append to existing group
+            hooks_config[event][0].setdefault("hooks", []).append(hook)
+        else:
+            hooks_config[event].append({"hooks": [hook]})
+
+
+def ensure_local_gitignored(working_directory: str) -> None:
+    gitignore_path = Path(working_directory) / ".gitignore"
+    pattern = ".letta/settings.local.json"
+    try:
+        content = gitignore_path.read_text() if gitignore_path.exists() else ""
+        if pattern not in content:
+            with open(gitignore_path, "a") as f:
+                if content and not content.endswith("\n"):
+                    f.write("\n")
+                f.write(f"{pattern}\n")
+            print(f"Added {pattern} to .gitignore")
+    except Exception as e:
+        print(f"Warning: Could not update .gitignore: {e}", file=sys.stderr)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Add a hook to Letta Code settings",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument(
+        "--event",
+        required=True,
+        choices=sorted(ALL_EVENTS),
+        help="Hook event name",
+    )
+    parser.add_argument(
+        "--matcher",
+        help="Tool matcher pattern (for tool events). Examples: 'Bash', 'Edit|Write', '*'",
+    )
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=["command", "prompt"],
+        help="Hook type",
+    )
+    parser.add_argument("--command", help="Shell command (for type=command)")
+    parser.add_argument(
+        "--prompt",
+        help="LLM prompt text (for type=prompt). Use $ARGUMENTS for hook input JSON.",
+    )
+    parser.add_argument("--model", help="LLM model (for type=prompt)")
+    parser.add_argument(
+        "--timeout", type=int, help="Timeout in milliseconds (default: 60000/30000)"
+    )
+    parser.add_argument(
+        "--scope",
+        required=True,
+        choices=["user", "project", "local"],
+        help="Where to save the hook",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=os.getcwd(),
+        help="Working directory for project/local scope (default: cwd)",
+    )
+
+    args = parser.parse_args()
+
+    # Validation
+    if args.event in TOOL_EVENTS and not args.matcher:
+        print(
+            f"Warning: {args.event} is a tool event; using matcher='*' (match all tools)",
+            file=sys.stderr,
+        )
+
+    settings_path = get_settings_path(args.scope, args.cwd)
+    settings = load_settings(settings_path)
+
+    try:
+        add_hook(settings, args)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    save_settings(settings_path, settings)
+    print(f"Added {args.type} hook on {args.event}")
+
+    if args.scope == "local":
+        ensure_local_gitignored(args.cwd)
+
+
+if __name__ == "__main__":
+    main()

package/skills/modifying-letta-code/scripts/add_permission.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""
+Add a permission rule to Letta Code settings.
+
+Usage:
+    python3 add_permission.py --rule "Bash(npm run:*)" --type allow --scope user
+    python3 add_permission.py --rule "Read(src/**)" --type allow --scope project
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def get_settings_path(scope: str, working_directory: str) -> Path:
+    """Get the settings file path for a given scope."""
+    if scope == "user":
+        return Path.home() / ".letta" / "settings.json"
+    elif scope == "project":
+        return Path(working_directory) / ".letta" / "settings.json"
+    elif scope == "local":
+        return Path(working_directory) / ".letta" / "settings.local.json"
+    else:
+        raise ValueError(f"Unknown scope: {scope}")
+
+
+def load_settings(path: Path) -> dict:
+    """Load settings from a JSON file, or return empty dict if not found."""
+    if path.exists():
+        try:
+            with open(path) as f:
+                return json.load(f)
+        except json.JSONDecodeError:
+            print(f"Warning: Could not parse {path}, starting fresh", file=sys.stderr)
+            return {}
+    return {}
+
+
+def save_settings(path: Path, settings: dict) -> None:
+    """Save settings to a JSON file, creating parent directories if needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(settings, f, indent=2)
+    print(f"Saved to {path}")
+
+
+def add_rule(settings: dict, rule: str, rule_type: str) -> bool:
+    """
+    Add a permission rule to settings.
+
+    Returns True if the rule was added, False if it already exists.
+    """
+    if "permissions" not in settings:
+        settings["permissions"] = {}
+
+    if rule_type not in settings["permissions"]:
+        settings["permissions"][rule_type] = []
+
+    rules = settings["permissions"][rule_type]
+
+    if rule in rules:
+        return False
+
+    rules.append(rule)
+    return True
+
+
+def ensure_local_gitignored(working_directory: str) -> None:
+    """Ensure .letta/settings.local.json is in .gitignore."""
+    gitignore_path = Path(working_directory) / ".gitignore"
+    pattern = ".letta/settings.local.json"
+
+    try:
+        content = ""
+        if gitignore_path.exists():
+            content = gitignore_path.read_text()
+
+        if pattern not in content:
+            with open(gitignore_path, "a") as f:
+                if content and not content.endswith("\n"):
+                    f.write("\n")
+                f.write(f"{pattern}\n")
+            print(f"Added {pattern} to .gitignore")
+    except Exception as e:
+        print(f"Warning: Could not update .gitignore: {e}", file=sys.stderr)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Add a permission rule to Letta Code settings"
+    )
+    parser.add_argument(
+        "--rule",
+        required=True,
+        help='Permission rule pattern, e.g., "Bash(npm run:*)" or "Read(src/**)"',
+    )
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=["allow", "deny", "ask"],
+        help="Type of permission rule",
+    )
+    parser.add_argument(
+        "--scope",
+        required=True,
+        choices=["user", "project", "local"],
+        help="Where to save the rule",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=os.getcwd(),
+        help="Working directory for project/local scope (default: current directory)",
+    )
+
+    args = parser.parse_args()
+
+    settings_path = get_settings_path(args.scope, args.cwd)
+    settings = load_settings(settings_path)
+
+    if add_rule(settings, args.rule, args.type):
+        save_settings(settings_path, settings)
+        print(f"Added {args.type} rule: {args.rule}")
+
+        # Ensure local settings are gitignored
+        if args.scope == "local":
+            ensure_local_gitignored(args.cwd)
+    else:
+        print(f"Rule already exists: {args.rule}")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()