@letta-ai/letta-code 0.1.9 → 0.1.11

package/README.md

@@ -13,7 +13,7 @@ Letta Code is a command-line harness around the stateful Letta [Agents API](http
 Letta Code is model agnostic, and supports Sonnet 4.5, GPT-5, Gemini 2.5, GLM-4.6, and more.
 
 > [!IMPORTANT]
-> Letta Code is a **research preview** in active development, and may have bugs or unexpected issues. To learn more about the roadmap and chat with the dev team, visit our [Discord](https:/discord.gg/letta). Contributions welcome, join the fun.
+> Letta Code is a **research preview** in active development, and may have bugs or unexpected issues. To learn more about the roadmap and chat with the dev team, visit our [Discord](https://discord.gg/letta). Contributions welcome, join the fun.
 
 ## Quickstart
 
@@ -24,7 +24,7 @@ Install the package via [npm](https://docs.npmjs.com/downloading-and-installing-
 npm install -g @letta-ai/letta-code
 ```
 
-Make sure you have your Letta API key set in your environment:
+Set your Letta API key via environment variable:
 ```bash
 export LETTA_API_KEY=...
 ```
@@ -38,67 +38,86 @@ Any of the agents you create in Letta Code will be viewable (and fully interacta
 
 ## Persistence
 
-All agents in Letta are **stateful**: they maintain context forever and can self-edit their own [memory blocks](https://www.letta.com/blog/memory-blocks). Agents can share memory blocks across projects—for example, multiple agents can share user coding preferences while maintaining project-specific memories independently.
+All agents in Letta are **stateful**: they maintain context forever and can self-edit their own [memory blocks](https://www.letta.com/blog/memory-blocks). 
+
+### Project-Level Agent Persistence
+
+**Letta Code automatically remembers the last agent used in each directory.**
+When you run `letta` in a project, it resumes where you left off with the same agent.
+
+**How it works:**
+- First time running `letta` in a directory → creates new agent (with shared memory blocks across all Letta Code agents)
+- Subsequent runs → automatically resumes that agent
+- Agent ID stored in `.letta/settings.local.json` (gitignored, personal to you)
+
+```bash
+letta                    # Auto-resumes project agent (or creates new if first time)
+letta --new              # Force create new agent
+letta --agent <id>       # Use specific agent ID
+```
 
 ### Memory Configuration
 
-Letta Code uses a hierarchical memory system with both global and local blocks:
+Letta Code uses a hierarchical memory system:
 
 **Global** (`~/.letta/settings.json`)
+- API keys and credentials
 - `persona` block - defines agent behavior 
 - `human` block - stores user coding preferences
 
-**Local** (`./.letta/settings.json`)  
-- `project` block - stores project-specific context
-
-### Starting Letta
-
-```bash
-letta                    # New agent (attaches to existing memory blocks or creates new)
-letta --continue         # Resume last agent session
-letta --agent <id>       # Resume specific agent session
-```
+**Project** (`./.letta/settings.local.json`)  
+- Last agent ID for this directory (auto-resumes)
+- Gitignored - personal to you, not shared with your team
 
-When you start a new agent, it automatically connects to existing memory block IDs from your settings files. If none exist, it creates them.
+**Project Shared** (`./.letta/settings.json`)  
+- `project` block - stores project-specific context
+- Can be committed - shared with team
 
-Memory blocks are highly configurable — see our [docs](https://docs.letta.com/guides/agents/memory-blocks) for advanced configuration options. Join our [Discord](https://discord.gg/letta) to share feedback on persistence patterns for coding agents.
+Memory blocks are highly configurable — see our [docs](https://docs.letta.com/guides/agents/memory-blocks) for advanced configuration options.
+Join our [Discord](https://discord.gg/letta) to share feedback on persistence patterns for coding agents.
 
 ## Usage
 
 ### Interactive Mode
 ```bash
-letta                    # Start new session (new agent with shared memory blocks)
-letta --continue         # Resume last session (last recently used agent)
-letta --agent <id>       # Open specific agent
+letta                    # Auto-resume project agent (or create new if first time)
+letta --new              # Force create new agent
+letta --agent <id>       # Use specific agent ID
+letta --continue         # Resume global last agent (deprecated, use project-based)
 ```
 
 ### Headless Mode
 ```bash
-letta -p "your prompt"                           # Run non-interactive
-letta -p "commit changes" --continue             # Continue previous session
-letta -p "run tests" --allowedTools "Bash"       # Control tool permissions
-letta -p "run tests" --disallowedTools "Bash"    # Control tool permissions
+letta -p "Run bun lint and correct errors"              # Auto-resumes project agent
+letta -p "Pick up where you left off"                   # Same - auto-resumes by default
+letta -p "Start fresh" --new                            # Force new agent
+letta -p "Run all the test" --allowedTools "Bash"       # Control tool permissions
+letta -p "Just read the code" --disallowedTools "Bash"  # Control tool permissions
 
 # Pipe input from stdin
 echo "Explain this code" | letta -p
 cat file.txt | letta -p
-gh pr diff 123 | letta -p --yolo                 # Review PR changes
+gh pr diff 123 | letta -p --yolo
+
+# Output formats
+letta -p "Analyze this codebase" --output-format json         # Structured JSON at end
+letta -p "Analyze this codebase" --output-format stream-json  # JSONL stream (one event per line)
 ```
 
 You can also use the `--tools` flag to control the underlying *attachment* of tools (not just the permissions).
 Compared to disallowing the tool, this will additionally remove the tool schema from the agent's context window.
 ```bash
-letta -p "run tests" --tools "Bash,Read"         # Only load specific tools
-letta -p "analyze code" --tools ""               # No tools (analysis only)
+letta -p "Run all tests" --tools "Bash,Read"         # Only load specific tools
+letta -p "Just analyze the code" --tools ""          # No tools (analysis only)
 ```
 
-Use `--output-format json` to get additional information, including the agent ID ("session_id"):
+Use `--output-format json` to get structured output with metadata:
 ```bash
 # regular text output
 $ letta -p "hi there"
 Hi! How can I help you today?
 
-# structured output
+# structured output (single JSON object at end)
 $ letta -p "hi there" --output-format json
 {
   "type": "result",
@@ -108,14 +127,32 @@ $ letta -p "hi there" --output-format json
   "duration_api_ms": 2098,
   "num_turns": 1,
   "result": "Hi! How can I help you today?",
-  "session_id": "agent-8ab431ca-63e0-4ca1-ba83-b64d66d95a0f",
+  "agent_id": "agent-8ab431ca-63e0-4ca1-ba83-b64d66d95a0f",
   "usage": {
-    "input_tokens": 294,
-    "output_tokens": 97
+    "prompt_tokens": 294,
+    "completion_tokens": 97,
+    "total_tokens": 391
   }
 }
 ```
 
+Use `--output-format stream-json` to get streaming outputs, in addition to a final JSON response.
+This is useful if you need to have data flowing to prevent automatic timeouts:
+```bash
+# streaming JSON output (JSONL - one event per line, token-level streaming)
+# Note: Messages are streamed at the token level - each chunk has the same otid and incrementing seqId.
+$ letta -p "hi there" --output-format stream-json
+{"type":"init","agent_id":"agent-...","model":"claude-sonnet-4-5-20250929","tools":[...]}
+{"type":"message","messageType":"reasoning_message","reasoning":"The user is asking","otid":"...","seqId":1}
+{"type":"message","messageType":"reasoning_message","reasoning":" me to say hello","otid":"...","seqId":2}
+{"type":"message","messageType":"reasoning_message","reasoning":". This is a simple","otid":"...","seqId":3}
+{"type":"message","messageType":"reasoning_message","reasoning":" greeting.","otid":"...","seqId":4}
+{"type":"message","messageType":"assistant_message","content":"Hi! How can I help you today?","otid":"...","seqId":5}
+{"type":"message","messageType":"stop_reason","stopReason":"end_turn"}
+{"type":"message","messageType":"usage_statistics","promptTokens":294,"completionTokens":97,"totalTokens":391}
+{"type":"result","subtype":"success","result":"Hi! How can I help you today?","agent_id":"agent-...","usage":{...}}
+```
+
 ### Permissions
 
 **Tool selection** (controls which tools are loaded):
@@ -151,6 +188,11 @@ Permissions are also configured in `.letta/settings.json`:
 }
 ```
 
+## Self-hosting
+
+To use Letta Code with a self-hosted server, set `LETTA_BASE_URL` to your server IP, e.g. `export LETTA_BASE_URL="http://localhost:8283"`.
+See our [self-hosting guide](https://docs.letta.com/guides/selfhosting) for more information.
+
 ## Installing from source
 
 First, install Bun if you don't have it yet: [https://bun.com/docs/installation](https://bun.com/docs/installation)
@@ -171,7 +213,7 @@ bun run dev -- -p "Hello world"  # example with args
 bun run build
 
 # expose the binary globally (adjust to your preference)
-bun link --global   # or: bun add --global .
+bun link
 
 # now you can run the compiled CLI
 letta