How to Configure a Different Agent Per Project Using LETTA_AGENT_ID with direnv

Yes, you can configure a different Letta agent for each project by setting the LETTA_AGENT_ID environment variable in a .envrc file, which direnv automatically loads when you enter the directory.

The Claude Subconscious plugin supports per-project agent isolation through environment variable overrides. By combining LETTA_AGENT_ID with direnv, you can bypass the global agent configuration stored in ~/.letta/claude-subconscious/config.json and automatically switch agents based on your current working directory. This guide explains the selection logic implemented in scripts/agent_config.ts and provides the exact configuration steps to isolate agents per repository.

How LETTA_AGENT_ID Selection Works

The plugin selects which Letta agent to use through a strict precedence hierarchy defined in scripts/agent_config.ts. Understanding this order is essential for troubleshooting multi-project setups.

The selection logic follows this priority:

1. LETTA_AGENT_ID environment variable — Highest priority; overrides all other settings
2. Saved agent ID in global config — Located at ~/.letta/claude-subconscious/config.json
3. Bundled Subconscious agent fallback — Imports the default agent if neither above is present

// scripts/agent_config.ts – agent selection hierarchy
if (process.env.LETTA_AGENT_ID) {
  // Environment variable takes precedence
} else if (config.agentId) {
  // Use globally saved agent ID
} else {
  // Import bundled default agent
}

When LETTA_AGENT_ID is present, the plugin validates the value against the required UUID format (agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) before establishing the connection. If validation fails, the plugin emits a warning and aborts rather than falling back silently.

Setting Up direnv for Per-Project Agents

The README explicitly recommends direnv for multi-project workflows. As noted in README.md, lines 168-174: "To use a different agent per project, set LETTA_AGENT_ID in your shell or via direnv."

Step 1: Create the .envrc File

Create a .envrc file in the root directory of any project requiring a specific agent:

# .envrc – place in project root

export LETTA_AGENT_ID="agent-1234abcd-12ab-34cd-56ef-1234567890ab"

Replace the UUID with your actual Letta agent identifier. This file exports the variable only when you navigate into this directory or its subdirectories.

Step 2: Allow the Configuration

Run the following command once per project to authorize direnv to load the file:

direnv allow .

This creates a security signature preventing unauthorized execution of untrusted .envrc files.

Step 3: Verify the Agent Selection

When you cd into the project directory, direnv exports LETTA_AGENT_ID automatically. The plugin logs its selection source to the console or hook logs ($TMPDIR/letta-claude-sync-*/send_worker_sdk.log):

Using agent ID from LETTA_AGENT_ID: agent-1234abcd-12ab-34cd-56ef-1234567890ab

If you see this message, the per-project configuration is active.

Validation and Error Handling

The plugin implements strict validation in scripts/agent_config.ts to prevent misconfiguration.

UUID Format Enforcement: The plugin checks that LETTA_AGENT_ID matches the pattern agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. If you provide an invalid format, the plugin warns and stops:

WARNING: Invalid LETTA_AGENT_ID format: "my-agent"

Fallback Behavior: If you remove the .envrc file or disable direnv, the plugin automatically falls back to the global agent ID stored in ~/.letta/claude-subconscious/config.json. No manual intervention is required to restore the default behavior.

Summary

• Environment variables override global config: LETTA_AGENT_ID takes precedence over ~/.letta/claude-subconscious/config.json according to the hierarchy in scripts/agent_config.ts.
• direnv enables per-project isolation: Creating a .envrc file with export LETTA_AGENT_ID automatically switches agents when entering project directories.
• Validation prevents errors: The plugin validates UUID format before connecting and provides clear warnings for malformed IDs.
• Zero-configuration fallback: Removing the .envrc file restores the global agent without additional steps.

Frequently Asked Questions

What happens if LETTA_AGENT_ID is malformed?

The plugin validates the ID format in scripts/agent_config.ts and emits a warning message: WARNING: Invalid LETTA_AGENT_ID format. It will not fall back to the global agent automatically; you must fix the environment variable or remove it to restore the global configuration.

Can I use a .env file instead of direnv?

The Claude Subconscious plugin only checks actual environment variables via process.env.LETTA_AGENT_ID as implemented in scripts/agent_config.ts. Standard .env files are not automatically sourced into the shell environment. You must use a tool like direnv that exports variables to the parent shell, or manually export the variable before launching Claude Code.

Where is the global agent ID stored?

When no LETTA_AGENT_ID environment variable is present, the plugin reads from ~/.letta/claude-subconscious/config.json. This file is created automatically when you first run the plugin and stores the default agent ID for all projects without per-project overrides.

Does the plugin support multiple agents simultaneously?

No, the plugin maintains a single active agent connection per Claude Code session. The LETTA_AGENT_ID variable determines which single agent to use for that session. To work with multiple agents, you must switch directories (triggering direnv) or manually change the environment variable before starting Claude Code.

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