feat: support configurable OpenWiki state directory

[Krish (akyourowngames)]

Summary

Adds OPENWIKI_CONFIG_DIR as an override for OpenWiki's local state directory. Credentials, the personal wiki, connectors, and skills now use the same resolved directory; the default remains ~/.openwiki.

Agent prompts, ingestion instructions, connector-tool descriptions, and the CLI output panel use the configured location when it is overridden, so agents do not attempt to read the default home directory.

Fixes #223.

Why

Containerized and read-only-home environments currently fail before documentation work begins because OpenWiki always writes to the user's home directory. The override lets users supply a writable mounted location without changing default behavior.

Testing

• tsc --noEmit -p tsconfig.json
• ESLint on changed files
• vitest run --pool=threads — 181 tests passed
• tsc -p tsconfig.json

The repository-wide Prettier check reports pre-existing line-ending issues across the untouched upstream checkout; git diff --check passes.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Krish (akyourowngames)]

Ready for review.

This change adds OPENWIKI_CONFIG_DIR to relocate OpenWiki's local state while retaining ~/.openwiki as the default. The override is shared by credentials, the personal wiki, connectors, and skills. Agent prompts, ingestion instructions, connector-tool descriptions, and the CLI output path also honor the configured directory.

Validated with typecheck, lint, build, and the full Vitest suite (181 tests).

[Zelys (Zelys-DFKH)]

This is a solid design, especially the display-path split (openWikiHomeDisplayPath etc.) for keeping messages accurate without changing the resolved directory logic. That's a cleaner approach than I'd have picked.

One gap I noticed while working on something similar: resolveOpenWikiHomeDir calls path.resolve(configuredDir) directly, so a bare ~ or ~/-prefixed value in OPENWIKI_CONFIG_DIR won't expand to the home directory. Node's path.resolve doesn't know about ~, and several environments that set env vars (PowerShell, docker-compose, a hand-edited .env file) don't expand it either, so OPENWIKI_CONFIG_DIR=~/openwiki-state would resolve relative to the process cwd instead of the home directory, something like <cwd>/~/openwiki-state. Worth special-casing ~ and ~//~\ before the path.resolve call, the same way normalizeLocalPath already does in credentials.tsx.

[Zelys (Zelys-DFKH)]

Great work on this, it's a clean approach to the state-directory relocation problem.

I noticed a couple of things while reviewing that might be worth addressing before merge:

1. In resolveOpenWikiHomeDir (src/openwiki-home.ts:13), path.resolve(configuredDir) doesn't expand a leading ~. If someone sets OPENWIKI_CONFIG_DIR=~/openwiki, it resolves to a literal ~ folder next to the current working directory instead of the home directory. Since the original ask (don't mess with my home directory #223, plus [Feature]: Change the default openwiki directory of person mode #471) was specifically about Windows users wanting to relocate off the C: drive, most folks will probably just use an absolute path like D:\openwiki, but ~ is such a natural thing to type that it's worth handling.

2. There are a couple of hardcoded ~/.openwiki/.env strings that don't reflect the configured location: src/credentials.tsx:4222 ("Saved to ~/.openwiki/.env as {apiKeyEnv}...") and src/telemetry/config.ts:37 (the telemetry opt-out message). Anyone who sets OPENWIKI_CONFIG_DIR would still see these old paths in the UI, which could send them looking in the wrong place.

Happy to help test this once you sort these out. Really appreciate you tackling this, it's a genuine quality-of-life improvement for users.

[Zelys (Zelys-DFKH)]

Great work on this, it's a clean approach to the state-directory relocation problem.

I noticed a couple of things while reviewing that might be worth addressing before merge:

1. In resolveOpenWikiHomeDir (src/openwiki-home.ts:13), path.resolve(configuredDir) doesn't expand a leading ~. If someone sets OPENWIKI_CONFIG_DIR=~/openwiki, it resolves to a literal ~ folder next to the current working directory instead of the home directory. Since the original ask (don't mess with my home directory #223, plus [Feature]: Change the default openwiki directory of person mode #471) was specifically about Windows users wanting to relocate off the C: drive, most folks will probably just use an absolute path like D:\openwiki, but ~ is such a natural thing to type that it's worth handling.

2. There are a couple of hardcoded ~/.openwiki/.env strings that don't reflect the configured location: src/credentials.tsx:4222 ("Saved to ~/.openwiki/.env as {apiKeyEnv}...") and src/telemetry/config.ts:37 (the telemetry opt-out message). Anyone who sets OPENWIKI_CONFIG_DIR would still see these old paths in the UI, which could send them looking in the wrong place.

Happy to help test this once you sort these out. Really appreciate you tackling this, it's a genuine QoL improvement for users.

[Krish (akyourowngames)]

Working on this right now!!

[changeset-bot]

⚠️ No Changeset found

Latest commit: da542f5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Krish (akyourowngames)]

Addressed the review feedback and reconciled with upstream/main. The branch is mergeable again.

Review point 1 — tilde expansion in resolveOpenWikiHomeDir

Fixed. path.resolve does not expand a leading ~, so OPENWIKI_CONFIG_DIR=~/openwiki-state resolved relative to the cwd. src/openwiki-home.ts now expands ~ and ~//~\ (mirroring normalizeLocalPath) before resolving. Added two tests in test/openwiki-home.test.ts covering bare ~ and ~/-prefixed overrides; both pass.

Review point 2 — user-facing ~/.openwiki/.env strings

Fixed across the board via a new openWikiEnvDisplayPath display const (~/.openwiki/.env by default, the configured path when OPENWIKI_CONFIG_DIR is set):

• src/credentials.tsx — the "Saved to ~/.openwiki/.env as {apiKeyEnv}" message (the one you cited, now ~/.openwiki/.env → display path).
• src/cli.tsx — the auth-fix steps ("came from your shell, not …", "edit …", and the Bedrock/AWS SDK messages).
• src/auth/configure.ts — the Gmail connector note.
• src/connectors/sources/x.ts and src/connectors/sources/langsmith/index.ts — connector enable/key warnings.
• src/env.ts — the credential-source diagnostic label (process.env over ~/.openwiki/.env / ~/.openwiki/.env).

One note: the src/telemetry/config.ts:37 reference doesn't exist in this repo — there is no telemetry/ module here (the opt-out message lives elsewhere / hasn't landed). If you meant a specific other file, point me at it; otherwise the above covers every user-facing .env path string I could find.

Merge conflicts with upstream/main

upstream/main had since refactored agent prompts into src/agent/prompts/{code,personal}.ts and added windows-acl / conversation-history handling. I merged it in and resolved conflicts in README.md, src/agent/index.ts, src/agent/prompt.ts, and src/env.ts. The display-path substitution was re-applied to the new prompt files so agent prompts still honor OPENWIKI_CONFIG_DIR (preserving the originally reviewed behavior that the refactor would otherwise have dropped).

Validation

• tsc --noEmit (both tsconfig.json and tsconfig.client.json): clean
• eslint .: clean
• vitest run: 923 passing, including the openwiki-home tilde tests. 4 failures remain (mermaid-validate, mermaid-wiki, index-middleware, visualize-graph) — they exercise mermaid rendering / symlink containment and are unrelated to this change (pre-existing / environment-specific on this machine).

Thanks Zelys (@Zelys-DFKH) for the careful review — the display-path split and the ~ edge case were both good catches.

[Krish (akyourowngames)]

Colin Francis (@colifran) Ready for review!!

[Krish (akyourowngames)]

Related open PRs / overlap check

I scanned the open-PR list for anything touching the same surface as this one (OPENWIKI_CONFIG_DIR, the ~/.openwiki state dir, the doc-path strings in prompts/env.ts/cli.tsx). The closest ones:

• feat: make OpenWiki docs directory configurable #189 "make OpenWiki docs directory configurable" (Wezza (@Omar-Elwazeery)) — the most adjacent PR. Key distinction: feat: make OpenWiki docs directory configurable #189 configures the docs directory (openwiki/ — the repo-local generated wiki output) via OPENWIKI_DOCS_DIR, whereas this PR configures the state/home directory (~/.openwiki — credentials .env, personal wiki, connectors, skills) via OPENWIKI_CONFIG_DIR. Different directories, different goals: this PR moves OpenWiki's state off ~ for containers / read-only home dirs (don't mess with my home directory #223); feat: make OpenWiki docs directory configurable #189 moves the repo-local docs output (Feature request: Make OPEN_WIKI_DIR configurable #183). Complementary, not duplicates. Caveat: both touch src/agent/index.ts, src/agent/prompt.ts, src/cli.tsx, src/env.ts, so a conflict-resolution pass is needed if both land. This PR routes every user-facing path through the exported openWiki*DisplayPath helpers, so feat: make OpenWiki docs directory configurable #189's OPENWIKI_DOCS_DIR can layer onto the same display-path pattern.
• feat: add config subcommand to manage credentials #161 "add config subcommand to manage credentials" (Harsh (@HarshVz)) — adds openwiki config to manage ~/.openwiki/.env. It currently hardcodes ~/.openwiki/.env; this PR's openWikiEnvPath / openWikiEnvDisplayPath exports let feat: add config subcommand to manage credentials #161 respect OPENWIKI_CONFIG_DIR — i.e. feat: support configurable OpenWiki state directory #274 makes feat: add config subcommand to manage credentials #161 config-aware rather than conflicting with it.
• fix: pass windows appdata/localappdata into mcp child env #599 "pass windows appdata/localappdata into mcp child env" (Sudip Kandel (@sudipawtg)) — adjacent Windows path/env handling, no file overlap with this PR.

Posting so reviewers can see the state-dir work here is distinct from the docs-dir work in #189.

cc Wezza (@Omar-Elwazeery) Harsh (@HarshVz) Sudip Kandel (@sudipawtg)