@letta-ai/letta-code 0.23.11 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.23.11",
+  "version": "0.24.1",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@letta-ai/letta-client": "1.10.1",
+    "@letta-ai/letta-client": "^1.10.2",
     "glob": "^13.0.0",
     "highlight.js": "^11.11.1",
     "ink-link": "^5.0.0",

package/skills/context_doctor/SKILL.md

@@ -12,6 +12,8 @@ Your context is what makes you *you* across sessions. You are responsible for ma
 
 Over time, context can degrade — bloat and poor prompt quality erode your ability to remember the right things and follow instructions properly. This skill helps you identify issues with your context and repair them collaboratively with the user.
 
+**IMPORTANT**: Your edits of your system instructions should be **conservative**. Do NOT make assuptions about what parts of the system prompt are critical. The system prompt defines who you are, so significant modifications to its structure can have unintended consequences. Focus on making minimal changes to meet the token budget, and to effectively link out to external memory. 
+
 ## Operating Procedure
 
 ### Step 1: Identify and resolve context issues 
@@ -19,37 +21,33 @@ Explore your memory files to identify issues. Consider what is confusing about y
 
 Below are additional common issues with context and how they can be resolved: 
 
-### Context quality 
-Your system prompt and memory filesystem should be well structured and clear. 
-
-**Questions to ask**: 
-- Is my system prompt clear and well formatted? 
-- Are there wasteful or unnecessary tokens in my prompts? 
-- Do I know when to load which files in my memory filesystem? 
-
-#### System prompt bloat 
-Memories that are compiled as part of the system prompt (contained in `system/`) should only take up about 10% of the total context size (usually ~15-20K tokens), though this is a recommendation, not a hard requirement.
+#### System prompt bloat
+Memories compiled into the system prompt (contained in `system/`) should take up about 10% of the total context size (usually ~15-20K tokens). This is a soft target, not a hard requirement.
 
-Use the following script to evaluate the token usage of the system prompt: 
+Use the following script to evaluate the token usage of the system prompt:
 ```bash
 npx tsx <SKILL_DIR>/scripts/estimate_system_tokens.ts --memory-dir "$MEMORY_DIR"
 ```
 Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header).
 
-**Questions to ask**:
-- Do all these tokens need to be passed to the LLM on every turn, or can they be retrieved when needed through being part of external memory or conversation history? 
-- Do any of these prompts confuse or distract me? 
-- Am I able to effectively follow critical instructions (e.g. persona information, user preferences) given the current prompt structure and contents? 
+**Why detail is load-bearing (read this before cutting anything)**: In-context detail does more than carry information. It does at least four things, and byte-counting sweeps only see the first:
+1. **Information** — the literal facts stated
+2. **Attention anchoring** — makes certain topics feel important to the model when it's reasoning
+3. **Semantic priming** — raises the prior on codebase-specific patterns ("this codebase has weird X, don't assume defaults")
+4. **Reasoning templates** — past examples become heuristics for new bugs; rationale in "why" prose becomes scaffolding
+
+Compression preserves (1). It destroys (2), (3), (4). That's why a compressed prompt can make an agent measurably worse at codebase-specific reasoning even though the explicit facts are all "still there" in reference files.
+
+
+**Reference links (`[[path]]`) are NOT equivalent to in-context presence.** They're latent until the agent actively fetches them. An agent only fetches when it already knows it doesn't know. The priming cues that tell it *when* it doesn't know are in the system prompt itself — they can't be replaced by links.
 
-**Solution**: Reduce the size of the system prompt if needed: 
-- Move files outside of `system/` so they are no longer part of the system prompt
-- Compact information to be more information dense or eliminate redundancy
-- Leverage progressive disclosure: move some context outside of `system/` and reference it via `[[path]]` links to create discovery paths
+**When to intervene**: Only if the system prompt is *meaningfully* over target. At or near the target, leave it alone. Every edit risks removing content that was doing work you can't see. A prompt that feels "a bit long" is almost always better than one that's been aggressively trimmed.
 
-**Scope**: You may refine, tighten, and restructure prompts to improve clarity and adherence — but do not change the intended semantics. The goal is better signal, not different behavior.
-- Do not alter persona-defining content (who you are, how you communicate)
-- Do not remove or change user identity or preferences (e.g. the human's name, their stated goals)
-- Do not rewrite instructions in ways that shift their meaning — only reduce noise and improve structure
+**Modifying the system prompt**: Make **MINIMAL** changes required to cut the token count of the system prompt if needed. The goal preserve the existing behavior while cutting down the token count. Focus on reducing redundancy or compressing - rather than offloading entire sections to external memory.
+- Preserve persona-defining content (who you are, how you communicate)
+- Preserve user identity or preferences (e.g. the human's name, their stated goals)
+- Maintain the existing distribution of detail: compression should be applied evenly across all topics. If the original prompt was 50% about a specific issue, the new prompt should also be 50% about that issue. 
+- Only reduce noise and improve structure - if compression must result in information loss, preserve lost details into external memory
 
 #### Context redundancy and unclear organization 
 The context in the memory filesystem should have a clear structure, with a well-defined purpose for each file. Memory file descriptions should be precise and non-overlapping. Their contents should be consistent with the description, and have non-overlapping content to other files. 
@@ -98,10 +96,13 @@ Sarah's active projects are: Letta Code [[projects/letta_code.md]] and Letta Clo
 - Make sure your future self will be able to find and load external files when needed. 
 
 ### Step 2: Implement context fixes
-Create a plan for what fixes you want to make, then implement them.
+Create a plan for what fixes you want to make, then implement them. Favor the smallest possible change that resolves the issue — if the system prompt is 1.5× the target, don't cut it to half the target "for headroom." Cut until you're near the target, then stop.
 
 Before moving on, verify:
 - [ ] System prompt token budget reviewed (target ~10% of context, usually 15-20k tokens)
+- [ ] Changes are proportional to the problem — only offloaded what's needed to meet the target
+- [ ] Preserved detailed rationale, examples, and cross-references in sections that stayed in `system/`
+- [ ] Preferred moving whole files or deleting stale sections over compressing detailed sections into summaries
 - [ ] No overlapping or redundant files remain
 - [ ] All file descriptions are unique, accurate, and match their contents
 - [ ] Moved-out knowledge has `[[path]]` references from in-context memory so it can be discovered
@@ -130,4 +131,4 @@ Before finishing make sure you:
 - [ ] Told the user to run `/recompile` to refresh the system prompt and apply changes
 
 ## Critical information 
-- **Ask the user about their goals for you, not the implementation**: You understand your own context best, and should follow the guidelines in this document. Do NOT ask the user about their structural preferences — the context is for YOU, not them. Ask them how they want YOU to behave or know instead. 
+- **Ask the user about their goals for you, not the implementation**: You understand your own context best, and should follow the guidelines in this document. Do NOT ask the user about their structural preferences — the context is for YOU, not them. Ask them how they want YOU to behave or know instead.

package/skills/initializing-memory/SKILL.md

@@ -292,7 +292,7 @@ If the worker output is generic, the worker failed. "User is direct" or "project
 **IMPORTANT**: Use this prompt template to ensure workers extract all required categories:
 
 ```
-Task({
+Agent({
   subagent_type: "history-analyzer",
   description: "Process chunk [N] of [SOURCE] history",
   prompt: `## Assignment
@@ -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/`
@@ -560,8 +560,8 @@ 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",
+Agent({
+  subagent_type: "general-purpose",
   description: "Explore API layer",
   run_in_background: true,
   prompt: `Read the implementation in src/api/.
@@ -573,8 +573,8 @@ Return:
 4. gotchas or deprecated paths
 5. file paths worth storing in memory`
 })
-Task({
-  subagent_type: "explore",
+Agent({
+  subagent_type: "general-purpose",
   description: "Explore frontend layer",
   run_in_background: true,
   prompt: `Read the implementation in src/ui/.
@@ -586,8 +586,8 @@ Return:
 4. gotchas or fragile areas
 5. file paths worth storing in memory`
 })
-Task({
-  subagent_type: "explore",
+Agent({
+  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

@@ -30,11 +30,11 @@ This skill enables you to send messages to other agents on the same Letta server
 
 **Important:** This skill is for *communication* with other agents, not *delegation* of local work. The target agent runs in their own environment and cannot interact with your codebase.
 
-**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:
+**Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Agent 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({
+  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()