How to Configure the Feynman Home Directory: 3 Methods Explained

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. 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 checks this variable first, using its value as the active home directory when present.

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 processes this flag and injects the provided path into the runtime configuration consumed by src/config/paths.js.

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 reads this JSON file and merges the home field into the final configuration object when no CLI flag or environment variable conflicts.

{
  "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)
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 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 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 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 verify the home directory override logic using the withFeynmanHome helper, while 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 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 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 and 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 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 using the logic defined in 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.

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