How the Claude Subconscious Auto-Import Process Works Without LETTA_AGENT_ID

When LETTA_AGENT_ID is not configured, the Claude Subconscious plugin automatically imports the bundled Subconscious.af agent, provisions it on the Letta server, and persists the new ID to ~/.letta/claude-subconscious/config.json for future sessions.

The letta-ai/claude-subconscious repository eliminates manual agent setup by detecting missing configuration and seamlessly provisioning the default Subconscious agent. When you launch a Claude Code session without the LETTA_AGENT_ID environment variable or a saved agent identifier, the plugin triggers an auto-import process that ensures a working Letta agent is available immediately.

Entry Point and Configuration Detection

The auto-import process originates in scripts/session_start.ts at line 79, where the session hook invokes getAgentId() to resolve the target agent identifier.

The getAgentId() function performs a hierarchical lookup to determine the active agent:

1. Environment variable check – The function first inspects process.env.LETTA_AGENT_ID. If present, the value is validated and returned immediately.
2. Saved configuration check – If the environment variable is absent, the utility reads ~/.letta/claude-subconscious/config.json via readConfig(). A valid agentId stored in this file short-circuits the import logic.

Only when both sources return empty does the system trigger the auto-import routine.

The Auto-Import Execution Flow

When no existing ID is detected, getAgentId() invokes importAndSaveAgent() at line 591 in scripts/agent_config.ts. This function orchestrates the complete provisioning workflow.

Locating the Bundled Agent Definition

The import process first verifies that Subconscious.af exists in the package directory adjacent to the source tree. This file contains the complete agent definition required by the Letta server.

Server-Side Import and ID Generation

The function calls importDefaultAgent() (line 778), which:

• Reads the .af file contents
• Constructs a multipart/form-data POST request to the Letta server's POST /agents/import endpoint
• Parses the JSON response to extract the newly created agent_id

Agent Normalization and Tagging

After successful import, the helper performs two normalization steps:

• renameAgent() – Removes the automatic "_copy" suffix appended during import, restoring the agent's original name
• ensureRequiredAgentTags() – Attaches the mandatory tags git-memory-enabled and origin:claude-subconcious to ensure proper functionality within the Claude Code ecosystem

Persistent Configuration

Finally, saveConfig() writes the fresh agentId to ~/.letta/claude-subconscious/config.json. Subsequent sessions read this value, bypassing the import step entirely.

Model Verification and Fallback Selection

After obtaining an ID—whether from environment, config, or auto-import—getAgentId() calls ensureModelAvailable(). This utility confirms the agent's assigned LLM is present on the server and auto-selects a fallback model if the primary is unavailable. This step guarantees the agent is operational but does not alter the import logic itself.

Practical Example: Simulating a Fresh Environment

You can observe the auto-import behavior programmatically by clearing existing configuration:

// Clear environment variable to simulate fresh state
process.env.LETTA_AGENT_ID = undefined;

// Remove existing configuration directory
import * as fs from 'fs';
import * as path from 'path';
const cfgDir = path.join(process.env.HOME!, '.letta', 'claude-subconscious');
fs.rmSync(cfgDir, { recursive: true, force: true });

// Import the configuration utility
import { getAgentId } from './scripts/agent_config.js';

(async () => {
  const apiKey = 'YOUR_LETTA_API_KEY';
  // This triggers the auto-import sequence
  const agentId = await getAgentId(apiKey);
  console.log('Using agent ID:', agentId);
})();

Executing this code on a clean machine produces output indicating the import progression:

No agent configured - importing default Subconscious agent...
Imported agent: agent-1234abcd-5678-90ef-1234-56789abcdef0
Saved agent ID to /home/user/.letta/claude-subconscious/config.json
Using agent ID: agent-1234abcd-5678-90ef-1234-56789abcdef0

Summary

• The auto-import process activates only when LETTA_AGENT_ID is unset and ~/.letta/claude-subconscious/config.json contains no valid agentId.
• importAndSaveAgent() in scripts/agent_config.ts handles the complete provisioning workflow when triggered by getAgentId().
• The bundled Subconscious.af file is uploaded via POST /agents/import with multipart/form-data encoding to generate a new agent instance.
• Post-import normalization includes renaming the agent to remove the "_copy" suffix and applying required tags: git-memory-enabled and origin:claude-subconcious.
• The new agentId is persisted to disk via saveConfig(), ensuring subsequent sessions reuse the provisioned agent without re-importing.

Frequently Asked Questions

What happens if the Subconscious.af file is missing from the installation?

If the bundled Subconscious.af file is not found adjacent to the source tree, importAndSaveAgent() throws an error before attempting server communication. The plugin requires this file to provision the default agent; without it, you must manually specify LETTA_AGENT_ID pointing to an existing Letta agent.

Does the auto-import process overwrite an existing agent on the Letta server?

No. The POST /agents/import endpoint creates a new agent instance with a unique ID each time it is called. The auto-import logic then renames this new instance and tags it appropriately. It does not modify or replace any pre-existing agents on your Letta server.

Can I disable the auto-import behavior and force manual configuration?

Yes. By setting LETTA_AGENT_ID to a valid agent identifier before starting Claude Code, you bypass the getAgentId() lookup entirely. Alternatively, pre-populating ~/.letta/claude-subconscious/config.json with an agentId field prevents the auto-import path from executing.

Where is the agent ID stored after the initial auto-import?

The system writes the ID to ~/.letta/claude-subconscious/config.json using the saveConfig() utility. This JSON file resides in the user's home directory and serves as the persistent store for the plugin's configuration across all future Claude Code sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}