fix(config): give standalone Gentle Shell its own config home by Alan-TheGentleman · Pull Request #2207 · Gentleman-Programming/gentle-shell

Alan-TheGentleman · 2026-10-13T22:55:22Z

Summary

Standalone gentle-shell in its default isolated home now keeps Gentle Shell preferences (profiles, models, banner, vim, card and other policies) in ~/.gentle-shell/gentle-ai instead of the shared ~/.pi/gentle-ai, so a standalone install and a Pi-package install (Path B) no longer overwrite each other's settings.
First launch copies the existing files once from ~/.pi/gentle-ai: never overwrites, never modifies or deletes the source, skips symlinks, subdirectories and install-level state, prints one line, and never blocks launch on failure.
One shared resolver for every reader: bundled prefix > non-empty GENTLE_PI_CONFIG_HOME > launcher marker GENTLE_SHELL_CONFIG_HOME > ~/.pi/gentle-ai. Gentle AI processes get the same folder through the bundled-mode pair (GENTLE_AI_PI_CONFIG_DIR + parent GENTLE_PI_CONFIG_HOME), and setup preserves both persona.json copies.

Behavior changes to note

Empty GENTLE_PI_CONFIG_HOME now counts as unset everywhere. Before, the banner, profiles and dev-binary readers resolved "" to the current folder while lib/agent-home.ts treated it as unset. tests/gentle-shell.test.ts pinned the old cwd behavior only as non-regression for the bundled work; it is updated.
Unchanged: --link, custom --home <path>, a custom GENTLE_SHELL_HOME outside a .gentle-shell folder (its parent may be any folder, such as ~, so Gentle Shell never claims a gentle-ai folder there), gentle-pi inside Pi, and bundled installs.
dev-binary.json and channel.json stay in ~/.pi/gentle-ai: the installer and gentle-shell upgrade write them outside any session.
self-uninstall removes ~/.gentle-shell/gentle-ai; the shared ~/.pi/gentle-ai rule (kept unless --include-shared) is unchanged.

Changes

Area	Files
Resolver	`lib/gentle-shell-bundled.ts`, `lib/agent-home.ts`, `extensions/startup-banner.ts`, `extensions/gentle-shell.ts`, `scripts/main-channel.mjs`
Launcher, migration, Gentle AI env	`lib/gentle-shell-launcher.ts`, `lib/gentle-ai-binary.ts`, `bin/gentle-shell.mjs`
Uninstall	`lib/gentle-shell-uninstall.ts`
Generated	`runtime/*.mjs`
Tests	`tests/standalone-config-home.test.ts` (new), uninstall, launcher, startup-banner, gentle-shell
Docs	`docs/readme-reference.md` (Config home), `docs/gentle-shell-uninstall.md`, `README.md`, `--help`

Test plan

RED reproduced first: an isolated gentle-shell list gave Pi no config marker (config in ~/.pi/gentle-ai); GENTLE_PI_CONFIG_HOME="" resolved dev-binary.json relative to the cwd.
npm test: exit 0, 6644 pass, 0 fail; unit-tests, provider-contract and runtime-harness pass (re-run after rebasing on current main). node scripts/check-types.mjs: no regressions; pnpm run check:runtime-modules: in sync.
Independent verifier (fresh context): S1/S1a/S8 PASS, no blockers. Probes against the real launcher with temp HOME and a fake pi: migration copies only regular non-install files, folder 0700, source hash/mode/mtime unchanged, second run is a no-op, existing files never overwritten; --link and --home get no marker; explicit GENTLE_PI_CONFIG_HOME wins with no migration; empty value from another cwd does not resolve to the cwd; self-uninstall --dry-run plan correct; Gentle AI setup receives the env pair and both persona.json copies are restored.
Verifier advisory fixed in a scoped follow-up commit: a custom GENTLE_SHELL_HOME=~/myagent no longer adopts an existing ~/gentle-ai (repro re-run: no marker, foreign folder untouched; default home still migrates).

Summary by CodeRabbit

New Features
- Standalone isolated installs now keep Gentle AI settings in a separate configuration folder. On first launch, existing settings are copied there; the shared settings remain unchanged.
- Configuration paths are documented, including how custom homes and environment-variable overrides affect them.
Bug Fixes
- Uninstalling removes the isolated install’s own settings when appropriate, while preserving shared settings and configuration folders associated with custom homes.

The isolated launcher home now keeps Gentle Shell preferences in ~/.gentle-shell/gentle-ai instead of the shared ~/.pi/gentle-ai. On first launch, files are copied once from ~/.pi/gentle-ai without overwriting or touching the source. An explicit GENTLE_PI_CONFIG_HOME still wins, and Gentle AI processes get the same folder through the bundled-mode isolation pair. Every reader shares one resolver, so an empty GENTLE_PI_CONFIG_HOME now counts as unset everywhere instead of naming the current folder. Install-level state (dev-binary.json, channel.json) stays in ~/.pi/gentle-ai. Closes #2201.

… home Beside a custom GENTLE_SHELL_HOME such as ~/myagent the sibling would be ~/gentle-ai, which may be anyone's folder; only an agent dir inside a .gentle-shell folder gets its own config folder.

coderabbitai · 2026-10-13T22:56:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: ada5a747-89a5-4fa6-a8f8-68953a2d5106

📥 Commits

Reviewing files that changed from the base of the PR and between fb5e731 and 50b1ba5.

📒 Files selected for processing: 20

README.md
bin/gentle-shell.mjs
docs/gentle-shell-uninstall.md
docs/readme-reference.md
extensions/gentle-shell.ts
extensions/startup-banner.ts
lib/agent-home.ts
lib/gentle-ai-binary.ts
lib/gentle-shell-bundled.ts
lib/gentle-shell-launcher.ts
lib/gentle-shell-uninstall.ts
runtime/gentle-ai-binary.mjs
runtime/gentle-shell-bundled.mjs
runtime/gentle-shell-launcher.mjs
runtime/gentle-shell-uninstall.mjs
scripts/main-channel.mjs
tests/gentle-shell-uninstall.test.ts
tests/gentle-shell.test.ts
tests/standalone-config-home.test.ts
tests/startup-banner.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

📝 Walkthrough

Standalone launches now resolve settings to ~/.gentle-shell/gentle-ai for the default isolated home, copy eligible settings from ~/.pi/gentle-ai when the new config directory is first created, and pass the selected config home through launcher and Gentle AI environments. Uninstall planning now accounts for the separate directory.

Changes: Standalone config home

Layer / File(s)	Summary
Config-home resolution `lib/gentle-shell-bundled.ts`, `lib/agent-home.ts`, `extensions/gentle-shell.ts`, `extensions/startup-banner.ts`, `lib/gentle-ai-binary.ts`, `runtime/gentle-shell-bundled.mjs`, `runtime/gentle-ai-binary.mjs`, `scripts/main-channel.mjs`, `tests/standalone-config-home.test.ts`, `tests/gentle-shell.test.ts`, `tests/startup-banner.test.ts`	A shared resolver applies config-home precedence, including treating empty overrides as unset. Profile and banner readers, Gentle AI isolation, and dev-binary registration use the resolved path.
Launcher config selection and migration `lib/gentle-shell-launcher.ts`, `runtime/gentle-shell-launcher.mjs`, `bin/gentle-shell.mjs`, `README.md`, `docs/readme-reference.md`, `tests/standalone-config-home.test.ts`	Eligible default isolated launches use a separate config home. On first creation, the launcher copies regular files from the shared config directory, excluding `dev-binary.json` and `channel.json`; failures are reported without stopping startup. Setup snapshots the selected config persona, and launcher help and reference docs describe the config paths and overrides.
Uninstall config ownership `lib/gentle-shell-uninstall.ts`, `runtime/gentle-shell-uninstall.mjs`, `tests/gentle-shell-uninstall.test.ts`, `README.md`, `docs/gentle-shell-uninstall.md`	Uninstall planning includes the separate config directory for the default isolated home when it differs from the active config home. A sibling config directory beside a custom home is kept and reported. Tests cover both cases.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Launcher as gentle-shell launcher
  participant Migrator as migrateStandaloneConfig
  participant Filesystem
  participant Pi
  participant GentleAI as Gentle AI
  Launcher->>Migrator: migrate shared settings when standalone config is missing
  Migrator->>Filesystem: create target and copy eligible regular files
  Launcher->>Pi: pass selected config-home marker
  Pi->>GentleAI: pass config environment for standalone isolation

Possibly related PRs

Gentleman-Programming/gentle-shell#1311: Introduces the standalone launcher and isolated-home behavior that this change extends with config-home selection and migration.

Suggested reviewers: decode2

Merge Risk: ⚪ Minimal · up to 50b1b

The standalone config-home change is mergeable after normal checks; no PR-introduced issue requiring a fix was established.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 52 functions across 17 files. (3 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: assigning standalone Gentle Shell its own configuration home.
Linked Issues check		Issue [`#2201`] requires standalone Path A configuration to remain separate from `~/.pi/gentle-ai` and to be removed with the standalone home. `standaloneConfigHome` selects `~/.gentle-shell/gentle-ai` …
Out of Scope Changes check		The changes stay within issue [`#2201`]. Resolver updates, launcher environment propagation, migration, Gentle AI environment handling, uninstall planning, generated runtime files, documentation, and te…

Full details: Docstring Coverage

Explanation

Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 52 functions across 17 files. (3 skipped: 3 unsupported.)

Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

…ng#2205, Gentleman-Programming#2207) before resolving the launcher import conflict # Conflicts: # bin/gentle-shell.mjs

Alan-TheGentleman added 2 commits October 14, 2026 00:48

fix(config): keep custom GENTLE_SHELL_HOME homes on the shared config…

50b1ba5

… home Beside a custom GENTLE_SHELL_HOME such as ~/myagent the sibling would be ~/gentle-ai, which may be anyone's folder; only an agent dir inside a .gentle-shell folder gets its own config folder.

Alan-TheGentleman added the type:bug Bug fix label Oct 13, 2026

Alan-TheGentleman merged commit f69cf2b into main Oct 13, 2026
9 checks passed

Navigation Menu

Repository navigation

fix(config): give standalone Gentle Shell its own config home - #2207

fix(config): give standalone Gentle Shell its own config home#2207
Alan-TheGentleman merged 2 commits into
mainfrom
fix/2201-standalone-config-home

Alan-TheGentleman commented Oct 13, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Oct 13, 2026 •

edited

Loading

Sequence Diagram(s)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Alan-TheGentleman commented Oct 13, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Behavior changes to note

Changes

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sequence Diagram(s)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Alan-TheGentleman commented Oct 13, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 13, 2026 •

edited

Loading