Agent Awareness

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:

These are the same variables available to setup scripts, so your shell, your scripts, and your agents all see the same workspace info.

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.

All four work out of the box. 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 — 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.