[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74834":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":15,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},74834,"claude-subconscious","letta-ai\u002Fclaude-subconscious","letta-ai","Give Claude Code a subconscious","https:\u002F\u002Fdocs.letta.com\u002Fletta-code",null,"TypeScript",2788,208,16,3,0,11,63,9,76.76,"MIT License",false,"main",true,[],"2026-06-12 04:01:16","> [!IMPORTANT]\n> Claude Subconscious is demo app built using the Letta Code SDK, and is not intended to be used in production.\n>\n> If you want to use a coding agent that runs background subconscious agents, use [**Letta Code**](https:\u002F\u002Fgithub.com\u002Fletta-ai\u002Fletta-code), which is also fully open source.\n>\n> Install the Letta Code CLI with `npm install -g @letta-ai\u002Fletta-code`, then use `letta` to launch.\n\n# Claude Subconscious\n\nA background agent that whispers to Claude Code. A subconcious agent that watches your sessions, reads your files, builds up memory over time, and whispers guidance back.\n\n![evil claude](assets\u002Fevil-claude.jpeg)\n\n## What Is This?\n\nClaude Code forgets everything between sessions. Claude Subconscious is a second agent running underneath — watching, learning, and whispering back:\n\n- **Watches** every Claude Code session transcript\n- **Reads your codebase** — explores files with Read, Grep, and Glob while processing transcripts\n- **Remembers** across sessions, projects, and time\n- **Whispers guidance** — surfaces context, patterns, and reminders before each prompt\n- **Never blocks** — runs in the background via the [Letta Code SDK](https:\u002F\u002Fdocs.letta.com\u002Fletta-code\u002Fsdk\u002F)\n\nNot just a memory layer — a background agent with real tool access that gets smarter the more you use it.\n\nUsing Letta's [Conversations](https:\u002F\u002Fdocs.letta.com\u002Fguides\u002Fagents\u002Fconversations\u002F) feature, a single agent can serve multiple Claude Code sessions in parallel with shared memory across all of them.\n\n## How It Works\n\nAfter 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.\n\n```\n┌─────────────┐          ┌──────────────────────────┐\n│ Claude Code │◄────────►│ Letta Agent (background)  │\n└─────────────┘          │                          │\n       │                 │  Tools: Read, Grep, Glob │\n       │                 │  Memory: persistent       │\n       │                 │  Web: search, fetch       │\n       │                 └──────────────────────────┘\n       │                        │\n       │   Session Start        │\n       ├───────────────────────►│ New session notification\n       │                        │\n       │   Before each prompt   │\n       │◄───────────────────────┤ Whispers guidance → stdout\n       │                        │\n       │   Before each tool use │\n       │◄───────────────────────┤ Mid-workflow updates → stdout\n       │                        │\n       │   After each response  │\n       ├───────────────────────►│ Transcript → SDK session (async)\n       │                        │  ↳ Reads files, updates memory\n```\n\n## Installation\n\nInstall from GitHub:\n\n```\n\u002Fplugin marketplace add letta-ai\u002Fclaude-subconscious\n\u002Fplugin install claude-subconscious@claude-subconscious\n```\n\n### Updating\n\n```\n\u002Fplugin marketplace update\n\u002Fplugin update claude-subconscious@claude-subconscious\n```\n\n### Install from Source\n\nClone the repository:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fletta-ai\u002Fclaude-subconscious.git\ncd claude-subconscious\nnpm install\n```\n\nEnable the plugin (from inside the cloned directory):\n\n```\n\u002Fplugin enable .\n```\n\nOr enable globally for all projects:\n\n```\n\u002Fplugin enable --global .\n```\n\nIf running from a different directory, use the full path to the cloned repo.\n\n### Linux: tmpfs Workaround\n\nIf plugin installation fails with `EXDEV: cross-device link not permitted`, your `\u002Ftmp` is likely on a different filesystem (common on Ubuntu, Fedora, Arch). Set `TMPDIR` to work around this [Claude Code bug](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code\u002Fissues\u002F14799):\n\n```bash\nmkdir -p ~\u002F.claude\u002Ftmp\nexport TMPDIR=\"$HOME\u002F.claude\u002Ftmp\"\n```\n\nAdd to your shell profile (`~\u002F.bashrc` or `~\u002F.zshrc`) to make permanent.\n\n## Configuration\n\n### Required\n\n```bash\nexport LETTA_API_KEY=\"your-api-key\"\n```\n\nGet your API key from [app.letta.com](https:\u002F\u002Fapp.letta.com).\n\n### Optional\n\n```bash\nexport LETTA_MODE=\"whisper\"    # Default. Or \"full\" for blocks + messages, \"off\" to disable\nexport LETTA_AGENT_ID=\"agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\nexport LETTA_BASE_URL=\"http:\u002F\u002Flocalhost:8283\"  # For self-hosted Letta\nexport LETTA_MODEL=\"anthropic\u002Fclaude-sonnet-4-5\"  # Model override\nexport LETTA_CONTEXT_WINDOW=\"1048576\"             # Context window size (e.g. 1M tokens)\nexport LETTA_HOME=\"$HOME\"      # Consolidate .letta state to ~\u002F.letta\u002F\nexport LETTA_SDK_TOOLS=\"read-only\"       # Or \"full\", \"off\"\n```\n\n- `LETTA_MODE` - Controls what gets injected. `whisper` (default, messages only), `full` (blocks + messages), `off` (disable). See [Modes](#modes).\n- `LETTA_AGENT_ID` - If not set, the plugin automatically imports a default \"Subconscious\" agent on first use.\n- `LETTA_BASE_URL` - For self-hosted Letta servers. Defaults to `https:\u002F\u002Fapi.letta.com`.\n- `LETTA_MODEL` - Override the agent's model. Optional - the plugin auto-detects and selects from available models. See [Model Configuration](#model-configuration) below.\n- `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.\n- `LETTA_HOME` - Base directory for plugin state files. Creates `{LETTA_HOME}\u002F.letta\u002Fclaude\u002F` for session data and conversation mappings. Defaults to current working directory. Set to `$HOME` to consolidate all state in one location.\n- `LETTA_SDK_TOOLS` - Controls client-side tool access for the Subconscious agent. `read-only` (default), `full`, or `off`. See [SDK Tools](#sdk-tools).\n\n### Modes\n\nThe `LETTA_MODE` environment variable controls what gets injected into Claude's context:\n\n| Mode | What Claude sees | Use case |\n|------|-----------------|----------|\n| **`whisper`** (default) | Only messages from Sub | Lightweight — Sub speaks when it has something to say |\n| **`full`** | Memory blocks + messages | Full context — blocks on first prompt, diffs after |\n| **`off`** | Nothing | Disable hooks temporarily |\n\nSubconscious **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 `\u003Cletta>` content from an older version, it will be cleaned up automatically.\n\n### Agent Resolution Order\n\n1. **Environment variable** - `LETTA_AGENT_ID` if set\n2. **Saved config** - `~\u002F.letta\u002Fclaude-subconscious\u002Fconfig.json` if exists\n3. **Auto-import** - Imports bundled `Subconscious.af` agent, saves ID for future use\n\nThis means zero-config setup: just set `LETTA_API_KEY` and the plugin handles the rest.\n\n### Multi-Project Usage\n\n**One agent, many projects.** The Subconscious agent is stored globally at `~\u002F.letta\u002Fclaude-subconscious\u002Fconfig.json`. When you use the plugin in different repos, they all share the same agent brain.\n\n```\n~\u002F.letta\u002Fclaude-subconscious\u002Fconfig.json  →  ONE agent ID (shared brain)\n                                               ↓\nproject-a\u002F.letta\u002Fclaude\u002F                  →  Project A's conversation threads\nproject-b\u002F.letta\u002Fclaude\u002F                  →  Project B's conversation threads\nproject-c\u002F.letta\u002Fclaude\u002F                  →  Project C's conversation threads\n```\n\nThe `.letta\u002Fclaude\u002F` directories in each project are **conversation bookkeeping** (mapping Claude Code sessions to Letta conversations), not separate agents. Memory blocks are shared across all projects.\n\nTo use a **different agent per project**, set `LETTA_AGENT_ID` in your shell or via [direnv](https:\u002F\u002Fdirenv.net\u002F):\n\n```bash\n# .envrc in project directory\nexport LETTA_AGENT_ID=\"agent-xxx-for-this-project\"\n```\n\n### Model Configuration\n\nThe plugin **automatically detects available models** on your Letta server and configures the agent appropriately:\n\n1. **Queries available models** from your Letta server (`GET \u002Fv1\u002Fmodels\u002F`)\n2. **Checks if the agent's model is available** on that server\n3. **Auto-selects a fallback** if the current model isn't available\n\n#### Auto-Selection Priority\n\nWhen the agent's model isn't available, the plugin selects from available models in this order:\n1. `letta\u002Fauto` (Letta Cloud auto-routing)\n2. `anthropic\u002Fclaude-sonnet-4-5` (recommended - best for agents)\n3. `openai\u002Fgpt-4.1-mini` (good balance, 1M context, cheap)\n4. `anthropic\u002Fclaude-haiku-4-5` (fast Claude option)\n5. `openai\u002Fgpt-5.2` (flagship fallback)\n6. `google_ai\u002Fgemini-3-flash` (Google's balanced option)\n7. `google_ai\u002Fgemini-2.5-flash` (fallback)\n8. `minimax\u002FMiniMax-M2.7` (MiniMax flagship, 1M context)\n9. First available model on the server\n\n#### Manual Override\n\nTo specify a particular model, set `LETTA_MODEL`:\n\n```bash\nexport LETTA_MODEL=\"anthropic\u002Fclaude-sonnet-4-5\"\n```\n\nThe model handle format is `provider\u002Fmodel`. Common options:\n\n| Provider | Example Models |\n|----------|----------------|\n| `letta` | `auto` (Letta Cloud auto-routing) |\n| `openai` | `gpt-5.2`, `gpt-5-nano`, `gpt-4.1-mini` |\n| `anthropic` | `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-haiku-4-5` |\n| `google_ai` | `gemini-3-flash`, `gemini-2.5-flash`, `gemini-2.5-pro` |\n| `minimax` | `MiniMax-M2.7` (1M context) |\n| `zai` | `glm-5` (Letta Cloud default, free) |\n\nIf `LETTA_MODEL` is set but not available on the server, the plugin will warn you and fall back to auto-selection.\n\nThe default bundled agent uses `zai\u002Fglm-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:\u002F\u002Fapp.letta.com) (ADE) or by setting `LETTA_MODEL`.\n\n**Note:** Ensure your Letta server has the appropriate API key configured for your chosen provider (e.g., `OPENAI_API_KEY` for OpenAI models).\n\n## Default Subconscious Agent\n\nWhen no agent is configured, the plugin auto-imports a bundled \"Subconscious\" agent designed specifically for this use case.\n\n### What It Does\n\nThe default agent is a background agent that:\n\n- **Reads your code** — uses Read, Grep, and Glob to explore your codebase while processing transcripts\n- **Learns your preferences** from corrections, explicit statements, and patterns\n- **Tracks project context** — architecture decisions, known gotchas, pending items\n- **Provides guidance** via the `\u003Cletta_message>` block when it has something useful\n- **Searches the web** — can look things up to augment its context\n\n### Memory Blocks\n\nThe default agent Subconscious maintains 8 memory blocks:\n\n| Block | Purpose |\n|-------|---------|\n| `core_directives` | Role definition and behavioral guidelines |\n| `guidance` | Active guidance for the next session (syncs to Claude Code before each prompt) |\n| `user_preferences` | Learned coding style, tool preferences, communication style |\n| `project_context` | Codebase knowledge, architecture decisions, known gotchas |\n| `session_patterns` | Recurring behaviors, time-based patterns, common struggles |\n| `pending_items` | Unfinished work, explicit TODOs, follow-up items |\n| `self_improvement` | Guidelines for evolving memory architecture over time |\n| `tool_guidelines` | How to use available tools (memory, filesystem, web search) |\n\nIf you set an alternative agent using `LETTA_AGENT_ID`, your agent will use its existing memory architecture.\n\n### Communication Style\n\nSubconscious is configured to be:\n\n- **Observational** - \"I noticed...\" not \"You should...\"\n- **Concise** - Technical, no filler\n- **Present but not intrusive** - Empty guidance is fine; it won't manufacture content\n\n### Two-Way Communication\n\nClaude 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.\n\n## Hooks\n\nThe plugin uses four Claude Code hooks:\n\n| Hook | Script | Timeout | Purpose |\n|------|--------|---------|---------|\n| `SessionStart` | `session_start.ts` | 5s | Notifies agent, cleans up legacy CLAUDE.md |\n| `UserPromptSubmit` | `sync_letta_memory.ts` | 10s | Injects memory + messages via stdout |\n| `PreToolUse` | `pretool_sync.ts` | 5s | Mid-workflow updates via `additionalContext` |\n| `Stop` | `send_messages_to_letta.ts` | 120s | Spawns SDK worker to send transcript (async) |\n\n### SessionStart\n\nWhen a new Claude Code session begins:\n- Creates a new Letta conversation (or reuses existing one for the session)\n- Sends session start notification with project path and timestamp\n- Cleans up any legacy `\u003Cletta>` content from CLAUDE.md\n- Saves session state for other hooks to reference\n\n### UserPromptSubmit\n\nBefore each prompt is processed:\n- Fetches agent's current memory blocks and messages\n- In `full` mode: injects all blocks on first prompt, diffs on subsequent prompts\n- In `whisper` mode: injects only messages from Sub\n\n### PreToolUse\n\nBefore each tool use:\n- Checks for new messages or memory changes since last sync\n- If updates found, injects them via `additionalContext`\n- Silent no-op if nothing changed\n\n### SDK Tools\n\nBy default, the Subconscious agent now gets **client-side tool access** via the [Letta Code SDK](https:\u002F\u002Fdocs.letta.com\u002Fletta-code\u002Fsdk\u002F). Instead of being limited to memory operations, Sub can read your files, search the web, and explore your codebase while processing transcripts.\n\n**Configuration via `LETTA_SDK_TOOLS`:**\n\n| Mode | Tools Available | Use Case |\n|------|----------------|----------|\n| `read-only` (default) | `Read`, `Grep`, `Glob`, `web_search`, `fetch_webpage` | Safe background research and file reading |\n| `full` | All tools (Bash, Edit, Write, Task, etc.) | Full autonomy — Sub can make changes and spawn sub-agents |\n| `off` | None (memory-only) | Listen-only — Sub processes transcripts but has no client-side tools |\n\nIn `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.\n\n> **Note:** Requires `@letta-ai\u002Fletta-code-sdk` (installed as a dependency).\n\n### Stop\n\nUses an **async hook** pattern — runs in the background without blocking Claude Code:\n\n1. Main hook (`send_messages_to_letta.ts`) runs quickly:\n   - Parses the session transcript (JSONL format)\n   - Extracts user messages, assistant responses, thinking blocks, and tool usage\n   - Writes payload to a temp file\n   - Spawns detached background worker\n   - Exits immediately\n\n2. Background worker (`send_worker_sdk.ts`) runs independently:\n   - Opens a Letta Code SDK session, giving Sub client-side tools\n   - Sub processes the transcript and can use Read\u002FGrep\u002FGlob to explore the codebase\n   - Updates state on success\n   - Cleans up temp file\n\nThe Stop hook runs as an async hook, so it never blocks Claude Code.\n\n## State Management\n\nThe plugin stores state in two locations:\n\n### Durable State (`.letta\u002Fclaude\u002F`)\n\nPersisted in your project directory (this is **conversation bookkeeping**, not a separate agent - see [Multi-Project Usage](#multi-project-usage)):\n- `conversations.json` - Maps Claude Code session IDs → Letta conversation IDs\n- `session-{id}.json` - Per-session state (last processed index, cached conversation ID)\n\n### Temporary State (`$TMPDIR\u002Fletta-claude-sync-$UID\u002F`)\n\nLog files for debugging:\n- `session_start.log` - Session initialization\n- `sync_letta_memory.log` - Memory sync operations\n- `send_messages.log` - Main Stop hook\n- `send_worker_sdk.log` - SDK background worker\n\n## What Your Agent Receives\n\n### Session Start Message\n\n```\n[Session Start]\nProject: my-project\nPath: \u002FUsers\u002Fyou\u002Fcode\u002Fmy-project\nSession: abc123\nStarted: 2026-01-14T12:00:00Z\n\nA new Claude Code session has begun. I'll be sending you updates as the session progresses.\n```\n\n### Conversation Transcript\n\nFull transcript with:\n- User messages\n- Assistant responses (including thinking blocks)\n- Tool uses and results\n- Timestamps\n\n## What Claude Sees\n\nAll content is injected via stdout — nothing is written to disk. What Claude receives depends on the mode.\n\n### Messages (whisper + full mode)\n\nMessages from your Subconscious agent are injected before each prompt:\n\n```xml\n\u003Cletta_message from=\"Subconscious\" timestamp=\"2026-01-26T20:37:14+00:00\">\nYou've asked about error handling in async contexts three times this week.\nConsider reviewing error handling architecture holistically.\n\u003C\u002Fletta_message>\n```\n\n### Memory Blocks (full mode only)\n\nOn the first prompt of a session, all memory blocks are injected:\n\n```xml\n\u003Cletta_context>\nSubconscious agent \"herald\" is observing this session.\nSupervise: https:\u002F\u002Fapp.letta.com\u002Fagents\u002Fagent-xxx?conversation=conv-xxx\n\u003C\u002Fletta_context>\n\n\u003Cletta_memory_blocks>\n\u003Cuser_preferences description=\"Learned coding style and preferences.\">\nPrefers explicit type annotations. Uses pnpm, not npm.\n\u003C\u002Fuser_preferences>\n\u003Cproject_context description=\"Codebase knowledge and architecture.\">\nWorking on claude-subconscious plugin. TypeScript, ESM modules.\n\u003C\u002Fproject_context>\n\u003C\u002Fletta_memory_blocks>\n```\n\nOn subsequent prompts, only changed blocks are shown as diffs:\n\n```xml\n\u003Cletta_memory_update>\n\u003Cpending_items status=\"modified\">\n- Phase 1 test harness complete\n+ Release prep complete: README fixed, .gitignore updated\n\u003C\u002Fpending_items>\n\u003C\u002Fletta_memory_update>\n```\n\n## First Run\n\nOn 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.\n\n## Use Cases\n\n- **Persistent project context** — Agent reads your codebase and remembers it across sessions\n- **Learned preferences** — \"This user always wants explicit type annotations\"\n- **Cross-session continuity** — Pick up where you left off, with full context\n- **Background research** — Agent can search the web and read files while you work\n- **Pattern detection** — \"You've been debugging auth for 2 hours, maybe step back?\"\n- **Proactive codebase awareness** — Agent explores relevant files when it sees you working on a feature\n\n## Debugging\n\nCheck the log files if hooks aren't working. The log directory is user-specific (`$TMPDIR\u002Fletta-claude-sync-$UID\u002F`):\n\n```bash\n# Watch all logs (macOS\u002FLinux)\ntail -f \u002Ftmp\u002Fletta-claude-sync-$(id -u)\u002F*.log\n\n# Or specific logs\ntail -f \u002Ftmp\u002Fletta-claude-sync-$(id -u)\u002Fsend_messages.log\ntail -f \u002Ftmp\u002Fletta-claude-sync-$(id -u)\u002Fsend_worker_sdk.log\n```\n\n## API Notes\n\n- Memory sync requires `?include=agent.blocks` query parameter (Letta API doesn't include relationship fields by default)\n- All transcript delivery uses the [Letta Code SDK](https:\u002F\u002Fdocs.letta.com\u002Fletta-code\u002Fsdk\u002F) — no raw API calls for message sending\n- The SDK worker streams the agent's full response before updating state\n\n## License\n\nMIT\n","Claude Subconscious 是一个基于Letta Code SDK构建的后台代理程序，旨在为Claude Code提供持续的记忆和辅助功能。它通过监视每个Claude Code会话、读取代码库文件，并随着时间积累记忆，在每次用户输入前给出建议或提醒，且不会阻塞主进程操作。该工具采用TypeScript编写，支持文件读取、模式匹配及网络搜索等高级特性，使开发者能够更高效地进行编程工作。适用于需要跨会话保持上下文理解能力，以及希望在开发过程中获得智能提示与指导的场景。请注意，此项目作为演示用途设计，并不推荐直接用于生产环境。",2,"2026-06-11 03:51:01","high_star"]