@letta-ai/letta-code 0.21.16 → 0.21.18

package/package.json

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

package/skills/scheduling-tasks/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: scheduling-tasks
+description: Schedules reminders and recurring tasks via the letta cron CLI. Use when the user asks to be reminded of something, wants periodic messages, or needs to manage scheduled tasks.
+---
+
+# Scheduling Tasks
+
+This skill lets you create, list, and manage scheduled tasks using the `letta cron` CLI. Scheduled tasks send a prompt to the agent on a timer — useful for reminders, periodic check-ins, and deferred follow-ups.
+
+## When to Use This Skill
+
+- User asks to be reminded of something ("remind me to X at Y")
+- User wants a recurring check-in ("every morning ask me about X")
+- User wants a one-shot delayed message ("in 30 minutes, check on X")
+- User wants to see or cancel existing scheduled tasks
+
+## CLI Usage
+
+All commands go through `letta cron` via the Bash tool. Output is JSON.
+
+### Creating a Task
+
+```bash
+letta cron add --name <short-name> --description <text> --prompt <text> <schedule>
+```
+
+**Required flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--name <text>` | Short identifier for the task (e.g. "dog-walk-reminder") |
+| `--description <text>` | Human-readable description of what the task does |
+| `--prompt <text>` | The message that will be sent to the agent when the task fires |
+
+**Schedule (pick one):**
+
+| Flag | Type | Example |
+|------|------|---------|
+| `--every <interval>` | Recurring | `5m`, `2h`, `1d` |
+| `--at <time>` | One-shot | `"3:00pm"`, `"in 45m"` |
+| `--cron <expr>` | Raw cron (recurring) | `"0 9 * * 1-5"` |
+
+**Optional flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--agent <id>` | Agent ID (defaults to `LETTA_AGENT_ID` env var — usually already set) |
+| `--conversation <id>` | Conversation ID (defaults to `LETTA_CONVERSATION_ID` or `"default"`) |
+
+### Listing Tasks
+
+```bash
+letta cron list
+```
+
+Optional filters: `--agent <id>`, `--conversation <id>`
+
+### Getting a Single Task
+
+```bash
+letta cron get <task-id>
+```
+
+### Deleting Tasks
+
+```bash
+# Delete a specific task
+letta cron delete <task-id>
+
+# Delete all tasks for the current agent
+letta cron delete --all
+```
+
+## Examples
+
+### "Remind me every morning at 9am to walk the dog"
+
+```bash
+letta cron add \
+  --name "dog-walk-reminder" \
+  --description "Daily morning reminder to walk the dog" \
+  --prompt "Hey! It's 9am — time to walk the dog." \
+  --every 1d
+```
+
+Note: `--every 1d` fires once daily at midnight. For a specific time like 9am, use a raw cron expression:
+
+```bash
+letta cron add \
+  --name "dog-walk-reminder" \
+  --description "Daily 9am reminder to walk the dog" \
+  --prompt "Hey! It's 9am — time to walk the dog." \
+  --cron "0 9 * * *"
+```
+
+### "Check on the deploy in 30 minutes"
+
+```bash
+letta cron add \
+  --name "deploy-check" \
+  --description "One-time check on deployment status" \
+  --prompt "The user asked you to check on the deploy — ask them how it went." \
+  --at "in 30m"
+```
+
+### "Every weekday at 5pm, remind me to submit my timesheet"
+
+```bash
+letta cron add \
+  --name "timesheet-reminder" \
+  --description "Weekday 5pm timesheet reminder" \
+  --prompt "Friendly reminder: don't forget to submit your timesheet before EOD!" \
+  --cron "0 17 * * 1-5"
+```
+
+### "What reminders do I have?"
+
+```bash
+letta cron list
+```
+
+### "Cancel the dog walk reminder"
+
+First list to find the task ID, then delete:
+
+```bash
+letta cron list
+# Find the task ID from the output, then:
+letta cron delete <task-id>
+```
+
+## Writing Good Prompts
+
+The `--prompt` value is what gets sent to you (the agent) when the task fires. Write it as a message that will make sense when you receive it later, with enough context to act on:
+
+- **Good**: "The user asked to be reminded to review the PR for the auth refactor. Check if it's still open and nudge them."
+- **Bad**: "reminder"
+
+Include context about what the user originally asked for, so you can give a helpful response when the prompt arrives.
+
+## Important Notes
+
+- **Minimum granularity**: 1 minute. Intervals under 60 seconds are rounded up.
+- **Recurring TTL**: Recurring tasks auto-expire after 3 days. The user would need to re-create them or you can note this limitation.
+- **One-shot cleanup**: One-shot tasks are garbage-collected 24 hours after firing.
+- **Timezone**: Tasks use the user's local timezone by default.
+- **Scheduler requirement**: Tasks only fire while a Letta session is running (a WS listener must be active). If no session is running, tasks will be marked as missed.
+- **`--at` for specific times**: `--at "3:00pm"` schedules a one-shot. If the time has already passed today, it schedules for tomorrow.
+- **`--every` for daily**: `--every 1d` fires daily at midnight. For a specific time of day, use `--cron` instead (e.g. `--cron "0 9 * * *"` for 9am daily).
+
+## Cron Expression Reference
+
+For `--cron`, use standard 5-field cron syntax:
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
+│ │ │ │ │
+* * * * *
+```
+
+Common patterns:
+- `*/5 * * * *` — every 5 minutes
+- `0 */2 * * *` — every 2 hours
+- `0 9 * * *` — daily at 9am
+- `0 9 * * 1-5` — weekdays at 9am
+- `30 8 1 * *` — 8:30am on the 1st of each month

package/skills/working-in-parallel/SKILL.md

@@ -11,6 +11,17 @@ Git worktrees let you check out multiple branches into separate directories. Eac
 
 Learn more: [Git worktree documentation](https://git-scm.com/docs/git-worktree)
 
+## IMPORTANT: Worktree Location
+
+**All worktrees MUST be created under `.letta/worktrees/` in the repo root.** This keeps worktrees organized, gitignored, and out of the user's project directory.
+
+Before creating the first worktree, ensure `.letta/worktrees` is in the repo's `.gitignore`:
+
+```bash
+# Add to .gitignore if not already present
+grep -q '.letta/worktrees' .gitignore 2>/dev/null || echo '.letta/worktrees' >> .gitignore
+```
+
 ## IMPORTANT: Check Project Setup First
 
 Before running ANY commands in a new worktree, check the project's setup instructions:
@@ -24,11 +35,14 @@ Don't assume `npm` vs `bun` vs `pnpm` - **check the project first!**
 ## Quick Start
 
 ```bash
-# Create worktree with new branch (from main repo)
-git worktree add -b fix/my-feature ../repo-my-feature main
+# Ensure .letta/worktrees is gitignored
+grep -q '.letta/worktrees' .gitignore 2>/dev/null || echo '.letta/worktrees' >> .gitignore
+
+# Create worktree with new branch (from repo root)
+git worktree add -b fix/my-feature .letta/worktrees/my-feature main
 
 # Work in the worktree
-cd ../repo-my-feature
+cd .letta/worktrees/my-feature
 
 # CHECK PROJECT SETUP FIRST - then install dependencies
 # Read README.md or check project memory block for correct command
@@ -40,17 +54,17 @@ git commit -m "fix: description"
 git push -u origin fix/my-feature
 gh pr create --title "Fix: description" --body "## Summary..."
 
-# Clean up when done (from main repo)
-git worktree remove ../repo-my-feature
+# Clean up when done (from repo root)
+git worktree remove .letta/worktrees/my-feature
 ```
 
 ## Key Commands
 
 ```bash
-git worktree add -b <branch> <path> main  # Create with new branch
-git worktree add <path> <existing-branch>  # Use existing branch
-git worktree list                          # Show all worktrees
-git worktree remove <path>                 # Remove worktree
+git worktree add -b <branch> .letta/worktrees/<name> main  # Create with new branch
+git worktree add .letta/worktrees/<name> <existing-branch>  # Use existing branch
+git worktree list                                            # Show all worktrees
+git worktree remove .letta/worktrees/<name>                  # Remove worktree
 ```
 
 ## When to Use
@@ -65,8 +79,9 @@ Worktrees share `.git`, but pre-commit hooks may need initialization depending o
 
 ## Tips
 
+- **Always use `.letta/worktrees/`** - never create worktrees outside this directory
 - **Check project setup docs before installing** - README, claude.md, project memory block
-- Name directories clearly: `../repo-feature-auth`, `../repo-bugfix-123`
+- Name worktrees clearly: `.letta/worktrees/feature-auth`, `.letta/worktrees/bugfix-123`
 - Install dependencies using the project's package manager (check first!)
 - Push changes before removing worktrees