# How the Claude Subconscious Auto-Import Process Works Without LETTA_AGENT_ID

> Discover how the Claude Subconscious auto import process functions without LETTA_AGENT_ID. Learn how it automatically provisions the Subconscious.af agent for Letta.

- Repository: [Letta/claude-subconscious](https://github.com/letta-ai/claude-subconscious)
- Tags: internals
- Published: 2026-03-26

---

**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`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/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:

```typescript
// 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`](https://github.com/letta-ai/claude-subconscious/blob/main/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.