Headless mode

Headless mode allows you to run Letta Code non-interactively, making it easy to integrate into scripts, CI/CD pipelines, or compose with other UNIX tools.

Basic usage

Use the -p flag to pass a prompt directly:

Run a one-off prompt

letta -p "Look around this repo and write a README.md documenting it"

You can also pipe input to Letta Code:

Pipe input

cat code.ts | letta -p "Review this code for bugs"
echo "Explain this error" | letta -p

Output formats

Letta Code supports three output formats in headless mode:

Text (default)

Returns the agent’s response as plain text:

letta -p "What files are in this directory?"

JSON

Returns a structured JSON response with metadata:

letta -p "List all TypeScript files" --output-format json

Example output

{
  "type": "result",
  "result": "Found 15 TypeScript files...",
  "agent_id": "agent-abc123",
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 89
  }
}

Stream JSON

Returns line-delimited JSON events for real-time streaming. This is useful for preventing timeouts and getting incremental progress:

letta -p "Explain this codebase" --output-format stream-json

Each line is a JSON event:

Example stream output

{"type":"init","agent_id":"agent-...","model":"claude-sonnet-4-5","tools":[...]}
{"type":"message","messageType":"reasoning_message","reasoning":"The user is asking...","otid":"...","seqId":1}
{"type":"message","messageType":"assistant_message","content":"Here's an overview...","otid":"...","seqId":5}
{"type":"message","messageType":"stop_reason","stopReason":"end_turn"}
{"type":"message","messageType":"usage_statistics","promptTokens":294,"completionTokens":97}
{"type":"result","subtype":"success","result":"Here's an overview...","agent_id":"agent-...","usage":{...}}

Messages are streamed at the token level - each chunk has the same otid (output turn ID) and incrementing seqId.

Agent selection

By default, headless mode auto-resumes the last agent used in the current directory (just like interactive mode). This means your agent retains memory across headless runs.

Create a new agent

letta -p "..." --new

Use a specific agent

letta -p "..." --agent <agent-id>

Model selection

Specify a model for the headless run:

letta -p "..." --model sonnet-4.5
letta -p "..." -m gpt-5-codex
letta -p "..." -m haiku

See Models for the full list of supported model IDs.

Permission control

Auto-allow all tools

Use --yolo to bypass all permission prompts (use with caution):

letta -p "Refactor this file" --yolo

Restrict available tools

The --tools flag controls which tools are attached to the agent (removing them from the context window entirely):

Only load specific tools

letta -p "Analyze this codebase" --tools "Read,Glob,Grep"

No tools (conversation only)

letta -p "What do you think about this approach?" --tools ""

This is different from --allowedTools/--disallowedTools which control permissions but keep tools in context. See Permissions for more details.

Permission modes

Auto-allow edits only

letta -p "Fix the type errors" --permission-mode acceptEdits

Read-only mode

letta -p "Review this PR" --permission-mode plan

Examples

Automated tasks

Run lint and fix errors

letta -p "Run the linter and fix any errors" --yolo

Structured output for scripts

Use JSON output to parse results programmatically:

result=$(letta -p "What is the main entry point of this project?" --output-format json)
echo $result | jq '.result'

Read-only analysis

Use --tools to restrict the agent to read-only operations:

letta -p "Review this codebase for potential security issues" --tools "Read,Glob,Grep"

Scheduled tasks with cron

Run Letta Code on a schedule using cron:

Daily code review at 9am

0 9 * * * cd /path/to/project && letta -p "Review recent changes and summarize any issues" --tools "Read,Glob,Grep" --output-format json >> /var/log/letta-review.log 2>&1

Weekly dependency check

0 10 * * 1 cd /path/to/project && letta -p "Check for outdated dependencies and security vulnerabilities" --yolo >> /var/log/letta-deps.log 2>&1