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

> Easily configure a different Letta agent per project using LETTA_AGENT_ID and direnv. Automatically set environment variables by loading .envrc files to manage multiple agents in your projects.

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

---

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

```ts
// 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](https://github.com/letta-ai/claude-subconscious/blob/main/README.md#L168-L174): *"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:

```bash

# .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:

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