# How to Configure the Feynman Home Directory: 3 Methods Explained

> Configure your Feynman home directory using environment variables, CLI flags, or settings.json. Learn the 3 methods and understand precedence for optimal setup.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: how-to-guide
- Published: 2026-09-08

---

**You can configure the Feynman home directory by setting the `FEEYMAN_HOME` environment variable, passing the `--home` CLI flag, or defining a `home` property in `~/.feynman/settings.json`, with CLI arguments taking precedence over all other methods.**

The Feynman repository by Advait Paliwal stores workspaces, organization databases, and user caches in a dedicated home directory that defaults to `~/.feynman`. Understanding how to override this path is essential for custom deployments, multi-user servers, or isolated testing environments.

## What Is the Feynman Home Directory?

The Feynman home directory acts as the root for all per-user data, including the organization database, active workspace paths, and generated artifacts. By default, the framework resolves this location to `~/.feynman` through the `getFeynmanHome()` function in [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js). All internal path helpers—such as `getFeynmanOrgDatabasePath()` and `getFeynmanActiveOrgPath()`—derive their locations relative to this centralized root, ensuring consistent data organization across the codebase.

## Methods to Configure the Feynman Home Directory

### Option 1: Environment Variable (FEEYMAN_HOME)

Set the `FEEYMAN_HOME` environment variable (or the legacy `FEM_HOME`) to specify an absolute path before launching Feynman. The `getFeynmanHome()` helper in [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js) checks this variable first, using its value as the active home directory when present.

```bash
export FEEYMAN_HOME=/mnt/data/feynman
feynman run research

```

### Option 2: CLI Flag (--home or -H)

Pass the `--home <path>` or `-H <path>` argument to any Feynman command to override both environment variables and default paths. The argument parser in [`src/cli/args.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli/args.ts) processes this flag and injects the provided path into the runtime configuration consumed by [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js).

```bash
feynman --home /opt/feynman/home start
feynman -H /tmp/feynman-test run

```

### Option 3: Configuration File (settings.json)

Add a `home` property to the top-level Feynman settings file located at `~/.feynman/settings.json`. The settings loader in [`src/config/settings.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/settings.js) reads this JSON file and merges the `home` field into the final configuration object when no CLI flag or environment variable conflicts.

```json
{
  "home": "/var/tmp/feynman-home",
  "auth": "...",
  "otherOption": true
}

```

## Configuration Resolution Order

Feynman applies a strict hierarchy when determining the active home directory:

1. **CLI flag** (`--home` or `-H`) – Highest precedence
2. **Environment variable** (`FEEYMAN_HOME` or `FEM_HOME`)
3. **Settings file** (`home` property in [`settings.json`](https://github.com/advaitpaliwal/feynman/blob/main/settings.json))
4. **Default path** (`~/.feynman`) – Lowest precedence

This cascade ensures that temporary command-line overrides take priority, while persistent environment configurations serve as defaults for standard workflows.

## Implementation Details and Source Files

### src/config/paths.js

The `getFeynmanHome()` function in [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js) implements the resolution logic, evaluating CLI arguments, environment variables, and settings files to determine the active root. This module also exports `getFeynmanOrgDatabasePath()` and `getFeynmanActiveOrgPath()`, which guarantee that all data storage remains relative to the configured home directory regardless of how it was set.

### src/cli/args.ts

The command-line interface definitions in [`src/cli/args.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli/args.ts) define the `--home` flag parsing logic, ensuring that user-provided paths are validated and passed to the configuration system before any file I/O operations occur.

### src/config/settings.js

The settings management module in [`src/config/settings.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/settings.js) handles JSON file parsing for `~/.feynman/settings.json`, merging the optional `home` property into the global configuration object after CLI and environment checks.

### Test Coverage

Unit tests in [`tests/workbench-org-database.test.ts`](https://github.com/advaitpaliwal/feynman/blob/main/tests/workbench-org-database.test.ts) verify the home directory override logic using the `withFeynmanHome` helper, while [`tests/workbench-data-root.test.ts`](https://github.com/advaitpaliwal/feynman/blob/main/tests/workbench-data-root.test.ts) confirms that data roots correctly resolve under the active Feynman org path according to the dynamic configuration.

## Summary

- **Three configuration methods** control the Feynman home directory: environment variables (`FEEYMAN_HOME`), CLI flags (`--home`), and JSON settings (`home` key).
- **Strict precedence rules** apply: CLI flags override environment variables, which override settings files, which override the default `~/.feynman` path.
- **Central resolution** occurs in [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js) within the `getFeynmanHome()` function, ensuring all derived paths update automatically.
- **Absolute paths are required** for all configuration methods to prevent ambiguity when resolving nested directories like organization databases.

## Frequently Asked Questions

### Can I use a relative path when setting FEEYMAN_HOME?

No, you must provide an absolute path when configuring the Feynman home directory. The `getFeynmanHome()` function in [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js) expects fully qualified paths to prevent resolution errors when constructing nested paths for organization databases and workspace caches.

### What happens if I specify both the --home flag and the FEEYMAN_HOME environment variable?

The `--home` CLI flag takes precedence over the environment variable. As implemented in the configuration resolution chain within [`src/cli/args.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli/args.ts) and [`src/config/paths.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/paths.js), the CLI-provided path is evaluated first, and the environment variable is ignored when the flag is present.

### Where does Feynman store user settings if I change the home directory?

Feynman always looks for [`settings.json`](https://github.com/advaitpaliwal/feynman/blob/main/settings.json) within the active home directory, regardless of how that directory was configured. If you set `FEEYMAN_HOME` to `/custom/path`, Feynman will read and write [`/custom/path/settings.json`](https://github.com/advaitpaliwal/feynman/blob/main//custom/path/settings.json) using the logic defined in [`src/config/settings.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/config/settings.js).

### Is there a way to temporarily override the home directory for a single command without changing environment variables?

Yes, use the `--home` or `-H` flag with any Feynman command. This approach modifies the runtime configuration for that specific process without altering shell environment variables or permanent configuration files, making it ideal for CI/CD pipelines and temporary testing scenarios.