letta-code

Letta Code is an open-source agent harness built on the MemGPT research lineage, designed specifically for long-lived agents that need to remember, learn, and improve over time. Unlike ephemeral coding assistants that forget everything between sessions, Letta Code’s agents programmatically rewrite their own context — system prompts, skill libraries, and memory blocks — so they become more effective the longer they are used.

The project ships as a CLI-first tool that installs via npm, but agents created in the terminal are immediately available through a cross-platform desktop app, a browser interface at chat.letta.com (including mobile), and messaging integrations for Slack, Telegram, Discord, and WhatsApp. State is either stored locally (fully offline, embedded stateful server) or synced through Constellation, Letta’s cloud relay, which lets the same agent be reached from any machine including GitHub Actions runners or cloud VMs.

Memory is backed by git: every write to a memory block is a commit, making the agent’s context fully auditable, diff-able, and syncable to any GitHub repository. The MemFS (Memory Filesystem) layer tracks skills, system prompt history, and memory blocks as plain files, meaning developers can inspect and edit agent memory directly with standard tooling. The ‘dreaming’ feature (from Letta’s published sleep-time compute research) lets agents run background compaction and reflection during idle periods to consolidate what they have learned.

Letta Code supports multi-agent workflows natively: agents can spawn built-in subagents (general-purpose, recall, fork, history-analyzer, reflection) or call any other agent — including themselves — as a subagent. Hooks allow custom scripts to run at key lifecycle points, cron schedules let agents work autonomously across time, and a permission system gives fine-grained control over which actions are auto-approved.

What You Get

• A CLI-first coding agent installable via npm that works with any LLM — Claude, GPT-4o, Gemini, GLM, Kimi, Ollama, LM Studio, and more
• Persistent memory backed by git, where every memory write is a commit and the full agent context is auditable and syncable to any GitHub repository
• Cross-platform access: same agent available from the terminal, macOS/Windows/Linux desktop app, browser at chat.letta.com, and Slack/Telegram/Discord channels
• Skill system with global, project-scoped, and agent-scoped skills installable from GitHub or skill hubs like ClawHub and Hermes Skills Hub
• Multi-agent orchestration with built-in subagents (recall, fork, reflection, history-analyzer) and the ability to call any agent as a subagent synchronously or asynchronously
• Sleep-time dreaming for background memory compaction and reflection during idle periods, based on published sleep-time compute research
• Hooks and cron scheduling for autonomous background work and integration into CI/CD pipelines like GitHub Actions
• Full offline local mode with an embedded stateful agent server — no cloud account required

Common Use Cases

• Long-running development sessions where the agent remembers project conventions, past decisions, and learned preferences across days or weeks
• Cross-device development workflows where the same agent follows you from laptop to remote VM to mobile via Constellation sync
• Team messaging integrations where the same coding agent is accessible from a shared Slack or Discord channel
• Automated background tasks using cron triggers and GitHub Actions, with the agent running headlessly on a remote environment
• Multi-agent pipelines where a top-level agent orchestrates specialized recall, reflection, or fork subagents to handle complex tasks
• Local inference setups using Ollama, LM Studio, or llama-cpp with custom provider timeouts for slow local models

Under The Hood

Architecture Letta Code follows a layered, modular architecture with clear separation between the CLI presentation layer, the agent orchestration core, and the backend abstraction. The entry point at src/index.ts bootstraps CLI arg parsing (src/cli/args.ts), resolves the backend mode (Constellation API vs embedded local server via src/backend/), then hands control to either an interactive TUI session or a headless runner. The agent layer (src/agent/) handles all stateful concerns — memory reads and writes, model selection, skill loading, subagent spawning, and approval gating — while the websocket layer (src/websocket/) manages streaming protocol and concurrency between the agent runtime and client listeners. The channel system (src/channels/) is a plugin registry that adapts Slack, Telegram, Discord, and WhatsApp messages into a common MessageChannel interface, and hooks (src/hooks/) inject custom scripts at lifecycle boundaries. The result is a modular pipeline: input arrives via any channel, flows through the approval layer, executes against the Letta API or local backend, and emits streaming output back to the originating surface.

Tech Stack The project is written entirely in TypeScript targeting Node.js >=22.19.0 and built with Bun as both the package manager and runtime (bun@1.3.0). The published npm package (@letta-ai/letta-code v0.27.11) ships a pre-built letta.js binary. The terminal UI is built with Ink 5 (React-based TUI framework) using react 18.2, ink-spinner, and ink-text-input. Streaming LLM communication goes through @letta-ai/letta-client (the official Letta API SDK). Syntax highlighting uses Shiki 4, terminal PTY is handled by node-pty, and real-time git transport for MemFS uses the execFile Node API wrapping standard git commands. Code quality tooling uses Biome 2.2.5 for linting and formatting with no ESLint. Bundling is handled by a custom build.js script. Channel bots use grammy (Telegram), @slack/bolt, and a custom Discord adapter.

Code Quality Letta Code maintains an extensive automated test suite of over 400 test files spanning unit tests, integration tests, and headless smoke tests — covering memory git operations, approval flows, subagent lifecycle, websocket concurrency, skill import/export, and channel adapters. Custom architectural enforcement scripts (scripts/check-layer-boundaries.js, scripts/check-cycles, scripts/check-filename-casing.js, scripts/check-test-mock-isolation.js) run as part of the CI check suite to prevent dependency inversions and circular imports. Biome enforces strict linting rules including noDefaultExport and singleton-safe import paths (guarding against bundler duplication bugs). TypeScript strict mode is enabled throughout. The combination of abundant tests, automated architecture checks, and strict typing represents a high standard of code quality discipline unusual in young open-source projects.

What Makes It Unique The core innovation is that Letta Code agents are stateful entities that improve themselves: they use memory blocks to rewrite their own system prompts, accumulate skills as Markdown files tracked in a git-backed filesystem (MemFS), and run sleep-time dreaming (background compaction via a published compute technique from Letta’s research) to consolidate learned context between sessions. No other general-purpose coding agent provides a self-modifying, git-auditable memory layer as a first-class primitive. The architecture of treating agent memory as a git repository that can be synced to GitHub — and making every memory write a commit — is a genuinely novel approach to agent state management that makes context observable, portable, and rollback-safe.

Self-Hosting

Licensing Model Apache-2.0 licensed — all features available in self-hosted deployments with no restrictions or license keys required.

Self-Hosting Restrictions

• None. The full feature set, including MemFS, hooks, subagents, and multi-agent orchestration, is available locally without any license key.
• Local mode (--backend local) runs an embedded stateful agent server with no external dependencies.

Cloud vs Self-Hosted Constellation (Letta’s cloud relay) adds cross-device agent sync, remote environment management, and the ability to interact via chat.letta.com or the desktop app. These are convenience features; all core agent capabilities run fully locally. Constellation login is optional — the tool explicitly presents a local-first path on first run.