Agent Awareness
How Codemux injects environment variables and context so CLI agents know they're in a managed worktree.
Codemux injects environment variables and a system prompt into every terminal session. CLI agents like Claude Code, Codex, Pi, and Gemini automatically know they're inside a managed worktree — what branch they're on, where the main repo lives, and that they shouldn't create their own worktrees.
Environment Variables
Every terminal pane in Codemux has these variables set:
| Variable | Description |
|---|---|
$CODEMUX | Always 1 — quick check for "am I in Codemux?" |
$CODEMUX_VERSION | Codemux version string |
$CODEMUX_ROOT_PATH | Main git repository root (original checkout, not the worktree) |
$CODEMUX_WORKSPACE_PATH | This workspace's directory |
$CODEMUX_WORKSPACE_NAME | Workspace title |
$CODEMUX_BRANCH | Git branch name for this workspace |
$CODEMUX_PORT | Stable port allocated to this workspace (10-port range) |
$CODEMUX_WORKSPACE_ID | Unique workspace identifier |
$CODEMUX_SESSION_ID | Terminal session identifier |
$CODEMUX_PANE_ID | The pane the session runs in (used by commands like codemux monitor start) |
$CODEMUX_BROWSER_CMD | Always codemux browser — the command to drive the Codemux browser |
$CODEMUX_AGENT_CONTEXT | Full agent context string (see below) |
These are the same variables available to setup scripts, so your shell, your scripts, and your agents all see the same workspace info.
Agent Chat sessions
Agent Chat agents get the same CODEMUX_* variables (and BROWSER set to codemux browser open) for the commands they run, so a codemux browser or other codemux CLI call from a chat routes to that chat's own workspace rather than whichever one you're looking at. The context string is not added to a chat agent's system prompt; that injection applies to the terminal presets below. On a thread running on another device, the paths name the directory on that device, and the browser variables are left out.
Built-in Preset Injection
Four built-in presets receive the agent context automatically — no configuration needed. Codemux detects the binary and appends the appropriate flag or sets the right env var at launch time.
| Tool | Mechanism | Notes |
|---|---|---|
| Claude Code | --system-prompt "$CODEMUX_AGENT_CONTEXT" | Appended to the command |
| Codex | -c instructions="$CODEMUX_AGENT_CONTEXT" | Overrides Codex's config-level instructions |
| Pi | --append-system-prompt "$CODEMUX_AGENT_CONTEXT" | Appends to Pi's default system prompt |
| Gemini | Writes context to a temp file, sets GEMINI_SYSTEM_MD env var | Temp file created at launch, cleaned up on reboot |
All four work out of the box. On Windows, where presets run in PowerShell, the flags reference $env:CODEMUX_AGENT_CONTEXT instead, and Gemini's temp file is written with PowerShell. The agent is told its workspace name, worktree path, branch, and rules like "don't create additional worktrees" and "use Codemux browser commands instead of system browsers."
Configuring Other Tools
The $CODEMUX_AGENT_CONTEXT environment variable is available in every terminal session. If you create custom presets for other CLI tools, you can wire it up yourself.
If the tool has a system prompt flag, reference the variable in your preset command:
mytool --system-prompt "$CODEMUX_AGENT_CONTEXT"
aider --message-file <(echo "$CODEMUX_AGENT_CONTEXT")The shell expands $CODEMUX_AGENT_CONTEXT at launch time, so the agent receives the full context string with real workspace paths.
If the tool reads env vars, it can access $CODEMUX_AGENT_CONTEXT directly — it's already set in every terminal session. You can also check individual variables like $CODEMUX, $CODEMUX_BRANCH, or $CODEMUX_WORKSPACE_PATH.
If the tool only reads project files, Codemux does not modify your project files. You can manually add a note to your project's instruction files referencing the env vars.
A Note on OpenCode
OpenCode has no CLI flag for system prompt injection. It reads instructions from AGENTS.md and opencode.json files in your project. Codemux does not inject into these files, so OpenCode won't receive the agent context automatically.
If you use OpenCode, you can add a line to your project's AGENTS.md:
If $CODEMUX is set, you are inside a managed worktree.
Do not create additional worktrees. Use `codemux browser` commands
instead of system browsers. Run `codemux --help` for available commands.This is a manual step per-project.
What Agents Are Told
The agent context includes:
- Workspace identity — name, worktree path, branch, and main repo root
- Worktree rules — the worktree is the project root for all build, test, and run commands; don't
cdto the original repo (it has a different branch checked out); don't create additional worktrees (-wflag,git worktree add), Codemux manages the lifecycle - Browser rules — use
codemux browsercommands instead of system browsers or headless Chrome - Available commands — the
codemux browsercommand set for navigation, clicking, and screenshots
When a workspace is opened directly (not as a worktree), the worktree-specific lines are omitted and only the browser commands and general rules are included.