Skip to content
Back to search

claude-subconscious

MarketplaceWorks with Claude CodeGitHub

Give Claude Code a subconscious

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/letta-ai-claude-subconscious/badge.svg)](/listings/letta-ai-claude-subconscious)

HTML

<a href="/listings/letta-ai-claude-subconscious"><img src="/api/listings/letta-ai-claude-subconscious/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install from GitHub:

/plugin marketplace add letta-ai/claude-subconscious
/plugin install claude-subconscious@claude-subconscious

Updating

/plugin marketplace update
/plugin update claude-subconscious@claude-subconscious

Install from Source

Clone the repository:

git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious
npm install

Enable the plugin (from inside the cloned directory):

/plugin enable .

Or enable globally for all projects:

/plugin enable --global .

If running from a different directory, use the full path to the cloned repo.

Linux: tmpfs Workaround

If plugin installation fails with `EXDEV: cross-device link not permitted`, your `/tmp` is likely on a different filesystem (common on Ubuntu, Fedora, Arch). Set `TMPDIR` to work around this [Claude Code bug](https://github.com/anthropics/claude-code/issues/14799):

mkdir -p ~/.claude/tmp
export TMPDIR="$HOME/.claude/tmp"

Add to your shell profile (`~/.bashrc` or `~/.zshrc`) to make permanent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "claude-subconscious",
  3. "owner": {
  4. "name": "Letta",
  5. "url": "https://letta.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "claude-subconscious",
  10. "source": "./"
  11. }
  12. ]
  13. }
README.md · README · 454 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!IMPORTANT]
  2. > Claude Subconscious is demo app built using the Letta Code SDK, and is not intended to be used in production.
  3. >
  4. > If you want to use a coding agent that runs background subconscious agents, use [**Letta Code**](https://github.com/letta-ai/letta-code), which is also fully open source.
  5. >
  6. > Install the Letta Code CLI with `npm install -g @letta-ai/letta-code`, then use `letta` to launch.
  7. # Claude Subconscious
  8. A background agent that whispers to Claude Code. A subconscious agent that watches your sessions, reads your files, builds up memory over time, and whispers guidance back.
  9. ![evil claude](assets/evil-claude.jpeg)
  10. ## What Is This?
  11. Claude Code forgets everything between sessions. Claude Subconscious is a second agent running underneath — watching, learning, and whispering back:
  12. - **Watches** every Claude Code session transcript
  13. - **Reads your codebase** — explores files with Read, Grep, and Glob while processing transcripts
  14. - **Remembers** across sessions, projects, and time
  15. - **Whispers guidance** — surfaces context, patterns, and reminders before each prompt
  16. - **Never blocks** — runs in the background via the [Letta Code SDK](https://docs.letta.com/letta-code/sdk/)
  17. Not just a memory layer — a background agent with real tool access that gets smarter the more you use it.
  18. Using Letta's [Conversations](https://docs.letta.com/guides/agents/conversations/) feature, a single agent can serve multiple Claude Code sessions in parallel with shared memory across all of them.
  19. ## How It Works
  20. After each response, the transcript is sent to a Letta agent via the Letta Code SDK. The agent reads files, searches the web, updates its memory — then whispers back before the next prompt. Nothing is written to CLAUDE.md.
  21. ```
  22. ┌─────────────┐ ┌──────────────────────────┐
  23. │ Claude Code │◄────────►│ Letta Agent (background) │
  24. └─────────────┘ │ │
  25. │ │ Tools: Read, Grep, Glob │
  26. │ │ Memory: persistent │
  27. │ │ Web: search, fetch │
  28. │ └──────────────────────────┘
  29. │ │
  30. │ Session Start │
  31. ├───────────────────────►│ New session notification
  32. │ │
  33. │ Before each prompt │
  34. │◄───────────────────────┤ Whispers guidance → stdout
  35. │ │
  36. │ Before each tool use │
  37. │◄───────────────────────┤ Mid-workflow updates → stdout
  38. │ │
  39. │ After each response │
  40. ├───────────────────────►│ Transcript → SDK session (async)
  41. │ │ ↳ Reads files, updates memory
  42. ```
  43. ## Installation
  44. Install from GitHub:
  45. ```
  46. /plugin marketplace add letta-ai/claude-subconscious
  47. /plugin install claude-subconscious@claude-subconscious
  48. ```
  49. ### Updating
  50. ```
  51. /plugin marketplace update
  52. /plugin update claude-subconscious@claude-subconscious
  53. ```
  54. ### Install from Source
  55. Clone the repository:
  56. ```bash
  57. git clone https://github.com/letta-ai/claude-subconscious.git
  58. cd claude-subconscious
  59. npm install
  60. ```
  61. Enable the plugin (from inside the cloned directory):
  62. ```
  63. /plugin enable .
  64. ```
  65. Or enable globally for all projects:
  66. ```
  67. /plugin enable --global .
  68. ```
  69. If running from a different directory, use the full path to the cloned repo.
  70. ### Linux: tmpfs Workaround
  71. If plugin installation fails with `EXDEV: cross-device link not permitted`, your `/tmp` is likely on a different filesystem (common on Ubuntu, Fedora, Arch). Set `TMPDIR` to work around this [Claude Code bug](https://github.com/anthropics/claude-code/issues/14799):
  72. ```bash
  73. mkdir -p ~/.claude/tmp
  74. export TMPDIR="$HOME/.claude/tmp"
  75. ```
  76. Add to your shell profile (`~/.bashrc` or `~/.zshrc`) to make permanent.
  77. ## Configuration
  78. ### Required
  79. ```bash
  80. export LETTA_API_KEY="your-api-key"
  81. ```
  82. Get your API key from [app.letta.com](https://app.letta.com).
  83. ### Optional
  84. ```bash
  85. export LETTA_MODE="whisper" # Default. Or "full" for blocks + messages, "off" to disable
  86. export LETTA_AGENT_ID="agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  87. export LETTA_BASE_URL="http://localhost:8283" # For self-hosted Letta
  88. export LETTA_MODEL="anthropic/claude-sonnet-4-5" # Model override
  89. export LETTA_CONTEXT_WINDOW="1048576" # Context window size (e.g. 1M tokens)
  90. export LETTA_HOME="$HOME" # Consolidate .letta state to ~/.letta/
  91. export LETTA_SDK_TOOLS="read-only" # Or "full", "off"
  92. ```
  93. - `LETTA_MODE` - Controls what gets injected. `whisper` (default, messages only), `full` (blocks + messages), `off` (disable). See [Modes](#modes).
  94. - `LETTA_AGENT_ID` - If not set, the plugin automatically imports a default "Subconscious" agent on first use.
  95. - `LETTA_BASE_URL` - For self-hosted Letta servers. Defaults to `https://api.letta.com`.
  96. - `LETTA_MODEL` - Override the agent's model. Optional - the plugin auto-detects and selects from available models. See [Model Configuration](#model-configuration) below.
  97. - `LETTA_CONTEXT_WINDOW` - Override the agent's context window size (in tokens). Useful when `LETTA_MODEL` is set to a model with a large context window that differs from the server default. Example: `1048576` for 1M tokens.
  98. - `LETTA_HOME` - Base directory for plugin state files. Creates `{LETTA_HOME}/.letta/claude/` for session data and conversation mappings. Defaults to current working directory. Set to `$HOME` to consolidate all state in one location.
  99. - `LETTA_SDK_TOOLS` - Controls client-side tool access for the Subconscious agent. `read-only` (default), `full`, or `off`. See [SDK Tools](#sdk-tools).
  100. ### Modes
  101. The `LETTA_MODE` environment variable controls what gets injected into Claude's context:
  102. | Mode | What Claude sees | Use case |
  103. |------|-----------------|----------|
  104. | **`whisper`** (default) | Only messages from Sub | Lightweight — Sub speaks when it has something to say |
  105. | **`full`** | Memory blocks + messages | Full context — blocks on first prompt, diffs after |
  106. | **`off`** | Nothing | Disable hooks temporarily |
  107. Subconscious **never writes to CLAUDE.md** in any mode. All content is injected via stdout into the prompt context. If you have an existing CLAUDE.md with `<letta>` content from an older version, it will be cleaned up automatically.
  108. ### Agent Resolution Order
  109. 1. **Environment variable** - `LETTA_AGENT_ID` if set
  110. 2. **Saved config** - `~/.letta/claude-subconscious/config.json` if exists
  111. 3. **Auto-import** - Imports bundled `Subconscious.af` agent, saves ID for future use
  112. This means zero-config setup: just set `LETTA_API_KEY` and the plugin handles the rest.
  113. ### Multi-Project Usage
  114. **One agent, many projects.** The Subconscious agent is stored globally at `~/.letta/claude-subconscious/config.json`. When you use the plugin in different repos, they all share the same agent brain.
  115. ```
  116. ~/.letta/claude-subconscious/config.json → ONE agent ID (shared brain)
  117. ↓
  118. project-a/.letta/claude/ → Project A's conversation threads
  119. project-b/.letta/claude/ → Project B's conversation threads
  120. project-c/.letta/claude/ → Project C's conversation threads
  121. ```
  122. The `.letta/claude/` directories in each project are **conversation bookkeeping** (mapping Claude Code sessions to Letta conversations), not separate agents. Memory blocks are shared across all projects.
  123. To use a **different agent per project**, set `LETTA_AGENT_ID` in your shell or via [direnv](https://direnv.net/):
  124. ```bash
  125. # .envrc in project directory
  126. export LETTA_AGENT_ID="agent-xxx-for-this-project"
  127. ```
  128. ### Model Configuration
  129. The plugin **automatically detects available models** on your Letta server and configures the agent appropriately:
  130. 1. **Queries available models** from your Letta server (`GET /v1/models/`)
  131. 2. **Checks if the agent's model is available** on that server
  132. 3. **Auto-selects a fallback** if the current model isn't available
  133. #### Auto-Selection Priority
  134. When the agent's model isn't available, the plugin selects from available models in this order:
  135. 1. `letta/auto` (Letta Cloud auto-routing)
  136. 2. `anthropic/claude-sonnet-4-5` (recommended - best for agents)
  137. 3. `openai/gpt-4.1-mini` (good balance, 1M context, cheap)
  138. 4. `anthropic/claude-haiku-4-5` (fast Claude option)
  139. 5. `openai/gpt-5.2` (flagship fallback)
  140. 6. `google_ai/gemini-3-flash` (Google's balanced option)
  141. 7. `google_ai/gemini-2.5-flash` (fallback)
  142. 8. `minimax/MiniMax-M2.7` (MiniMax flagship, 1M context)
  143. 9. First available model on the server
  144. #### Manual Override
  145. To specify a particular model, set `LETTA_MODEL`:
  146. ```bash
  147. export LETTA_MODEL="anthropic/claude-sonnet-4-5"
  148. ```
  149. The model handle format is `provider/model`. Common options:
  150. | Provider | Example Models |
  151. |----------|----------------|
  152. | `letta` | `auto` (Letta Cloud auto-routing) |
  153. | `openai` | `gpt-5.2`, `gpt-5-nano`, `gpt-4.1-mini` |
  154. | `anthropic` | `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-haiku-4-5` |
  155. | `google_ai` | `gemini-3-flash`, `gemini-2.5-flash`, `gemini-2.5-pro` |
  156. | `minimax` | `MiniMax-M2.7` (1M context) |
  157. | `zai` | `glm-5` (Letta Cloud default, free) |
  158. If `LETTA_MODEL` is set but not available on the server, the plugin will warn you and fall back to auto-selection.
  159. The default bundled agent uses `zai/glm-5` (free on Letta Cloud). For better tool usage and reasoning, consider switching to a stronger model. You can change the model at any time via the [Agent Development Environment](https://app.letta.com) (ADE) or by setting `LETTA_MODEL`.
  160. **Note:** Ensure your Letta server has the appropriate API key configured for your chosen provider (e.g., `OPENAI_API_KEY` for OpenAI models).
  161. ## Default Subconscious Agent
  162. When no agent is configured, the plugin auto-imports a bundled "Subconscious" agent designed specifically for this use case.
  163. ### What It Does
  164. The default agent is a background agent that:
  165. - **Reads your code** — uses Read, Grep, and Glob to explore your codebase while processing transcripts
  166. - **Learns your preferences** from corrections, explicit statements, and patterns
  167. - **Tracks project context** — architecture decisions, known gotchas, pending items
  168. - **Provides guidance** via the `<letta_message>` block when it has something useful
  169. - **Searches the web** — can look things up to augment its context
  170. ### Memory Blocks
  171. The default agent Subconscious maintains 8 memory blocks:
  172. | Block | Purpose |
  173. |-------|---------|
  174. | `core_directives` | Role definition and behavioral guidelines |
  175. | `guidance` | Active guidance for the next session (syncs to Claude Code before each prompt) |
  176. | `user_preferences` | Learned coding style, tool preferences, communication style |
  177. | `project_context` | Codebase knowledge, architecture decisions, known gotchas |
  178. | `session_patterns` | Recurring behaviors, time-based patterns, common struggles |
  179. | `pending_items` | Unfinished work, explicit TODOs, follow-up items |
  180. | `self_improvement` | Guidelines for evolving memory architecture over time |
  181. | `tool_guidelines` | How to use available tools (memory, filesystem, web search) |
  182. If you set an alternative agent using `LETTA_AGENT_ID`, your agent will use its existing memory architecture.
  183. ### Communication Style
  184. Subconscious is configured to be:
  185. - **Observational** - "I noticed..." not "You should..."
  186. - **Concise** - Technical, no filler
  187. - **Present but not intrusive** - Empty guidance is fine; it won't manufacture content
  188. ### Two-Way Communication
  189. Claude Code can address the Subconscious agent directly in responses. The agent sees everything in the transcript and may respond on the next sync. It's designed for ongoing dialogue, not just one-way observation.
  190. ## Hooks
  191. The plugin uses four Claude Code hooks:
  192. | Hook | Script | Timeout | Purpose |
  193. |------|--------|---------|---------|
  194. | `SessionStart` | `session_start.ts` | 5s | Notifies agent, cleans up legacy CLAUDE.md |
  195. | `UserPromptSubmit` | `sync_letta_memory.ts` | 10s | Injects memory + messages via stdout |
  196. | `PreToolUse` | `pretool_sync.ts` | 5s | Mid-workflow updates via `additionalContext` |
  197. | `Stop` | `send_messages_to_letta.ts` | 120s | Spawns SDK worker to send transcript (async) |
  198. ### SessionStart
  199. When a new Claude Code session begins:
  200. - Creates a new Letta conversation (or reuses existing one for the session)
  201. - Sends session start notification with project path and timestamp
  202. - Cleans up any legacy `<letta>` content from CLAUDE.md
  203. - Saves session state for other hooks to reference
  204. ### UserPromptSubmit
  205. Before each prompt is processed:
  206. - Fetches agent's current memory blocks and messages
  207. - In `full` mode: injects all blocks on first prompt, diffs on subsequent prompts
  208. - In `whisper` mode: injects only messages from Sub
  209. ### PreToolUse
  210. Before each tool use:
  211. - Checks for new messages or memory changes since last sync
  212. - If updates found, injects them via `additionalContext`
  213. - Silent no-op if nothing changed
  214. ### SDK Tools
  215. By default, the Subconscious agent now gets **client-side tool access** via the [Letta Code SDK](https://docs.letta.com/letta-code/sdk/). Instead of being limited to memory operations, Sub can read your files, search the web, and explore your codebase while processing transcripts.
  216. **Configuration via `LETTA_SDK_TOOLS`:**
  217. | Mode | Tools Available | Use Case |
  218. |------|----------------|----------|
  219. | `read-only` (default) | `Read`, `Grep`, `Glob`, `web_search`, `fetch_webpage` | Safe background research and file reading |
  220. | `full` | All tools (Bash, Edit, Write, Task, etc.) | Full autonomy — Sub can make changes and spawn sub-agents |
  221. | `off` | None (memory-only) | Listen-only — Sub processes transcripts but has no client-side tools |
  222. In `full` mode, Sub can spawn sub-agents via the `Task` tool — dispatching parallel research or delegating work to other agents while Claude Code continues working.
  223. > **Note:** Requires `@letta-ai/letta-code-sdk` (installed as a dependency).
  224. ### Stop
  225. Uses an **async hook** pattern — runs in the background without blocking Claude Code:
  226. 1. Main hook (`send_messages_to_letta.ts`) runs quickly:
  227. - Parses the session transcript (JSONL format)
  228. - Extracts user messages, assistant responses, thinking blocks, and tool usage
  229. - Writes payload to a temp file
  230. - Spawns detached background worker
  231. - Exits immediately
  232. 2. Background worker (`send_worker_sdk.ts`) runs independently:
  233. - Opens a Letta Code SDK session, giving Sub client-side tools
  234. - Sub processes the transcript and can use Read/Grep/Glob to explore the codebase
  235. - Updates state on success
  236. - Cleans up temp file
  237. The Stop hook runs as an async hook, so it never blocks Claude Code.
  238. ## State Management
  239. The plugin stores state in two locations:
  240. ### Durable State (`.letta/claude/`)
  241. Persisted in your project directory (this is **conversation bookkeeping**, not a separate agent - see [Multi-Project Usage](#multi-project-usage)):
  242. - `conversations.json` - Maps Claude Code session IDs → Letta conversation IDs
  243. - `session-{id}.json` - Per-session state (last processed index, cached conversation ID)
  244. ### Temporary State (`$TMPDIR/letta-claude-sync-$UID/`)
  245. Log files for debugging:
  246. - `session_start.log` - Session initialization
  247. - `sync_letta_memory.log` - Memory sync operations
  248. - `send_messages.log` - Main Stop hook
  249. - `send_worker_sdk.log` - SDK background worker
  250. ## What Your Agent Receives
  251. ### Session Start Message
  252. ```
  253. [Session Start]
  254. Project: my-project
  255. Path: /Users/you/code/my-project
  256. Session: abc123
  257. Started: 2026-01-14T12:00:00Z
  258. A new Claude Code session has begun. I'll be sending you updates as the session progresses.
  259. ```
  260. ### Conversation Transcript
  261. Full transcript with:
  262. - User messages
  263. - Assistant responses (including thinking blocks)
  264. - Tool uses and results
  265. - Timestamps
  266. ## What Claude Sees
  267. All content is injected via stdout — nothing is written to disk. What Claude receives depends on the mode.
  268. ### Messages (whisper + full mode)
  269. Messages from your Subconscious agent are injected before each prompt:
  270. ```xml
  271. <letta_message from="Subconscious" timestamp="2026-01-26T20:37:14+00:00">
  272. You've asked about error handling in async contexts three times this week.
  273. Consider reviewing error handling architecture holistically.
  274. </letta_message>
  275. ```
  276. ### Memory Blocks (full mode only)
  277. On the first prompt of a session, all memory blocks are injected:
  278. ```xml
  279. <letta_context>
  280. Subconscious agent "herald" is observing this session.
  281. Supervise: https://app.letta.com/agents/agent-xxx?conversation=conv-xxx
  282. </letta_context>
  283. <letta_memory_blocks>
  284. <user_preferences description="Learned coding style and preferences.">
  285. Prefers explicit type annotations. Uses pnpm, not npm.
  286. </user_preferences>
  287. <project_context description="Codebase knowledge and architecture.">
  288. Working on claude-subconscious plugin. TypeScript, ESM modules.
  289. </project_context>
  290. </letta_memory_blocks>
  291. ```
  292. On subsequent prompts, only changed blocks are shown as diffs:
  293. ```xml
  294. <letta_memory_update>
  295. <pending_items status="modified">
  296. - Phase 1 test harness complete
  297. + Release prep complete: README fixed, .gitignore updated
  298. </pending_items>
  299. </letta_memory_update>
  300. ```
  301. ## First Run
  302. On first use, the agent starts with minimal context. It takes a few sessions before it has enough signal to provide useful guidance. Give it time — it reads your code, learns your patterns, and gets smarter the more it observes.
  303. ## Use Cases
  304. - **Persistent project context** — Agent reads your codebase and remembers it across sessions
  305. - **Learned preferences** — "This user always wants explicit type annotations"
  306. - **Cross-session continuity** — Pick up where you left off, with full context
  307. - **Background research** — Agent can search the web and read files while you work
  308. - **Pattern detection** — "You've been debugging auth for 2 hours, maybe step back?"
  309. - **Proactive codebase awareness** — Agent explores relevant files when it sees you working on a feature
  310. ## Debugging
  311. Check the log files if hooks aren't working. The log directory is user-specific (`$TMPDIR/letta-claude-sync-$UID/`):
  312. ```bash
  313. # Watch all logs (macOS/Linux)
  314. tail -f /tmp/letta-claude-sync-$(id -u)/*.log
  315. # Or specific logs
  316. tail -f /tmp/letta-claude-sync-$(id -u)/send_messages.log
  317. tail -f /tmp/letta-claude-sync-$(id -u)/send_worker_sdk.log
  318. ```
  319. ## API Notes
  320. - Memory sync requires `?include=agent.blocks` query parameter (Letta API doesn't include relationship fields by default)
  321. - All transcript delivery uses the [Letta Code SDK](https://docs.letta.com/letta-code/sdk/) — no raw API calls for message sending
  322. - The SDK worker streams the agent's full response before updating state
  323. ## License
  324. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.