Skip to main content
CODEMUXManual

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:

VariableDescription
$CODEMUXAlways 1 — quick check for "am I in Codemux?"
$CODEMUX_VERSIONCodemux version string
$CODEMUX_ROOT_PATHMain git repository root (original checkout, not the worktree)
$CODEMUX_WORKSPACE_PATHThis workspace's directory
$CODEMUX_WORKSPACE_NAMEWorkspace title
$CODEMUX_BRANCHGit branch name for this workspace
$CODEMUX_PORTStable port allocated to this workspace (10-port range)
$CODEMUX_WORKSPACE_IDUnique workspace identifier
$CODEMUX_SESSION_IDTerminal session identifier
$CODEMUX_PANE_IDThe pane the session runs in (used by commands like codemux monitor start)
$CODEMUX_BROWSER_CMDAlways codemux browser — the command to drive the Codemux browser
$CODEMUX_AGENT_CONTEXTFull 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.

ToolMechanismNotes
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
GeminiWrites context to a temp file, sets GEMINI_SYSTEM_MD env varTemp 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 cd to the original repo (it has a different branch checked out); don't create additional worktrees (-w flag, git worktree add), Codemux manages the lifecycle
  • Browser rules — use codemux browser commands instead of system browsers or headless Chrome
  • Available commands — the codemux browser command 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.