Conductor

Conductor

Conductor runs coding agents in isolated git worktrees. Git behavior (fetch, base branch, permissions) still follows /git-workflows and /pr-guidelines — this skill is the Conductor-specific layer on top.

Agent-critical context

• Each workspace is a full repo checkout, typically ~/conductor/workspaces/<project>/<city> (the city name is the workspace directory label; the branch is the primary identifier for what you're building).
• CONDUCTOR_ROOT_PATH points at the repository root inside that workspace. Use it in setup scripts (e.g. symlinking .env files): ln -sf "$CONDUCTOR_ROOT_PATH/<path>/.env.local" <path>/.env.local.
• .context/ in the workspace is for inter-agent collaboration and is gitignored — don't treat it as durable repo state.

• Conductor injects a target branch in the workspace system instruction. Use it for PR base selection, rebase targets, and diff range — not merely "whatever branch is currently checked out" without confirming it matches that target.

• origin is shared with every other clone of the repo. git fetch (especially origin and the relevant base) before diffing or rebasing — another workspace may have advanced the base branch.

Environment variables

Conductor exposes these in the terminal and in scripts (see official env doc):

Recommended workflow

From Workflow:

1. One workspace per feature or bugfix — create via ⌘⇧N or the ⋯ menu next to "New workspace" (from PR, branch, or Linear issue).
2. Develop in Conductor's Claude Code UI or open the same tree in your IDE.
3. Review in the Diff Viewer (⌘D); use Terminal or Run to exercise the app. For dev servers, see Using run scripts — bind to $CONDUCTOR_PORT; script cwd is $CONDUCTOR_WORKSPACE_PATH.
4. Open a PR (⌘⇧P) when ready; fix failing checks with help from Conductor, then merge when green.
5. Archive the workspace when done; restore later (including chat history) from Workspaces in the sidebar.

Workspaces and branches

Per Workspaces and branches:

• New workspace → new branch; first chat often renames the branch to match the task.
• Switch work with git checkout, git branch -m, or git checkout -b as usual.
• A branch can only be checked out in one workspace at a time. If blocked, switch the other workspace to another branch or create a new branch from the desired one.

Parallel agents

⌘N opens another workspace; each agent works in an isolated tree so concurrent runs don't stomp the same working copy (Parallel agents).

Checkpoints

Checkpoints snapshot per-turn code changes and allow revert from the chat UI. Revert is destructive for messages and code after the chosen turn. Use extra care if multiple chats run in the same workspace — checkpoints are Claude Code–only and stored separately from normal branch history.

Todos

Todos live in the notes tab; incomplete todos can block merging. Reference them in composer with @todos.

Diff viewer

Diff viewer shows agent-made changes and aligns with steps toward merge/PR.

Cursor / Grok in Conductor

Cursor IDE Agent, Claude Code, and Codex inject AGENTS.md and skill catalogs. Conductor's Grok / Cursor CLI path does not, even when those files sit in Cursor's documented discovery locations. Do not compensate with [prompts.general] — that prompt is appended to every harness.

What this Grok path does inject: Cursor User Rules (Customize → Rules) and Conductor action prompts (create_pr, code_review, …). There is no per-harness prompt in Conductor's settings schema. The durable fix is Conductor/Cursor loading project AGENTS.md and ~/.cursor/skills for Grok the same way Claude does; until then, a short Cursor User Rule is the only auto-load channel that stays off Claude and GPT.

Git and PRs

• Permission and safety: /git-workflows (commit/push gates, fetch-before-diff, SSH, etc.).
• Base branch and PR prose: /pr-guidelines — first step when choosing base is still Conductor target branch when present.

Managed settings

~/.conductor/settings.json (schema: https://conductor.build/schemas/settings.json) holds machine-wide overrides Conductor enforces — defaultModel, enterpriseDataPrivacy, claudeExecutablePath. In this dotfiles setup it is symlinked from agents/conductor.settings.json; edit there.

Official documentation

Full index: docs.conductor.build/llms.txt. Starting points:

• Workflow
• Workspaces and branches
• Conductor environment variables
• From issue to PR
• Core: Parallel agents, Diff viewer, Checkpoints, Todos, Scripts, MCP