@@ -146,6 +146,32 @@ Handover flags:
 | `--purge` | Delete the source folder once the copy is verified |
 | `-y` | Skip the "an agent may still be running" confirmation |
 
+## The session's environment
+
+A session luv starts for you — a remote dispatch, a handover, a detached start
+— is exec'd by tmux or ssh with no shell in between, so it never sources
+`~/.bashrc` or `~/.zshrc` and would otherwise run with whatever environment the
+tmux server happened to start with. luv asks your login shell (`$SHELL -lic`)
+for its environment and fills in the gaps before cloning or launching anything,
+so the agent gets the API keys and the `PATH` you'd have in a terminal there.
+
+Precedence, highest first:
+
+1. Anything already set — `FOO=bar luv …`, or `-e` — is a decision about *this*
+   session and is never overwritten.
+2. Your rc's exports fill in the rest. `PATH` is merged instead of replaced:
+   entries the rc adds (nvm, pyenv, `~/.local/bin`) are appended after the ones
+   already there.
+
+The probe runs on the machine the session runs on, so a remote session picks up
+the *remote* user's rc. It is skipped when you run `luv` yourself — that
+process already inherited your shell — and can be turned off entirely with
+`luv config set shell_env false`. An rc that hangs is given 15 seconds and then
+ignored.
+
+Docker sessions are the exception: the container has its own environment, and
+only `-e` crosses into it (see below).
+
 ## Docker dev environments
 
 If a repo contains `.luv/settings.json` with a `compose_file` key, `luv` automatically starts a Docker Compose environment and runs Claude inside the `dev-environment` container.
 
@@ -70,6 +70,35 @@ pushed. Workspaces created before slugs existed keep working.
 *string, default `~/prs`.* Where workspace folders are created on **this**
 machine. `~` is expanded.
 
+### `shell_env`
+
+*boolean, default `true`.* Whether a session luv starts should inherit your
+shell's environment.
+
+tmux and ssh exec their command directly, so a remote dispatch, a handover, or
+a detached start never sources `~/.bashrc` or `~/.zshrc` — it runs with the
+environment the tmux server was started with, frozen at whenever that server
+first came up. Anything you export from your rc (the API key an agent
+authenticates with, the `PATH` entry that makes `codex` resolvable) is simply
+absent, and only for the sessions luv started for you.
+
+With this on, luv runs `$SHELL -lic` on the machine the session runs on and
+fills in what's missing before it clones or launches anything. Values already
+set win, so `FOO=bar luv …` and `-e` still decide; `PATH` is merged rather than
+replaced, with the rc's entries appended. An rc that never returns is abandoned
+after 15 seconds.
+
+Set it to `false` if your rc is slow, or if you want sessions to see only what
+you pass them explicitly:
+
+```bash
+luv config set shell_env false
+```
+
+This is read on the machine the session runs on, so a remote host can opt out
+independently of your laptop. It does not apply to Docker sessions — the
+container has its own environment, and only `-e` crosses into it.
+
 ### `remote.host`
 
 *string.* SSH destination — an `~/.ssh/config` alias (`box`), a `user@host`, or
 
@@ -521,6 +521,19 @@ The key isn't installed or isn't being offered. Test with `ssh -v box`. Check
 `gh` is authenticated on your laptop but not on the remote. luv numbers
 workspaces with `gh api` *on the remote*, so it needs its own login there.
 
+**The agent can't find an API key / a tool it needs is missing**
+Sessions inherit your rc: before cloning or launching, luv asks the remote's
+login shell (`$SHELL -lic`) for its environment and fills in whatever tmux
+didn't pass on, `PATH` included. So this means the var isn't exported by the
+*remote* user's `~/.bashrc`/`~/.zshrc` — check with
+`ssh box 'zsh -lic "printenv | cut -d= -f1"'` — or that the rc takes longer than
+15 seconds, or that `shell_env` is `false` there. `-e` with a `LUV_`-prefixed
+variable forwards one from your laptop regardless. See
+[configuration.md](configuration.md#shell_env).
+
+Note that this happens *inside* the remote luv, so it can't help ssh find `luv`
+itself — that's the `PATH` problem above.
+
 **My prompt didn't get sent**
 Reopening a workspace that already has a live session attaches to it, and tmux
 discards the command — so the prompt is dropped. luv prints a note when this can
 
@@ -57,13 +57,13 @@ def die(msg: str) -> None:
     sys.exit(1)
 
 
-def run(cmd: list[str], *, cwd: str | None = None,
-        timeout: float | None = None) -> subprocess.CompletedProcess:
+def run(cmd: list[str], *, cwd: str | None = None, timeout: float | None = None,
+        stdin: int | None = None) -> subprocess.CompletedProcess:
     """Capture a subprocess. A timeout surfaces as a failure, not an exception,
     so callers keep their plain returncode checks."""
     try:
         return subprocess.run(cmd, capture_output=True, text=True, cwd=cwd,
-                              timeout=timeout)
+                              timeout=timeout, stdin=stdin)
     except subprocess.TimeoutExpired:
         return subprocess.CompletedProcess(cmd, 124, "", f"timed out after {timeout}s")
 
@@ -743,6 +743,84 @@ def collect_luv_env() -> dict[str, str]:
     return result
 
 
+# An rc file is a program, and some of them never finish: one that starts tmux,
+# or waits on a prompt, would otherwise hang every session start.
+SHELL_ENV_TIMEOUT = 15
+
+# Vars that describe the shell we just ran rather than the setup we asked it
+# about. Importing them would tell the agent it is somewhere it is not.
+SHELL_ENV_SKIP = {"_", "OLDPWD", "PWD", "SHLVL"}
+
+
+def shell_env() -> dict[str, str]:
+    """Everything the user's login+interactive shell exports.
+
+    tmux and ssh exec their command directly, with no shell in between, so a
+    session luv started — a remote dispatch, a handover, a detached start —
+    never sources ~/.bashrc or ~/.zshrc. It runs with whatever environment the
+    tmux server was started with, frozen at whenever that server first came up.
+    The API key an agent authenticates with and the PATH entry that makes
+    'codex' resolvable both live in the rc, and both go missing.
+
+    Asking $SHELL for its own environment is the only way to get them back: rc
+    files are code, not data, and there is no reading them from outside. -l
+    covers the profile files, -i the rc files; between them they reach where
+    bash and zsh users actually put their exports.
+    """
+    shell = os.environ.get("SHELL") or "/bin/bash"
+    marker = "__luv_env__"
+    code = ("import json,os,sys;"
+            f"sys.stdout.write({marker!r} + json.dumps(dict(os.environ)))")
+    probe = f"{shlex.quote(sys.executable)} -c {shlex.quote(code)}"
+    # DEVNULL because an interactive shell sharing our tty would fight the
+    # agent for it, and lose to SIGTTOU rather than to the timeout.
+    r = run([shell, "-lic", probe], timeout=SHELL_ENV_TIMEOUT,
+            stdin=subprocess.DEVNULL)
+    # Match on the marker, not the exit status: rc files greet, warn, and fail
+    # in ways that say nothing about whether the environment came back. What
+    # precedes the marker is the greeting; raw_decode drops anything an exit
+    # hook prints after it.
+    if marker not in r.stdout:
+        return {}
+    try:
+        env, _ = json.JSONDecoder().raw_decode(r.stdout.split(marker, 1)[1].lstrip())
+    except ValueError:
+        return {}
+    return {k: v for k, v in env.items() if isinstance(v, str)}
+
+
+def merged_path(current: str, from_rc: str) -> str:
+    """`current` first, then whatever the rc adds. PATH order is a precedence
+    list, so the binaries that got us this far keep winning."""
+    entries = [p for p in current.split(os.pathsep) if p]
+    entries += [p for p in from_rc.split(os.pathsep) if p and p not in entries]
+    return os.pathsep.join(entries)
+
+
+def apply_shell_env() -> None:
+    """Fill this process's environment in from the user's shell.
+
+    Only for the luv that tmux or ssh started (_LUV_INNER). A luv you ran
+    yourself already inherited the shell it ran in; re-deriving it there would
+    charge every session start for an rc that has already run.
+
+    What is already set wins. 'FOO=bar luv …' and -e are statements about this
+    session, while the rc is the background default, and a session that quietly
+    overrode the value you handed it would be worse than one missing it. PATH
+    is the exception, being a list rather than a value: the rc's entries are
+    appended, which is how nvm's node and ~/.local/bin become findable.
+    """
+    if not os.environ.get("_LUV_INNER") or load_config().get("shell_env") is False:
+        return
+    for key, value in shell_env().items():
+        if key in SHELL_ENV_SKIP:
+            continue
+        if key == "PATH":
+            os.environ["PATH"] = merged_path(os.environ.get("PATH", ""), value)
+        elif key not in os.environ:
+            os.environ[key] = value
+
+
 def docker_env_flags(env_vars: dict[str, str]) -> list[str]:
     """Convert env dict to docker compose exec -e flags."""
     flags: list[str] = []
@@ -3457,6 +3535,11 @@ def take_value(flag: str, what: str) -> str | None:
         die("--local cannot be combined with -s or -i")
 
     args = [a for a in args if a not in ("-n", "-r", "-e", "-f", "--force", "-p", "-nit", "--safe", "--claude", "--codex", "--local", "--no-agent-state", "--no-attach", "--purge", "-y")]
+
+    # Before anything shells out: the clone needs gh and git on PATH as much as
+    # the agent needs its credentials, and both come from the same rc. Ahead of
+    # collect_luv_env() too, so a LUV_* exported there is one -e can forward.
+    apply_shell_env()
     extra_env = collect_luv_env() if env_mode else {}
 
     # _LUV_INNER marks the remote-side luv: it must never dispatch onward.
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "luv-cli"
-version = "0.5.1"
+version = "0.6.0"
 description = "Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments"
 requires-python = ">=3.10"
 license = "MIT"
 
@@ -812,6 +812,102 @@ def test_batch_mode_adds_timeouts(self):
         self.assertIn("ConnectTimeout=5", base)
 
 
+def _shell_env_output(env, before="", after=""):
+    """What the probe sees: an rc's greeting, the marker, the environment."""
+    return f"{before}__luv_env__{json.dumps(env)}{after}"
+
+
+class ShellEnvTests(unittest.TestCase):
+    """tmux and ssh exec without a shell, so the rc has to be asked for."""
+
+    def _probe(self, stdout, returncode=0):
+        with (patch.dict(luv.os.environ, {"SHELL": "/bin/zsh"}, clear=True),
+              patch.object(luv, "run",
+                           return_value=_completed(stdout, returncode)) as run):
+            return luv.shell_env(), run.call_args
+
+    def test_asks_the_users_own_shell_as_login_and_interactive(self):
+        env, call = self._probe(_shell_env_output({"API_BASE": "https://x"}))
+
+        self.assertEqual(env, {"API_BASE": "https://x"})
+        self.assertEqual(call.args[0][:2], ["/bin/zsh", "-lic"])
+        self.assertEqual(call.kwargs["stdin"], subprocess.DEVNULL)
+        self.assertEqual(call.kwargs["timeout"], luv.SHELL_ENV_TIMEOUT)
+
+    def test_greeting_before_the_marker_is_ignored(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}, before="welcome back!\n"))
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_exit_hook_after_the_environment_is_ignored(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}, after="\ngoodbye\n"))
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_failing_rc_still_yields_what_it_exported(self):
+        env, _ = self._probe(_shell_env_output({"A": "1"}), returncode=1)
+
+        self.assertEqual(env, {"A": "1"})
+
+    def test_a_shell_that_says_nothing_useful_is_not_an_error(self):
+        self.assertEqual(self._probe("")[0], {})
+        self.assertEqual(self._probe("__luv_env__not json")[0], {})
+
+    def test_timeout_is_not_an_error(self):
+        # run() turns a hung rc into returncode 124 rather than an exception.
+        self.assertEqual(self._probe("", returncode=124)[0], {})
+
+
+class ApplyShellEnvTests(unittest.TestCase):
+    def _apply(self, environ, rc, config=None):
+        with (patch.dict(luv.os.environ, environ, clear=True),
+              patch.object(luv, "load_config", return_value=config or {}),
+              patch.object(luv, "shell_env", return_value=rc) as probe):
+            luv.apply_shell_env()
+            return dict(luv.os.environ), probe.called
+
+    def test_only_runs_for_the_luv_tmux_or_ssh_started(self):
+        env, probed = self._apply({}, {"API_KEY": "from-rc"})
+
+        self.assertFalse(probed)
+        self.assertNotIn("API_KEY", env)
+
+    def test_fills_in_what_the_session_never_sourced(self):
+        env, _ = self._apply({"_LUV_INNER": "1"}, {"API_KEY": "from-rc"})
+
+        self.assertEqual(env["API_KEY"], "from-rc")
+
+    def test_what_the_caller_set_wins(self):
+        env, _ = self._apply({"_LUV_INNER": "1", "API_KEY": "explicit"},
+                             {"API_KEY": "from-rc", "OTHER": "from-rc"})
+
+        self.assertEqual(env["API_KEY"], "explicit")
+        self.assertEqual(env["OTHER"], "from-rc")
+
+    def test_path_is_merged_rather_than_replaced(self):
+        env, _ = self._apply({"_LUV_INNER": "1", "PATH": "/usr/bin:/bin"},
+                             {"PATH": "/home/u/.nvm/bin:/usr/bin:/home/u/.local/bin"})
+
+        self.assertEqual(env["PATH"],
+                         "/usr/bin:/bin:/home/u/.nvm/bin:/home/u/.local/bin")
+
+    def test_the_probe_shells_own_bookkeeping_is_left_behind(self):
+        env, _ = self._apply({"_LUV_INNER": "1"},
+                             {"PWD": "/home/u", "SHLVL": "3", "_": "/usr/bin/env",
+                              "OLDPWD": "/tmp", "KEEP": "yes"})
+
+        self.assertEqual(env["KEEP"], "yes")
+        for key in ("PWD", "SHLVL", "_", "OLDPWD"):
+            self.assertNotIn(key, env)
+
+    def test_config_can_turn_it_off(self):
+        env, probed = self._apply({"_LUV_INNER": "1"}, {"API_KEY": "from-rc"},
+                                  config={"shell_env": False})
+
+        self.assertFalse(probed)
+        self.assertNotIn("API_KEY", env)
+
+
 class CleanGuardTests(unittest.TestCase):
     def test_live_session_folder_is_skipped(self):
         tempdir = tempfile.TemporaryDirectory()