letta-ai/claude-subconscious: a background Letta agent that whispers into Claude Code
Give Claude Code a subconscious
At a glance
- What is it?
- Claude Subconscious is a demo plugin built on the Letta Code SDK that watches Claude Code transcripts, reads your files through Read, Grep and Glob, keeps memory across sessions, and injects guidance via stdout. It is explicitly not intended for production; Letta Code is the maintained alternative.
- Who is it for?
- Claude Subconscious is worth installing if you want to see what a background agent with real tool access looks like next to Claude Code, and you accept the README's own warning that it is a demo app and not intended for production. Skip it if you need a coding agent that runs background subconscious agents in real work; the README points those users to Letta Code, installed with npm install -g @letta-ai/letta-code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 20, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Claude Subconscious is aimed at
Claude Code starts each session without the previous one. The README states this plainly: Claude Code forgets everything between sessions. The plugin's answer is a second agent that runs underneath the first, watching transcripts, exploring the repository with Read, Grep and Glob, accumulating memory over time, and whispering guidance back before the next prompt.
The intended user is someone already working in Claude Code who wants context carried forward without hand-maintaining a CLAUDE.md. The README is explicit that nothing is written to CLAUDE.md in any mode, and that content from older versions with a <letta> block is cleaned up automatically. That design choice matters more than it looks: a file that Claude Code loads as project instructions is visible to the whole team and lives in version control, while stdout injection is per-session and leaves no artifact behind.
The README also frames the scope honestly. The first line calls Claude Subconscious a demo app built using the Letta Code SDK, not intended to be used in production, and points to Letta Code for anyone who wants a coding agent that runs background subconscious agents. Treat this repository as a working demonstration of the pattern, not as infrastructure.
Transcript in, whisper out: the actual loop
The mechanism is a hook loop around Claude Code, with a Letta agent on the other side of the Letta Code SDK. Four events are described in the README's diagram. On session start, the plugin sends a new session notification. Before each prompt, the agent whispers guidance to stdout. Before each tool use, it can push mid-workflow updates to stdout. After each response, the transcript is sent to the agent asynchronously, and the agent reads files, searches the web and updates its memory.
Two details do most of the work here. The first is that the transcript upload is async, so the agent's file reading and memory writing do not sit in the path of your next prompt. The second is that the agent has real tool access rather than being a summarizer: Read, Grep and Glob on the client side, plus web search and fetch. The README calls it a background agent with real tool access, not just a memory layer, and the distinction is fair.
The README notes that Letta's Conversations feature lets a single agent serve multiple Claude Code sessions in parallel with shared memory across all of them. That is what makes the global config file coherent rather than sloppy: one agent ID, many repositories, one accumulated brain.
Installing the plugin and getting a first whisper
The README gives a plugin-marketplace path and a from-source path. The marketplace path is two commands inside Claude Code, which add the repository as a marketplace and then install the plugin from it.
/plugin marketplace add letta-ai/claude-subconscious
/plugin install claude-subconscious@claude-subconsciousBefore any of that, the plugin needs an API key. The README lists LETTA_API_KEY under Required and says to get it from app.letta.com.
export LETTA_API_KEY="your-api-key"With the key exported in the environment Claude Code inherits, the README describes zero-config setup: if LETTA_AGENT_ID is not set and no saved config exists, the plugin imports the bundled Subconscious.af agent on first use and stores the ID. The resolution order is the environment variable, then ~/.letta/claude-subconscious/config.json, then auto-import. What you should see is the agent speaking on stdout before a prompt when it has something to say; in the default whisper mode, that is the only channel it uses.
The from-source route is for people who want to modify the plugin. Clone, install, then enable from inside the cloned directory, or globally for all projects.
git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious
npm install/plugin enable .On Linux, the README documents a failure mode worth knowing before you file a bug: if installation fails with EXDEV: cross-device link not permitted, /tmp is probably on a different filesystem, common on Ubuntu, Fedora and Arch. The workaround is to point TMPDIR at a directory under your Claude config.
export TMPDIR="$HOME/.claude/tmp"Modes, tools and the limits you should read before enabling full
LETTA_MODE decides how much the agent is allowed to put in front of Claude. The default, whisper, injects messages only, so the agent speaks when it has something to say. full injects memory blocks plus messages, with blocks on the first prompt and diffs after. off disables the hooks temporarily without uninstalling anything.
LETTA_SDK_TOOLS is the other dial, and it is the one to think about. It controls client-side tool access for the Subconscious agent and accepts read-only (the default), full or off. Read-only is the sensible default because the agent is reading your codebase on every transcript, and widening that to full hands a background process more reach than most people want in a demo. The README does not spell out what full adds beyond the read-only set, and that silence is a reason to leave it alone unless you have read the hooks yourself.
The bigger limitation is stated by the project, not inferred. The README's opening callout says Claude Subconscious is a demo app built using the Letta Code SDK and is not intended to be used in production. There is also a real cost shape: every response sends a transcript to a Letta agent that then reads files, searches the web and rewrites memory. That is paid API traffic and token consumption proportional to how much you type, and the plugin is the wrong tool if you want a local-only memory layer with no network round trip. The README documents LETTA_BASE_URL for self-hosted Letta servers, which is the route for anyone who needs the agent to stay inside their own network, but the client-side tool access and the transcript flow still exist either way.
How it differs from Letta Code and from static memory files
The alternative the project itself names is Letta Code, at github.com/letta-ai/letta-code, which the README describes as also fully open source and as the thing to use if you want a coding agent that runs background subconscious agents. The difference in approach is the direction of control. Claude Subconscious is a plugin that attaches to Claude Code and injects through hooks; Letta Code is a coding agent you launch yourself with the letta command after npm install -g @letta-ai/letta-code. If your goal is a background agent doing real work, the README is telling you that this repository is the demonstration and that one is the product.
The other comparison is the CLAUDE.md pattern that most Claude Code users reach for first. A CLAUDE.md is a static file you edit by hand, it is deterministic, it costs nothing per session, and it is reviewable in a pull request. Claude Subconscious is the opposite on every axis: it writes nothing to disk for Claude to read, it decides for itself what to surface, and its usefulness depends on an agent correctly judging what is worth whispering. Neither is strictly better. The static file is auditable; the background agent can notice a pattern across three sessions that you would never have thought to write down.
Maintenance, licence and what upgrading costs
The repository is not archived, and the last push was on 2026-09-10, which is recent enough that the code is being touched. The release history shows a different rhythm: v1.5.1 (Checkpoint Hooks & Splash Screen) on 2026-03-04, then v2.1.0 (SDK-only transport, memfs, and memory limits) and v2.1.1 (Bug fixes) both on 2026-03-30. Package.json carries version 2.1.1. So the tagged releases cluster in March while commits continue later, which is worth knowing if you pin to a tag rather than to main.
The v2.1.0 title, SDK-only transport, memfs, and memory limits, is the kind of change that can invalidate a setup built on an earlier version. The README's own upgrade path is the marketplace update pair, /plugin marketplace update followed by /plugin update claude-subconscious@claude-subconscious, and the from-source path is a git pull plus npm install. The README does not document rollback, so if you need to return to v1.5.1 behaviour, plan for it yourself.
Licensing is MIT, stated in both the repository licence file and the package.json license field. MIT is permissive and places few obligations on how you redistribute or modify the code. It says nothing about the Letta service you point the plugin at, or about the model behind LETTA_MODEL, and those are governed by their own terms. This is not legal advice; read the terms of the services you actually call.
Editorial conclusion
Claude Subconscious is worth installing if you want to see what a background agent with real tool access looks like next to Claude Code, and you accept the README's own warning that it is a demo app and not intended for production. Skip it if you need a coding agent that runs background subconscious agents in real work; the README points those users to Letta Code, installed with npm install -g @letta-ai/letta-code. Before adopting it, verify three things: that LETTA_API_KEY is set in the environment Claude Code inherits, that /plugin marketplace add letta-ai/claude-subconscious followed by /plugin install claude-subconscious@claude-subconscious resolves, and whether ~/.letta/claude-subconscious/config.json already holds an agent ID you did not create, because a shared brain is shared across every repo you open.
Frequently asked questions
What is Claude Subconscious?
It is a demo app built on the Letta Code SDK that runs a background Letta agent alongside Claude Code. The agent watches session transcripts, reads files with Read, Grep and Glob, keeps memory across sessions, and whispers guidance back to stdout.
How do I install letta-ai/claude-subconscious?
The README gives two routes. Inside Claude Code, run /plugin marketplace add letta-ai/claude-subconscious and then /plugin install claude-subconscious@claude-subconscious; alternatively clone the repository, run npm install, and enable it with /plugin enable . from inside the cloned directory.
Does Claude Subconscious write to CLAUDE.md?
No. The README states that Subconscious never writes to CLAUDE.md in any mode, and that all content is injected via stdout into the prompt context. It also says existing CLAUDE.md content in a <letta> block from an older version is cleaned up automatically.
Is Claude Subconscious safe to run in production?
The README's opening callout says it is a demo app built using the Letta Code SDK and is not intended to be used in production. For a coding agent that runs background subconscious agents, the README points to Letta Code instead.
Why does plugin installation fail on Linux with EXDEV?
The README attributes an EXDEV: cross-device link not permitted error to /tmp sitting on a different filesystem, which it calls common on Ubuntu, Fedora and Arch. The documented workaround is to create ~/.claude/tmp and set TMPDIR to that directory.
Community notes