feat: added configurable base directory.

[mcking-07]

What Changed

Added a configurable base directory for T3 Code data storage via:

• T3CODE_BASE_DIR environment variable
• --base-dir CLI flag

The base directory defaults to ~/.t3, with the following paths now relative to baseDir:

• userdata -> application state and SQLite database
• worktrees -> git worktree directories (existing, now uses baseDir)

Path precedence:

• baseDir: CLI (--base-dir) > env (T3CODE_BASE_DIR) > default (~/.t3)
• stateDir: CLI (--state-dir) > env (T3CODE_STATE_DIR) > default (<baseDir>/userdata)

Note: If stateDir is set explicitly (via CLI or env), it takes full priority and can be anywhere, independent of baseDir.

Changes include:

• Add baseDir to ServerConfigShape
• Add resolveBaseDir() for base directory resolution
• Update resolveStateDir() to accept baseDir parameter
• Add --base-dir flag to CLI (server + dev-runner)
• Add T3CODE_BASE_DIR env var support
• Update all test layers to include baseDir

Why

Previously, all T3 Code data (worktrees, userdata, etc.) was hardcoded to ~/.t3. This change introduces T3CODE_BASE_DIR (--base-dir CLI flag) to allow users to customize the base directory.

This enables:

• Storing data in a custom location (not ~/.t3)
• Using different drives/volumes (external SSD, network mount, etc.)
• CI/headless environments with non-standard paths
• For users who prefer not to have a .t3 folder in their home directory cough myself cough

Fixes #748

---

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Note

Replace T3CODE_STATE_DIR with T3CODE_HOME as the configurable base directory

• Introduces a baseDir concept (defaulting to ~/.t3) that serves as the root from which stateDir is derived as {baseDir}/userdata (or {baseDir}/dev when a dev URL is set).
• Replaces the --state-dir CLI flag with --home-dir (mapping to T3CODE_HOME) across both the server (main.ts) and dev-runner (dev-runner.ts).
• Git worktrees are now created under {baseDir}/worktrees/{repo}/{branch} instead of under the user home directory.
• Adds resolveBaseDir to os-jank.ts and updates resolveStateDir to accept baseDir as its first argument.
• Behavioral Change: any tooling or environment config relying on T3CODE_STATE_DIR or --state-dir must switch to T3CODE_HOME / --home-dir.

^{Macroscope summarized 6de5527.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 105387c2-a531-4c25-afd4-117a5c561523

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

Tip

You can disable poems in the walkthrough.

Disable the reviews.poem setting to disable the poems in the walkthrough.

[Copilot]

Pull request overview

Adds a configurable “base directory” for T3 Code data storage (~/.t3 by default), exposing it via T3CODE_BASE_DIR and a --base-dir CLI flag, and updates the server/dev-runner/test harnesses so state/worktrees paths become relative to this base.

Changes:

• Introduce baseDir into server config and CLI/env resolution with documented precedence (--base-dir > T3CODE_BASE_DIR > default).
• Move worktree location under <baseDir>/worktrees and make default state dir relative to base (<baseDir>/userdata).
• Update dev-runner + extensive test layers/harnesses to pass and use baseDir.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
turbo.json	Adds T3CODE_BASE_DIR to turbo global env passthrough.
scripts/dev-runner.ts	Adds base dir flag/env support and resolves derived dev state dir.
scripts/dev-runner.test.ts	Updates dev-runner env tests for new base dir behavior.
apps/server/src/wsServer.test.ts	Extends test server options to include baseDir.
apps/server/src/telemetry/Layers/AnalyticsService.test.ts	Updates test config layer to pass baseDir.
apps/server/src/provider/Layers/CodexAdapter.test.ts	Updates ServerConfig.layerTest calls for new signature.
apps/server/src/os-jank.ts	Adds resolveBaseDir + updates resolveStateDir to be base-dir aware.
apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts	Updates ServerConfig.layerTest calls for new signature.
apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts	Updates harness to manage temp base dirs and pass baseDir.
apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts	Updates projection pipeline test layers to include baseDir and temp dir cleanup.
apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts	Updates ServerConfig.layerTest calls for new signature.
apps/server/src/orchestration/Layers/CheckpointReactor.test.ts	Updates ServerConfig.layerTest calls for new signature.
apps/server/src/main.ts	Adds --base-dir + T3CODE_BASE_DIR env parsing and resolves base/state dirs with precedence.
apps/server/src/git/Layers/GitManager.test.ts	Provides ServerConfig layer to satisfy GitCore’s new dependency.
apps/server/src/git/Layers/GitCore.ts	Moves default worktrees directory under <baseDir>/worktrees.
apps/server/src/git/Layers/GitCore.test.ts	Provides ServerConfig layer for GitCore tests.
apps/server/src/git/Layers/CodexTextGeneration.test.ts	Updates test layer creation to pass baseDir/stateDir.
apps/server/src/config.ts	Adds baseDir to ServerConfigShape and updates layerTest signature.
apps/server/integration/OrchestrationEngineHarness.integration.ts	Updates integration harness to pass base dir into test config layer.
apps/desktop/src/main.ts	Derives desktop state dir from T3CODE_BASE_DIR and forwards it to backend env.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[juliusmarminge]

i feel like we have too many flags already 😆, would be down to just have T3_HOME and everything relative to that one?

[mcking-07]

nice, much cleaner... let me confirm the plan,

removing

• --base-dir and --state-dir CLI flags
• T3CODE_BASE_DIR env var
• T3CODE_STATE_DIR env var

introducing

• single T3_HOME (or T3CODE_HOME?) env var
• --t3-home CLI flag (optional, for convenience)
• defaults to ~/.t3
• fixed structure:
  • $T3_HOME/userdata/ — SQLite, logs, app state
  • $T3_HOME/worktrees/ — git worktrees

quick question on naming... should I go with T3_HOME (shorter) or T3CODE_HOME (consistent with T3CODE_PORT, T3CODE_HOST, etc.)?

[juliusmarminge]

quick question on naming... should I go with T3_HOME (shorter) or T3CODE_HOME (consistent with T3CODE_PORT, T3CODE_HOST, etc.)?

T3CODE_HOME sounds good. as for cli flag we don't need to have the t3- prefix. just --home-dir (or does that cuas confusion thinking it'll override OS.homedir() ?

[mcking-07]

T3CODE_HOME 👍

or does that cuas confusion thinking it'll override OS.homedir()

--home-dir works for me. it should be clear enough given the context. alternative: --data-dir if you want to avoid any confusion?

[mcking-07]

@juliusmarminge, i have updated the PR to use the simplified approach we discussed:

changes made:

• removed T3CODE_BASE_DIR, T3CODE_STATE_DIR env vars and --base-dir, --state-dir flags
• introduced T3CODE_HOME env var and --home-dir flag

behavior:

• defaults to ~/.t3
• all paths are derived from it:
  • dev - dev-runner state (for development mode)
  • userdata - app state, sqlite, logs
  • worktrees - git worktrees

[binbandit]

Can we update the pr title based on the current solution please

[binbandit]

Lets change the title to: feat: added configurable base directory -- short sharp clean.