# Conductor > Conductor is a Mac app that lets you run many coding agents in parallel on your codebase. ## Evergreen pages --- title: "Brand kit | Conductor" url: "/brandkit" description: "Official Conductor brand assets, product description, and links." --- # Conductor brand assets Official Conductor brand assets, product description, and links. ## Brand kit download - [Download the Conductor brand kit ZIP](/brandkit/conductor-brandkit.zip) ## Assets ### Letter mark (Dark) Use on light backgrounds. - SVG: [conductor-letter-dark.svg](/brandkit/conductor-letter-dark.svg) - PNG: [conductor-letter-dark.png](/brandkit/conductor-letter-dark.png) - 677 x 1024 ### Letter mark (Light) Use on dark backgrounds. - SVG: [conductor-letter-light.svg](/brandkit/conductor-letter-light.svg) - PNG: [conductor-letter-light.png](/brandkit/conductor-letter-light.png) - 677 x 1024 ### Wordmark (Dark) Use on light backgrounds. - SVG: [conductor-wordmark-dark.svg](/brandkit/conductor-wordmark-dark.svg) - PNG: [conductor-wordmark-dark.png](/brandkit/conductor-wordmark-dark.png) - 2400 x 369 ### Wordmark (Light) Use on dark backgrounds. - SVG: [conductor-wordmark-light.svg](/brandkit/conductor-wordmark-light.svg) - PNG: [conductor-wordmark-light.png](/brandkit/conductor-wordmark-light.png) - 2400 x 369 ## About Conductor Conductor is a Mac app for running coding agents in parallel. Developers create isolated workspaces for Claude Code, Codex, and Cursor, see what each agent is doing, then review and merge the changes. Each workspace gets its own branch, git worktree, run environment, and shared context folder, so multiple tasks can move at once without crowding the main repository. Conductor is a Y Combinator Summer 2024 company based in San Francisco, building developer tools for teams working with AI coding agents. ## Short description Conductor is a Mac app for running Claude Code, Codex, and Cursor agents in parallel across isolated workspaces. ## Facts - Product: Conductor - Category: Developer tools / AI - Platform: Mac app - Agents: Claude Code, Codex, and Cursor - Founded: 2024 - YC batch: Summer 2024 - Location: San Francisco ## Official links - Website: [https://www.conductor.build](/) - Docs: [https://www.conductor.build/docs](/docs) - Changelog: [https://www.conductor.build/changelog](/changelog) - YC profile: [https://www.ycombinator.com/companies/conductor](https://www.ycombinator.com/companies/conductor) ## Agent resources - Skill: [/.well-known/agent-skills/conductor/SKILL.md](/.well-known/agent-skills/conductor/SKILL.md) - Discovery: [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json) --- title: "Enterprise | Conductor" url: "/enterprise" description: "Conductor is the best way to run multiple coding agents in parallel. Reach out to bring Conductor to your organization." --- # Conductor Enterprise Conductor is the interface to manage your coding agents. Trusted by builders at Use this page when you need to discuss deployment requirements, security constraints, or how Conductor fits into your organization's engineering workflow. ## Privacy and security [#privacy-and-security] --- title: "Join us | Conductor" url: "/join-us" description: "We're building Conductor in San Francisco and hiring engineers and designers to shape the future of AI-native software development." --- # Join Conductor Conductor lets you run a team of coding agents on your Mac. We've grown 10x since January and raised $24M from some of the top investors in Silicon Valley. We're used by engineers at leading companies like Linear, Vercel, Ramp, Notion, Stripe, and many more. ## Our plan [#our-plan] Coding agents are doing work that junior engineers used to do. Soon they'll be doing senior-engineer work. In response, humans are becoming full-time AI-managers. What software will these AI-managers use? Conductor has already created a narrow new product category, the "AI orchestrator," and it's already changing how people work. As one engineer at Ambrook told me on a call: > A huge amount of my work now is wildly parallelized, in a way I've never had to worry about before. It's been a while since a dev tool has changed my life \[like Conductor did]. Right now, AI-managers use many tools alongside Conductor. They'll probably use existing coding software (Cursor, Warp, GitHub) and tools for human managers (Linear, GitHub, Slack). Of all those tools, we think it's the AI orchestrator that has the best shot at becoming the primary UI that the AI-managers will use. Although it's the newest and least-established of those tools, it's the only one built ground-up with AI in mind. Designing the first AI orchestrator from the ground up as we build it has been a ton of fun. It feels like a perfect match for the skillset of our team: technical chops, customer focus, taste, and speed. And if we win the category, Conductor will be a massive company. ## Our team [#our-team] One reason we started Conductor was to create a place where we could do the best work of our lives: in person, with incredible people, toward a formidable goal, holding each other to the highest standards. Conductor feels like an elite sports team. We work in person about five days a week in San Francisco. Learn more about [what it's like working at Conductor](https://conductor-build.notion.site/What-It-s-Like-Working-at-Conductor-29da076bd0f2808bad97e3a4b876c01a) and [see what we've been building](https://x.com/search?src=typed_query\&q=%40conductor_build). --- title: "Privacy notice | Conductor" url: "/privacy" description: "How Conductor collects, uses, discloses, and otherwise processes personal data." --- # Privacy Notice [#privacy-notice] **Last Updated**: June 12, 2026 This Privacy Notice explains how Melty, Inc. ("**Conductor**") collects, uses, discloses, and otherwise processes personal data in connection with any specific product, service, or application that references or links to this Privacy Notice. This Privacy Notice does not address our privacy practices relating to Conductor job applicants, employees and other employment-related individuals, nor data that is not subject to applicable data protection laws (such as non-personal, company confidential information, or deidentified or publicly available information in certain jurisdictions). This Privacy Notice is also not a contract and does not create any legal rights or obligations not otherwise provided by law. **Our Role in Processing Personal Data** Data protection laws sometimes differentiate between "controllers" and "processors" of personal data. A "controller" determines the purposes and means (the why and how) of processing personal data. A "processor," which is sometimes referred to as a "service provider," processes personal data on behalf of a controller subject to the controller's instructions. This Privacy Notice describes our privacy practices where we are acting as the controller of personal data. However, this Privacy Notice does not cover or address how our customers may process personal data when they use our services, or how we may process personal data on their behalf in accordance with their instructions where we are acting as their processor. We primarily act as a controller of personal data we collect through our website ([https://www.conductor.build](https://www.conductor.build)), personal data we collect about representatives of our customers (such as name, contact information, professional information, account information, payment information, and feedback and support information that is used for managing our relationships with our customers), and limited analytics data collected from the Conductor application (such as crash logs and information about what features are used). We act as a processor on behalf of our customers for all data processed through the Conductor application to which we have access. This data is limited for on-prem deployments of Conductor because the application stores code and chat history locally on our customers' systems. Conductor does not intercept or modify any network traffic sent between customers' systems and customers' AI model providers in this configuration. However, certain optional product features for the on-prem deployment may send limited chat data to third-party AI service providers on Conductor's behalf. For example, Conductor may send but not store the first message in a chat session to a third-party AI provider to generate a summary title for that session. These features can be disabled in the on-prem Conductor application's privacy settings. For Conductor Cloud, Conductor has additional technical access to data (including code, logs, chat history, and certain interactions between customers and third-party AI model providers) within the Conductor-managed cloud environment. However, we are still acting as a processor subject to use restrictions and other contractual obligations in our handling of this data. Answers to FAQs about data processing in connection with the Conductor application are available here: /docs/reference/privacy. Where we are acting as a processor, we recommend referring to the privacy notice of the customer with which you have a relationship for information on how they engage processors, like us, to process personal data on their behalf. In addition, we are generally not permitted to respond to individual requests relating to personal data we process on behalf of our customers, so we recommend directing any requests to the relevant customer. **Our Collection and Use of Personal Data** The categories of personal data we collect depend on how you interact with us and our services. For example, you may provide us your personal data directly when you sign up for our mailing list, register for an account, make a payment, post a review, or otherwise contact us or interact with us. We also collect personal data automatically when you interact with our websites and other services and may also collect personal data from other sources and third parties. **Personal Data Provided by Individuals** We collect the following categories of personal data individuals provide us: * **Contact Information**, including first and last name, email address, and communication preferences. We use this information primarily to fulfill your request or transaction, to communicate with you directly, and to send you marketing communications in accordance with your preferences. * **Professional Information**, including job title, company name, professional background, and the nature of your relationship with us. We use this information primarily to fulfill your request or transaction, to determine how we communicate with you, to administer your account, to provide you with our services, and for customer support purposes. * **Account Information**, including first and last name, email address, profile image, account credentials or one-time passcodes, and the products or services you are interested in, purchased, or have otherwise used. We use this information primarily to administer your account, provide you with our products and services, communicate with you regarding your account and your use of our products and services, and for customer support purposes. * **Payment Information**, including payment card information, billing address, and other financial information (such as, routing and account number). Please note that we use third-party payment providers, including Stripe, to process payments made to us. We do not retain any personally identifiable financial information, such as payment card number, you provide these third-party payment providers in connection with payments. Rather, all such information is provided directly by you to our third-party payment providers. The payment provider's use of your personal data is governed by their privacy notice. To view Stripe's privacy policy, please [click here](https://stripe.com/privacy). * **Feedback and Support Information**, including the contents of custom messages you choose to send us through the forms, customer support chat platforms, including online live chat or automated chat functions, email addresses, or other contact information we make available for customer support (including through the use of automated or artificial intelligence tools provided by us or our third-party providers). We use this information primarily to investigate and respond to your inquiries, to communicate with you, and to improve our products and services. This category of personal data does not include chats or chat history outside of designated customer support channels, including chats or chat history from the Conductor application (which are stored locally in our customers' systems by default for on-prem deployments and otherwise are processed by us solely in our capacity as a "processor," as described above). **Personal Data Automatically Collected** We, and our third-party partners, automatically collect information you provide to us and information about how you access and use our website, products and services when you engage with us. We typically collect this information through the use of a variety of our own and our third-party partners' automatic data collection technologies, including (i) cookies or small data files that are stored on an individual's computer and (ii) other, related technologies, such as web beacons, pixels, embedded scripts, mobile SDKs, location-identifying technologies and logging technologies. Information we collect automatically about you may be combined with other personal data we collect directly from you or receive from other sources. We, and our third-party partners, use automatic data collection technologies to automatically collect the following data when you use our website, products and services or otherwise engage with us: * **Information About Your Device and Network**, including the device type, manufacturer, and model, operating system, IP address, browser type, Internet service provider, and unique identifiers associated with you, your device, or your network (including, for example, a persistent device identifier). On our website, we may employ third-party technologies designed to allow us to recognize when two or more devices are likely being used by the same individual and may leverage these technologies (where permitted by law) to link information collected from different devices. * **Information About the Way Individuals Use Our Services and Interact With Us**: * For our website, this includes the site from which you came, the site to which you are going when you leave our website, how frequently you access our website, whether you open emails or click the links contained in emails sent in connection with our website (such as marketing emails), whether you access our website from multiple devices, and other browsing behavior and actions you take on our services (such as the pages you visit, the content you view, videos you watch, the communications you send us, and the content, links and ads you interact with). We may employ third-party technologies designed to allow us to collect detailed information about browsing behavior and actions that you take on our website. These third-party technologies may also record information you enter when you interact with our website, or engage in chat features or other communication platforms we provide on our website. * For the Conductor application, this is limited to information about how and when you use the application, what features of the application you use, errors or issues you may experience (including through the recording of crash logs), and similar analytics data. * **Information About Your Location**, including general geographic location that we or our third-party providers may derive from your IP address. All of the information collected automatically through these tools allows us to improve your experience. For example, we may use this information to enhance and personalize your user experience, to monitor and improve our website, products and services, to offer customer support features such as live and automated chat, and to improve the effectiveness of our website, products, services, offers, advertising, communications and customer service. We may also use this information to: (a) remember information so that you will not have to re-enter it during your visit or the next time you visit the website; (b) provide custom, personalized content and information, including targeted content and advertising, based on information collected from your visit to our website; (c) identify you across multiple devices; (d) provide and monitor the effectiveness of our website, products and services; (e) monitor aggregate metrics such as total number of visitors / users, traffic, usage, and demographic patterns on our website; (f) diagnose or fix technology problems; and (g) otherwise to plan for and enhance our website, products and services. For information about the choices you may have in relation to our use of automatic data collection technologies, please refer to the Your Privacy Choices section below. **Personal Data from Other Sources and Third Parties** We may receive the same categories of personal data as described above from the following sources and other parties: * **Single Sign-On**: We may provide you the ability to log in to our services through certain third-party accounts you maintain. When you use these single sign-on protocols to access our services, we do not receive your login credentials for the relevant third-party service. Instead, we receive tokens from the single sign-on protocol to help identify you in our system (such as by your username) and confirm you successfully authenticated through the single sign-on protocol. This information allows us to more easily provide you access to our products and services. * **Other Customers**: We may receive your personal data from our other customers. For example, a customer may provide us with your contact information as a part of a referral. * **Social Media**: When you interact with our services through social media networks, such as when you follow us or share our content on other social networks, we may receive some information that you permit the social network to share with third parties. The data we receive is dependent upon your privacy settings with the social network, and may include profile information, profile picture, username, and any other information you permit the social network to share with third parties. You should always review and, if necessary, adjust your privacy settings on third-party websites and social media networks and services before sharing information and/or linking or connecting them to other services. We use this information primarily to operate, maintain, and provide to you the features and functionality of our products and services, as well as to communicate directly with you, such as to send you messages about features that may be of interest to you. * **Advertisers, Influencers, and Publishers**: We engage in advertising through third-party services. Advertisers, influencers, and publishers may share personal data with us in connection with our advertising efforts. For example, we may obtain information about whether an advertisement for our services led to a successful engagement between you and us. * **Integration Partners**: We may receive your information from integration partners, such as companies that offer their products and/or services as a part of or in connection with our services. For example, certain of our products and services allow our customers to integrate third-party services. If you choose to leverage these third-party service integrations, we may receive confirmation from our integration partner regarding whether you are an existing customer of their services. * **Service Providers**: Our service providers that perform services on our behalf, such as analytics, cloud hosting, and certain marketing providers, collect personal data and often share some or all of this information with us. For example, we receive personal data you may submit in response to requests for feedback to our survey providers. * **Other Sources**: We may also collect personal data about you from other sources, including through transactions such as mergers and acquisitions. **Additional Uses of Personal Data** In addition to the primary purposes for using personal data described above, we may also use personal data we collect to: * Fulfill or meet the reason the information was provided, such as to fulfill our contractual obligations, to facilitate payment for our products and services, or to deliver the services requested; * Manage our organization and its day-to-day operations; * Communicate with you, including via email; * Facilitate the relationship we have with you and, where applicable, the company you represent; * Request you provide us feedback about our product and service offerings; * Address inquiries or complaints made by or about an individual in connection with our products or services; * Create and maintain accounts for our users; * Verify your identity and entitlement to our products and services; * Market our products and services to you, including through email; * Administer, improve, and personalize our products and services, including by recognizing you and remembering your information when you return to our products and services; * Develop, operate, improve, maintain, protect, and provide the features and functionality of our products and services; * Identify and analyze how you use our products and services; * Infer additional information about you from your use of our products and services, such as your interests; * Create aggregated or de-identified information that cannot reasonably be used to identify you, which information we may use for purposes outside the scope of this Privacy Notice; * Conduct research and analytics on our user base and our products and services, including to better understand the demographics of our users; * Improve and customize our products and services to address the needs and interests of our user base and other individuals we interact with; * Test, enhance, update, and monitor the products and services, or diagnose or fix technology problems; * Help maintain and enhance the safety, security, and integrity of our property, products, services, technology, assets, and business; * Defend, protect, or enforce our rights or applicable contracts and agreements (including our Terms and Conditions), as well as to resolve disputes, to carry out our obligations and enforce our rights, and to protect our business interests and the interests and rights of third parties; * Detect, prevent, investigate, or provide notice of security incidents or other malicious, deceptive, fraudulent, or illegal activity and protect the rights and property of Conductor and others; * Facilitate business transactions and reorganizations impacting the structure of our business; * Comply with contractual and legal obligations and requirements; * Fulfill any other purpose for which you provide your personal data, or for which you have otherwise consented. Please note we do not use customer data, including any customer personal data, processed through the Conductor application for purposes of training or fine-tuning our or our third-party providers' artificial intelligence or machine learning models (including AI or ML models made available directly by us through Conductor Cloud). However, if a customer chooses to share data with an integration partner (such as a third-party AI model provider with whom the customer has a relationship), the customer's contract with the relevant third party would govern that third party's use of personal data. We have no control over, or responsibility for, that third party's use of personal data (including, but not limited to, the extent to which the third party may use such data for training or fine-tuning artificial intelligence or machine learning models). **Our Disclosure of Personal Data** We disclose or otherwise make available personal data in the following ways: * **To Marketing Providers:** We coordinate and share personal data with our marketing providers in order to advertise and communicate with you about the products and services we make available. * **To Ad Networks and Advertising Partners**: We work with third-party ad networks and advertising partners to deliver advertising and personalized content on other websites and services, and across other devices. These parties may collect information automatically from your browser or device when you visit our website through the use of cookies and related technologies. This website information is used to provide and inform targeted advertising, as well as to provide advertising-related services such as reporting, attribution, analytics, and market research. * **To Integration Partners**: When you choose to activate a specific integration feature, we may share personal data with our relevant integration partners, or we may allow our relevant integration partners to collect personal data directly from you in connection with our services. Our integration partners may use your personal data for their own business and commercial purposes, including to send you information about their products and services. * **To Service Providers:** We engage other third parties to perform certain services on our behalf in connection with the uses of personal data described in the sections above. Depending on the applicable services, these service providers may process personal data on our behalf or have access to personal data while performing services on our behalf. * **To Other Businesses as Needed to Provide Services**: We may share personal data with third parties you engage with through our services or as needed to fulfill a request or transaction including, for example, payment processing services. * **In Connection with a Business Transaction or Reorganization:** We may take part in or be involved with a business transaction or reorganization, such as a merger, acquisition, joint venture, or financing or sale of company assets. We may disclose, transfer, or assign personal data to a third party during negotiation of, in connection with, or as an asset in such a business transaction or reorganization. Also, in the unlikely event of our bankruptcy, receivership, or insolvency, your personal data may be disclosed, transferred, or assigned to third parties in connection with the proceedings or disposition of our assets. * **To Facilitate Legal Obligations and Rights:** We may disclose personal data to third parties, such as legal advisors and law enforcement: * in connection with the establishment, exercise, or defense of legal claims; * to comply with laws or to respond to lawful requests and legal process; * to protect our rights and property and the rights and property of our agents, customers, and others, including to enforce our agreements, policies, and terms of use; * to detect, suppress, or prevent fraud; * to reduce credit risk and collect debts owed to us; * to protect the health and safety of us, our customers, or any person; or * as otherwise required by applicable law. * **With Your Consent or Direction:** We may disclose your personal data to certain other third parties or publicly with your consent or direction. For example, with your permission, we may post your testimonial on our websites. **Your Privacy Choices** **Communication Preferences** * **Email Communication Preferences**: You can stop receiving promotional email communications from us by clicking on the "unsubscribe" link provided in any of our email communications. Please note you cannot opt-out of service-related email communications (such as account verification, transaction confirmation, or service update emails). **Automatic Data Collection Preferences** You may be able to utilize third-party tools and features to restrict our use of automatic data collection technologies. For example, (i) most browsers allow you to change browser settings to limit automatic data collection technologies on websites, (ii) most email providers allow you to prevent the automatic downloading of images in emails that may contain automatic data collection technologies, and (iii) many devices allow you to change your device settings to limit automatic data collection technologies for device applications. Please note that blocking automatic data collection technologies through third-party tools and features may negatively impact your experience using our services, as some features and offerings may not work properly or at all. Depending on the third-party tool or feature you use, you may not be able to block all automatic data collection technologies or you may need to update your preferences on multiple devices or browsers. We do not have any control over these third-party tools and features and are not responsible if they do not function as intended. **Targeted Advertising Preferences** We engage third parties to help us facilitate targeted advertising designed to show you personalized ads based on predictions of your preferences and interests developed using personal data we maintain and personal data our third-party partners obtain from your activity over time and across nonaffiliated websites and other services. The data we and our third-party partners use for purposes of facilitating targeted advertising, as well as to provide advertising-related services such as reporting, attribution, analytics, and market research, are primarily collected through the use of a variety of automatic data collection technologies on our and other websites, including cookies, web beacons, pixels, embedded scripts, SDKs, location-identifying technologies and logging technologies. We may share a common account identifier (such as a hashed email address) with our third-party advertising partners to help link the personal data we and our third-party partners collect to the same person, or otherwise target advertising to an individual on a third-party website or platform. In addition to taking the steps set forth in the Automatic Data Collection Preferences section above, you may be able to further exercise control over the advertisements that you see by leveraging one or more targeted advertising opt-out programs. For example: * **Device-Specific Opt-Out Programs**: Certain devices provide individuals the option to turn off targeted advertising for the entire device (such as Apple devices through their App Tracking Transparency framework or Android devices through their opt out of ads personalization feature). Please refer to your device manufacturer's user guides for additional information about implementing any available device-specific targeted advertising opt-outs. * **Digital Advertising Alliance**: The [Digital Advertising Alliance](https://digitaladvertisingalliance.org/) allows individuals to opt out of receiving online interest-based targeted advertisements from companies that participate in their program. Please follow the instructions at [https://optout.aboutads.info/?c=2\&lang=EN](https://optout.aboutads.info/?c=2\&lang=EN) for browser-based advertising and [https://www.youradchoices.com/appchoices](https://www.youradchoices.com/appchoices) for app-based advertising to opt out of targeted advertising carried out by our third-party partners and other third parties that participate in the Digital Advertising Alliance's self-regulatory program. * **Network Advertising Initiative**: The [Network Advertising Initiative](https://thenai.org/) also provides individuals instructions for further controlling how information is used for online advertising. Please follow the instructions at [https://thenai.org/how-to-opt-out/](https://thenai.org/how-to-opt-out/) to exercise these controls. * **Platform-Specific Opt-Out Programs**: Certain third-party platforms provide individuals the option to turn off targeted advertising for the entire platform (such as certain social media platforms). Please refer to your platform provider's user guides for additional information about implementing any available platform-specific targeted advertising opt-outs. Please note that when you opt out of receiving interest-based advertisements through one of these programs, this does not mean you will no longer see advertisements from us or on our services. Instead, it means that the online ads you do see from relevant program participants should not be based on your interests. We are not responsible for the effectiveness of, or compliance with, any third parties' opt-out options or programs or the accuracy of their statements regarding their programs. In addition, program participants may still use automatic data collection technologies to collect information about your use of our website, including for analytics and fraud prevention as well as any other purpose permitted under the applicable advertising industry program. **Children's Personal Data** Our services are not directed to, and we do not intend to, or knowingly, collect or solicit personal data from children under the age of 13. If an individual is under the age of 13, they should not use our services or otherwise provide us with any personal data either directly or by other means. If a child under the age of 13 has provided personal data to us, we encourage the child's parent or guardian to contact us to request that we remove the personal data from our systems. If we learn that any personal data we collect has been provided by a child under the age of 13, we will promptly delete that personal data. **Third-Party Websites and Services** Our websites and other services may include links to or redirect you to third-party websites, plug-ins, applications, or other services, including social media services where you may connect with us. Third-party websites and other services may also reference or link to our websites and services. This Privacy Notice does not apply to any personal data practices of these third-party websites, plug-ins, applications, or other services. To learn about these third parties' personal data practices, please visit their respective privacy notices. **Updates to This Privacy Notice** We may update this Privacy Notice from time to time. When we make changes to this Privacy Notice, we will change the date at the beginning of this Privacy Notice. If we make material changes to this Privacy Notice, we will notify individuals by email to their registered email address, by prominent posting on this website or our other platforms, or through other appropriate communication channels. All changes shall be effective from the date of publication unless otherwise provided. **Contact Us** If you have any questions or requests in connection with this Privacy Notice or other privacy-related matters, please contact us at: [humans@conductor.build](mailto:humans@conductor.build). --- title: "Team | Conductor" url: "/team" description: "We want Conductor to be a place where people do the best work of their lives: in person, with incredible people, toward a formidable goal, holding each other to the highest standards." --- # Meet the Conductors Before Conductor, Charlie worked as a quantitative researcher at a [hedge fund](https://point72.com/), and led growth at Replicate where he created apps that were used by millions. One time he [accidentally struck fear into the heart of Hollywood](https://web.archive.org/web/20231117033051/https://www.businessinsider.com/david-attenborough-ai-video-hollywood-actors-afraid-sag-aftra-2023-11). Charlie started Conductor with Jackson in the summer of 2024 to build the best interface for managing your AIs, eat lots of ice cream, and do the best work of our lives. Jackson first learned to code in Microsoft Visual Basic 2005, and he's been hooked ever since. Before starting Conductor, he built ML infrastructure at Netflix, researched automated negotiating agents at Brown, and, with Charlie, built [Shindig](https://shindig.life/), the first, best, and only way to host a party from the command line. In his free time he enjoys reading [Garner's Modern English Usage](https://en.wikipedia.org/wiki/Garner%27s_Modern_English_Usage). Guillaume worked as a staff engineer at Airbnb, and before that he was at Snap. Lewis worked at YC. Before that he was at Pave. He likes [penguins](https://tuxedosam.dev/). Tywen is an artist turned engineer. He has imaged [data centers](https://tywenkelly.com/Lensless-Horizon) and wondered about [worlding](https://e-scapes.blog/posts/worlds-made-without-hands). He has worked in VR, AI, and GovTech. Kaden is studying at the University of Chicago and was previously at Replit. He also co-created the card game [Race to Kepler](https://racetokepler.com). Sam wore many hats before donning his Conductor cap. He (literally) built a [craft brewery in Seattle](https://www.instagram.com/fairislebrewing/?hl=en) before serving as Chief of Staff at a $10B RIA. He then took a brief detour to get his MBA at MIT Sloan, before spending the next four years as a VC. He also moonlights as one of the top coaches in the sport of Ultimate Frisbee (he met Charlie and Jackson playing Ultimate at Brown). At Conductor, Sam leads all things operations, ensuring there is always plenty of yogurt in the fridge. --- title: "Terms of service | Conductor" url: "/terms" description: "Customer terms and conditions for using Conductor." --- # Customer Terms and Conditions [#customer-terms-and-conditions] *Last Modified: March 30, 2026* **Welcome to Conductor** These Customer Terms and Conditions (this "**Agreement**"), effective as of the date on which you click a button or check a box acknowledging your acceptance of this Agreement or you execute with Conductor an Order that incorporates this Agreement by reference (the "**Effective Date**"), is by and between Melty Labs, Inc., a Delaware corporation with offices located at 2261 Market St, STE 70582, San Francisco, CA 94114 ("**Conductor**") and the entity on whose behalf the individual accepting this Agreement accepts this Agreement ("**Customer**"). The individual accepting this Agreement hereby represents and warrants that it is duly authorized by the entity on whose behalf it accepts this Agreement to so accept this Agreement. Conductor and Customer may be referred to herein collectively as the "**Parties**" or individually as a "**Party**." PLEASE READ THESE TERMS CAREFULLY TO ENSURE THAT YOU UNDERSTAND EACH PROVISION. THESE TERMS CONTAIN A MANDATORY ARBITRATION PROVISION THAT REQUIRES THE USE OF ARBITRATION TO RESOLVE DISPUTES. The Parties agree as follows: 1. **Definitions.** "**Authorized User**" means Customer's employees, consultants, contractors, and agents who are authorized by Customer to use the Platform under this Agreement. "**Client-Side Software**" means any Conductor software that Conductor distributes to Customer for use on systems under Customer's administrative control. "**Conductor IP**" means the Platform, and any and all intellectual property provided to Customer or any Authorized User in connection with the foregoing. For the avoidance of doubt, Conductor IP includes Usage Data and any information, data, or other content derived from Conductor's provision of the Platform but does not include Customer Data. "**Customer Data**" means information, data, and other content, in any form or medium, that is submitted, posted, or otherwise transmitted by or on behalf of Customer or an Authorized User through the Platform; provided that, for purposes of clarity, Customer Data as defined herein does not include Usage Data. "**Customer Systems**" means Customer's information technology infrastructure, including computers, software, databases, electronic systems (including database management systems), and networks, whether operated directly by Customer or through the use of third-party platforms or service providers (other than Conductor). "**Harmful Code**" means any software, hardware, or other technology, device, or means, including any virus, worm, malware, or other malicious computer code, the purpose or effect of which is to permit unauthorized access to, or to destroy, disrupt, disable, distort, or otherwise harm or impede in any manner any (i) computer, software, firmware, hardware, system, or network; or (ii) any application or function of any of the foregoing or the security, integrity, confidentiality, or use of any data processed thereby. "**Hosted Software**" means any Conductor software in a Conductor-hosted environment that Conductor makes available to Customer. "**Order**" means: (i) a purchase order, order form, or other ordering document entered into by the Parties that incorporates this Agreement by reference; or (ii) if Customer registered for the Platform through Conductor's online ordering process, the results of such online ordering process. "**Platform**" means Conductor's proprietary hosted AI automation software platform, which may include (i) the Client-Side Software, and (ii) the Hosted Software. "**Personal Data**" means any information that, individually or in combination, does or can identify a specific individual or by or from which a specific individual may be identified, contacted, or located, including without limitation all data considered "personal data", "personally identifiable information", or something similar under applicable laws, rules, or regulations relating to data privacy. "**Professional Services**" means training, migration, implementation, integration, or other professional services that are memorialized in writing in a Statement of Work and provided to Customer in connection with its use of the Platform hereunder. "**Sensitive Data**" means: (i) special categories of data enumerated in European Union Regulation 2016/679, Article 9(1) or any successor legislation; (ii) protected health information as defined in the Health Insurance Portability and Protection Act, as amended ("**HIPAA**"); (iii) payment cardholder information or financial account information, including bank account numbers or other personally identifiable financial information; (iv) social security numbers, driver's license numbers, or other government identification numbers; (v) other information subject to regulation or protection under specific laws such as the Children's Online Privacy Protection Act ("**COPPA**") or the Gramm-Leach-Bliley Act ("**GLBA**"), in each case as amended, or related rules or regulations; or (vi) any data similar to the above protected under applicable laws, rules, or regulations. "**Statement of Work**" means a written statement of work for Professional Services executed by both Parties that incorporates this Agreement by reference. "**Subscription Period**" means the time period identified on the Order during which Customer's Authorized Users may access and use the Platform. "**Third-Party Products**" means products, services, and applications provided by a third party and used by Customer in connection with the Platform. For purposes of clarity, Third-Party Products does not include products, services, and applications provided by a third party and used by Company to operate, provide, maintain, or manage the Platform. "**Usage Data**" means usage data collected and processed by Conductor in connection with Customer's use of the Platform, including without limitation, telemetry data, data used to identify the source and destination of a communication, activity logs, and data used to optimize and maintain performance of the Platform, and to investigate and prevent system abuse. "**Usage Limitations**" means the usage limitations set forth in this Agreement and the Order, including without limitation any limitations on the number of Authorized Users (if any), and the applicable product, pricing, and support tiers agreed-upon by the Parties. 2. **Platform Usage.** Subject to and conditioned on Customer's compliance with the terms and conditions of this Agreement: 2.1. **Client-Side Software.** If Conductor provides to Customer any Client-Side Software, Conductor hereby grants to Customer a non-transferable (except in accordance with Section 13.8), non-exclusive, and non-sublicensable license during the Subscription Period to install and use the Client-Side Software specified in the Order in accordance with the Documentation. Such use is limited to Customer's internal business purposes and the features and functionalities specified in the Order. Licenses are not fungible and may not be reallocated or expanded by Customer to any purpose, configuration, or module not specified in the Order without Conductor's prior written approval. 2.2. **Hosted Software.** If Conductor provides to Customer any Hosted Software, Customer may, solely through its Authorized Users, access and use the Platform during the Subscription Period on a non-exclusive, non-transferable (except in compliance with Section 13.8), and non-sublicensable basis. Such use is limited to Customer's internal business purposes and the features and functionalities specified in the Order. Each Authorized User must have its own unique account on the Platform and Authorized Users may not share their account credentials with one another or any third party. Customer will be responsible for all of the acts and omissions of its Authorized Users in connection with this Agreement and for all use of Authorized Users' accounts. 2.3. **Restrictions.** Customer shall not at any time, directly or indirectly, and shall not permit any Authorized Users to: (i) copy, modify, or create derivative works of any Conductor IP, whether in whole or in part; (ii) rent, lease, lend, sell, license, sublicense, assign, distribute, publish, transfer, or otherwise make available the Platform to any third party; (iii) reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to any software component of the Platform, in whole or in part; (iv) remove any proprietary notices from any Conductor IP; (v) use any Conductor IP in any manner or for any purpose that infringes, misappropriates, or otherwise violates any intellectual property right or other right of any person, or that violates any applicable law; (vi) access or use any Conductor IP for purposes of competitive analysis of Conductor or the Platform, the development, provision, or use of a competing software service or product, or any other purpose that is to Conductor's detriment or commercial disadvantage provided, however, that subject to the other terms and conditions of this Agreement, Customer shall be permitted to develop software that interfaces with any application programming interfaces ("**APIs**") Conductor makes available for Customer's use under this Agreement, provided further that Customer shall not attempt to, or encourage any third party to, sell, rent, lease, license, sublicense, distribute, transfer, or syndicate such software, without prior written approval from Conductor; (vii) bypass or breach any security device or protection used by the Platform or access or use the Platform other than by an Authorized User through the use of valid access credentials; (viii) input, upload, transmit, or otherwise provide to or through the Platform any information or materials, including Customer Data, that are unlawful or injurious or that infringe or otherwise violate any third party's intellectual property or other rights, or that contain, transmit, or activate any Harmful Code; (ix) use any Conductor IP for any activity where use or failure of the Conductor IP could lead to death, personal injury, or environmental damage, including life support systems, emergency services, nuclear facilities, autonomous vehicles, or air traffic control; or (x) use Output (as defined below) to develop any artificial intelligence ("**AI**") models that compete with Conductor's products or services. 2.4. **Data Rights and Outputs.** This Section 2.4 applies solely to the extent that Conductor provides, and Customer uses, any Hosted Software under the Agreement. (a) **Customer Data.** Customer hereby grants to Conductor a non-exclusive, royalty-free, worldwide license to reproduce, distribute, and otherwise use and display the Customer Data and perform all acts with respect to the Customer Data as may be necessary for Conductor to provide the Platform. (b) **Security Measures.** Conductor shall use commercially reasonable efforts to maintain the security and integrity of the Platform and the Customer Data. Customer acknowledges and agrees that the Platform may be subject to limitations on the length of time that Customer Data will be stored, and the amount of Customer Data that may be stored, and that Customer Data which exceeds either of such limitations may be automatically deleted by the Platform. Conductor may delete all Customer Data upon termination or expiration of this Agreement. In addition, and notwithstanding anything to the contrary, Customer acknowledges and agrees that Conductor may internally use and modify (but not disclose) Customer Data to provide the Platform to Customer. Customer represents and warrants that it has all rights, consents, and authorizations necessary to grant such rights to Conductor. (c) **Processing of Personal Data; No Sensitive Data.** Conductor's rights and obligations with respect to Personal Data that it collects directly from individuals are set forth in Conductor's [Privacy Notice](/privacy). Personal Data processed by Conductor on behalf of Customer will be governed by the terms of this Agreement. Notwithstanding the foregoing, Customer acknowledges and agrees that: (i) the Platform is not designed to store Sensitive Data; and (ii) Customer will not use the Platform to store Sensitive Data and will not submit, post, or otherwise transmit through the Platform any Customer Data that includes or constitutes Sensitive Data. 2.5. **AI Technologies.** (a) **Inputs and Output.** The Platform includes features and functionalities supported by AI technologies. Customer may submit inputs via the Platform ("**Inputs**") and receive outputs from the Platform based on such Inputs ("**Output**"). If Conductor provides and Customer uses any Hosted Software under this Agreement, then Inputs are Customer Data. To the extent Customer deploys Client-Side Software or otherwise configures the Platform so Inputs, Output, and Customer Data remain solely on Customer Systems, Conductor will not access or store any such Inputs, Output, or Customer Data except as expressly authorized by Customer or as necessary to provide the specific features of the Hosted Software that Customer has enabled. (b) **Ownership and Usage Limitations.** As between Conductor and Customer, and to the extent permitted by applicable law, Customer: (i) retains all ownership rights in its Inputs; and (ii) owns all Output. Except to the extent otherwise expressly set forth in this Agreement, Conductor will only use Inputs as necessary to provide Customer with the Platform, comply with applicable law, and enforce Conductor's policies. For purposes of clarity, Conductor will not use Inputs (including without limitation any Customer-provided code or prompts) or Output (including without limitations any generated code) to train, fine-tune, or otherwise improve Conductor's or any third party's AI models, or for product development or benchmarking purposes, without Customer's separate prior written consent. (c) **Disclaimers.** Customer acknowledges that Output may not be unique and other users may receive similar content from the Platform, and such similar content is not considered "Output" owned by Customer hereunder. Customer is solely responsible for all Input and represents and warrants that it has all rights, licenses, and permissions required to provide Inputs. Customer is solely responsible for its use of all Output and evaluating the Output for accuracy and appropriateness for its use cases, including by utilizing human review where appropriate. ALL OUTPUT IS PROVIDED "AS IS" WITHOUT WARRANTIES OF ANY KIND. 2.6. **Reservation of Rights.** Conductor reserves all rights not expressly granted to Customer in this Agreement. Except for the limited rights and licenses expressly granted under this Agreement, nothing in this Agreement grants, by implication, waiver, estoppel, or otherwise, to Customer or any third party any intellectual property rights or other right, title, or interest in or to the Conductor IP. 2.7. **Suspension.** Notwithstanding anything to the contrary in this Agreement, Conductor may temporarily suspend Customer's and any Authorized User's access to any portion or all of the Platform if: (i) Conductor reasonably determines that (a) there is a threat or attack on any of the Conductor IP; (b) Customer's or any Authorized User's use of the Conductor IP disrupts or poses a security risk to the Conductor IP or to any other customer or vendor of Conductor; (c) Customer, or any Authorized User, is using the Conductor IP for fraudulent or illegal activities; (d) subject to applicable law, Customer has ceased to continue its business in the ordinary course, made an assignment for the benefit of creditors or similar disposition of its assets, or become the subject of any bankruptcy, reorganization, liquidation, dissolution, or similar proceeding; (e) Conductor's provision of the Platform to Customer or any Authorized User is prohibited by applicable law; or (f) any Customer Data submitted, posted, or otherwise transmitted by or on behalf of Customer or an Authorized User through the Platform may infringe or otherwise violate any third party's intellectual property or other rights; (ii) any vendor of Conductor has suspended or terminated Conductor's access to or use of any Third-Party Products required to enable Customer to access the Platform; or (iii) in accordance with Section 6.1 (any such suspension described in subclauses (i), (ii), or (iii), a "**Platform Suspension**"). Conductor shall use commercially reasonable efforts to provide written notice of any Platform Suspension to Customer and to provide updates regarding resumption of access to the Platform following any Platform Suspension. Conductor shall use commercially reasonable efforts to resume providing access to the Platform as soon as reasonably possible after the event giving rise to the Platform Suspension is cured. Conductor will have no liability for any damage, liabilities, losses (including any loss of data or profits), or any other consequences that Customer or any Authorized User may incur as a result of a Platform Suspension. 2.8. **Usage Data.** Notwithstanding anything to the contrary in this Agreement, Conductor may process Usage Data to monitor, maintain, and optimize the Platform and for any other lawful purpose. As between Conductor and Customer, all right, title, and interest in and to such Usage Data is owned solely and exclusively by Conductor. 2.9. **Open Source Components.** Certain aspects of the Platform, such as the Client-Side Software, may contain or be distributed with open source software code or libraries ("**Open Source Components**"). Conductor will provide a list of Open Source Components for a particular version of any distributed portion of the Platform, such as the Client-Side Software, on Customer's request. To the extent required by the license applicable to such Open Source Components: (i) Conductor will use reasonable efforts to deliver to Customer any notices or other materials (such as source code); and (ii) the terms of such licenses will apply to such Open Source Components in lieu of the terms of this Agreement. To the extent the terms of such licenses prohibit any of the restrictions in this Agreement with respect to any particular Open Source Component, such restrictions will not apply to such Open Source Component. To the extent the terms of such licenses require Conductor to make an offer to provide source code or related information in connection with the Open Source Component, such offer is hereby made. For purposes of clarity, Open Source Components are Third-Party Products. 3. **Customer Responsibilities.** 3.1. **General.** Customer is responsible and liable for all uses of the Platform resulting from access provided by Customer, directly or indirectly, whether such access or use is permitted by or in violation of this Agreement. Without limiting the generality of the foregoing, Customer is responsible for all acts and omissions of Authorized Users, and any act or omission by an Authorized User that would constitute a breach of this Agreement if taken by Customer will be deemed a breach of this Agreement by Customer. Customer shall use reasonable efforts to make all Authorized Users aware of this Agreement's provisions as applicable to such Authorized User's use of the Platform and shall cause Authorized Users to comply with such provisions. 3.2. **Third-Party Products.** Conductor may from time to time make Third-Party Products available to Customer or Conductor may allow for certain Third-Party Products to be integrated with the Platform to allow for, among other things, the transmission of Customer Data from such Third-Party Products into the Platform. For purposes of this Agreement, such Third-Party Products are subject to their own terms and conditions. Conductor is not responsible for the operation of any Third-Party Products and makes no representations or warranties of any kind with respect to Third-Party Products or their respective providers. If Customer does not agree to abide by the applicable terms for any such Third-Party Products, then Customer should not install or use such Third-Party Products. By authorizing Conductor to transmit Customer Data from Third-Party Products into the Platform, Customer represents and warrants to Conductor that it has all right, power, and authority to provide such authorization. 3.3. **Customer Control and Responsibility.** Customer has and will retain sole responsibility for: (i) all Customer Data, including its content and use; (ii) all information, instructions, and materials provided by or on behalf of Customer or any Authorized User in connection with the Platform; (iii) Customer Systems; (iv) the security and use of Customer's and its Authorized Users' access credentials; and (v) all access to and use of the Platform directly or indirectly by or through the Customer Systems or its Authorized Users' access credentials, with or without Customer's knowledge or consent, including all results obtained from, and all conclusions, decisions, and actions based on, such access or use. 4. **Support.** During the Subscription Period, Conductor will use commercially reasonable efforts to provide Customer with basic customer support via Conductor's standard support channels during Conductor's normal business hours. 5. **Professional Services.** Conductor will perform Professional Services as described in an Order or Statement of Work. Customer will provide Conductor all reasonable cooperation required for Conductor to perform the Professional Services, including without limitation timely access to any reasonably required Customer materials, information, or personnel. Subject to any limitations identified in an Order or Statement of Work, Customer will reimburse Conductor's reasonable travel and lodging expenses incurred in providing Professional Services. To the extent the Professional Services result in any software code or other work product of any kind ("**Work Product**"), all such Work Product will remain owned solely and exclusively by Conductor and may be used by Customer solely in connection with Customer's authorized use of the Platform under this Agreement. 6. **Fees and Taxes.** 6.1. **Fees.** The Platform may be provided for a fee or other charge. Customer shall pay Conductor the fees ("**Fees**") identified in the Order without offset or deduction at the cadence identified in the Order (e.g., monthly or annually). Fees paid by Customer are non-refundable. Customer shall make all payments hereunder in US dollars by a mutually agreed-upon payment method. If Customer pays via invoice, Customer will pay the invoiced amount within thirty (30) calendar days of the invoice date. If Customer fails to make any payment when due, and Customer has not notified Conductor in writing within ten (10) days of the payment becoming due and payable that the payment is subject to a good faith dispute, without limiting Conductor's other rights and remedies: (i) Conductor may charge interest on the undisputed past due amount at the rate of 1.5% per month, calculated daily and compounded monthly or, if lower, the highest rate permitted under applicable law; (ii) Customer shall reimburse Conductor for all reasonable costs incurred by Conductor in collecting any late payments or interest, including attorneys' fees, court costs, and collection agency fees; and (iii) if such failure continues for ten (10) days or more, Conductor may suspend Customer's and its Authorized Users' access to all or any part of the Platform until such amounts are paid in full. 6.2. **Taxes.** All Fees and other amounts payable by Customer under this Agreement are exclusive of taxes and similar assessments. Customer is responsible for all sales, use, and excise taxes, and any other similar taxes, duties, and charges of any kind imposed by any federal, state, or local governmental or regulatory authority on any amounts payable by Customer hereunder, other than any taxes imposed on Conductor's income. 7. **Confidential Information.** 7.1. **Definition.** From time to time during the Subscription Period, either Party may disclose or make available to the other Party information about its business affairs, products, confidential intellectual property, trade secrets, third-party confidential information, and other sensitive or proprietary information, whether orally or in written, electronic, or other form or media that: (i) is marked, designated or otherwise identified as "confidential" or something similar at the time of disclosure or within a reasonable period of time thereafter; or (ii) would be considered confidential by a reasonable person given the nature of the information or the circumstances of its disclosure (collectively, "**Confidential Information**"). Except for Personal Data, Confidential Information does not include information that, at the time of disclosure is: (a) in the public domain; (b) known to the receiving Party at the time of disclosure; (c) rightfully obtained by the receiving Party on a non-confidential basis from a third party; or (d) independently developed by the receiving Party without use of, reference to, or reliance upon the disclosing Party's Confidential Information. 7.2. **Duty.** The receiving Party shall not use the disclosing Party's Confidential Information except to perform its obligations and exercise its rights hereunder nor shall it disclose the disclosing Party's Confidential Information to any person or entity, except to the receiving Party's employees, contractors, and agents who have a need to know the Confidential Information for the receiving Party to exercise its rights or perform its obligations hereunder ("**Representatives**"). The receiving Party will be responsible for all the acts and omissions of its Representatives as they relate to Confidential Information hereunder. Notwithstanding the foregoing, each Party may disclose Confidential Information to the limited extent required (i) in order to comply with the order of a court or other governmental body, or as otherwise necessary to comply with applicable law, provided that the Party making the disclosure pursuant to the order shall first have given written notice to the other Party and made a reasonable effort to obtain a protective order; or (ii) to establish a Party's rights under this Agreement, including to make required court filings. Further, notwithstanding the foregoing, each Party may disclose the terms and existence of this Agreement to its actual or potential investors, debtholders, acquirers, or merger partners under customary confidentiality terms. 7.3. **Return of Materials; Effects of Termination/Expiration.** On the expiration or termination of the Agreement, the receiving Party shall promptly return to the disclosing Party all copies, whether in written, electronic, or other form or media, of the disclosing Party's Confidential Information, or destroy all such copies and certify in writing to the disclosing Party that such Confidential Information has been destroyed. Each Party's obligations of non-use and non-disclosure with regard to Confidential Information are effective as of the Effective Date and will expire three (3) years from the date of termination or expiration of this Agreement; provided, however, with respect to any Confidential Information that constitutes a trade secret (as determined under applicable law), such obligations of non-disclosure will survive the termination or expiration of this Agreement until such Confidential Information is no longer considered a trade secret under applicable law through no wrongful act or omission of the receiving Party. 8. **Intellectual Property Ownership; Feedback.** 8.1. **Conductor IP.** Customer acknowledges that, as between Customer and Conductor, Conductor owns all right, title, and interest, including all intellectual property rights, in and to the Conductor IP and, with respect to Third-Party Products, the applicable third-party providers own all right, title, and interest, including all intellectual property rights, in and to the Third-Party Products. 8.2. **Customer Data and Output.** Conductor acknowledges that, as between Conductor and Customer, Customer owns all right, title, and interest, including all intellectual property rights, in and to the Customer Data and Output. 8.3. **Feedback.** If Customer or any of its employees or contractors sends or transmits any communications or materials to Conductor by mail, email, telephone, or otherwise, suggesting or recommending changes to the Conductor IP, including without limitation, new features or functionality relating thereto, or any comments, questions, suggestions, or the like ("**Feedback**"), Conductor is free to use such Feedback irrespective of any other obligation or limitation between the Parties governing such Feedback. 9. **Warranty Disclaimer.** THE CONDUCTOR IP IS PROVIDED "AS IS" AND CONDUCTOR HEREBY DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE. CONDUCTOR SPECIFICALLY DISCLAIMS ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, AND ALL WARRANTIES ARISING FROM COURSE OF DEALING, USAGE, OR TRADE PRACTICE. CONDUCTOR MAKES NO WARRANTY OF ANY KIND THAT THE CONDUCTOR IP, OR ANY PRODUCTS OR RESULTS OF THE USE THEREOF, WILL MEET CUSTOMER'S OR ANY OTHER PERSON'S REQUIREMENTS, OPERATE WITHOUT INTERRUPTION, ACHIEVE ANY INTENDED RESULT, BE COMPATIBLE OR WORK WITH ANY SOFTWARE, SYSTEM OR OTHER PLATFORM, OR BE SECURE, ACCURATE, COMPLETE, FREE OF HARMFUL CODE, OR ERROR FREE. 10. **Indemnification.** 10.1. **Conductor Indemnification.** (a) Conductor shall indemnify, defend, and hold harmless Customer from and against any and all losses, damages, liabilities, costs (including reasonable attorneys' fees) ("**Losses**") incurred by Customer resulting from any claim, suit, action, or proceeding brought by an unaffiliated third party ("**Third-Party Claim**") against Customer alleging that the Platform, or any use of the Platform in accordance with this Agreement, infringes or misappropriates such third party's US intellectual property rights; provided that Customer promptly notifies Conductor in writing of the claim, cooperates with Conductor, and allows Conductor sole authority to control the defense and settlement of such claim. (b) If such a claim is made or appears possible, Customer agrees to permit Conductor, at Conductor's sole discretion: to (i) modify or replace the Platform, or component or part thereof, to make it non-infringing; or (ii) obtain the right for Customer to continue use. If Conductor determines that neither alternative is reasonably commercially available, Conductor may terminate this Agreement, in its entirety or with respect to the affected component or part, effective immediately on written notice to Customer. (c) This Section 10.1 will not apply to the extent that the alleged infringement arises from: (i) use of the Platform in combination with data, software, hardware, equipment, or technology not provided by Conductor or authorized by Conductor in writing; (ii) modifications to the Platform not made by Conductor; (iii) Customer Data; or (iv) Third-Party Products. 10.2. **Customer Indemnification.** Customer shall indemnify, hold harmless, and, at Conductor's option, defend Conductor from and against any Losses resulting from any Third-Party Claim alleging that the Customer Data, or any use of the Customer Data in accordance with this Agreement, infringes or misappropriates such third party's intellectual property or other rights and any Third-Party Claims based on Customer's or any Authorized User's (i) negligence or willful misconduct; (ii) use of the Platform in a manner not authorized by this Agreement; (iii) use of the Platform in combination with data, software, hardware, equipment or technology not provided by Conductor or authorized by Conductor in writing; or (iv) use of or reliance on any Output; in each case provided that Customer may not settle any Third-Party Claim against Conductor unless Conductor consents to such settlement, and further provided that Conductor will have the right, at its option, to defend itself against any such Third-Party Claim or to participate in the defense thereof by counsel of its own choice. 10.3. **Sole Remedy.** THIS SECTION 10 SETS FORTH CUSTOMER'S SOLE REMEDIES AND CONDUCTOR'S SOLE LIABILITY AND OBLIGATION FOR ANY ACTUAL, THREATENED, OR ALLEGED CLAIMS THAT THE SERVICE INFRINGE, MISAPPROPRIATE, OR OTHERWISE VIOLATE ANY INTELLECTUAL PROPERTY RIGHTS OF ANY THIRD PARTY. 11. **Limitations of Liability.** IN NO EVENT WILL CONDUCTOR BE LIABLE UNDER OR IN CONNECTION WITH THIS AGREEMENT UNDER ANY LEGAL OR EQUITABLE THEORY, INCLUDING BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, AND OTHERWISE, FOR ANY: (I) CONSEQUENTIAL, INCIDENTAL, INDIRECT, EXEMPLARY, SPECIAL, ENHANCED, OR PUNITIVE DAMAGES; (II) INCREASED COSTS, DIMINUTION IN VALUE OR LOST BUSINESS, PRODUCTION, REVENUES, OR PROFITS; (III) LOSS OF GOODWILL OR REPUTATION; (IV) USE, INABILITY TO USE, LOSS, INTERRUPTION, DELAY OR RECOVERY OF ANY DATA, OR BREACH OF DATA OR SYSTEM SECURITY; OR (V) COST OF REPLACEMENT GOODS OR SERVICES, IN EACH CASE REGARDLESS OF WHETHER CONDUCTOR WAS ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES OR SUCH LOSSES OR DAMAGES WERE OTHERWISE FORESEEABLE. IN NO EVENT WILL CONDUCTOR'S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT UNDER ANY LEGAL OR EQUITABLE THEORY, INCLUDING BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, AND OTHERWISE EXCEED (I) THE TOTAL AMOUNTS PAID TO CONDUCTOR UNDER THIS AGREEMENT IN THE TWELVE (12) MONTHS IMMEDIATELY PRECEDING THE CLAIM, OR (II) ONE THOUSAND U.S. DOLLARS ($1,000), WHICHEVER IS GREATER. 12. **Subscription Period and Termination.** 12.1. **Subscription Period.** The initial term of this Agreement begins on the Effective Date and, unless terminated earlier pursuant to this Agreement's express provisions, will continue in effect for the period identified in the Order (the "**Initial Subscription Period**"). This Agreement will automatically renew for additional successive terms equal to the length of the Initial Subscription Period unless earlier terminated pursuant to this Agreement's express provisions or either Party gives the other Party written notice of non-renewal at least thirty (30) days prior to the expiration of the then-current term (each a "**Renewal Subscription Period**" and together with the Initial Subscription Period, the "**Subscription Period**"). 12.2. **Termination.** In addition to any other express termination right set forth in this Agreement: (a) Conductor may terminate this Agreement, effective on written notice to Customer, if Customer: (i) fails to pay any amount when due hereunder, and such failure continues more than ten (10) calendar days after Conductor's delivery of written notice thereof; or (ii) breaches any of its obligations under Section 2.3 or Section 7; (b) either Party may terminate this Agreement, effective on written notice to the other Party, if the other Party materially breaches this Agreement, and such breach: (i) is incapable of cure; or (ii) being capable of cure, remains uncured thirty (30) calendar days after the non-breaching Party provides the breaching Party with written notice of such breach; or (c) either Party may terminate this Agreement, effective immediately upon written notice to the other Party, if the other Party: (i) becomes insolvent or is generally unable to pay, or fails to pay, its debts as they become due; (ii) files or has filed against it, a petition for voluntary or involuntary bankruptcy or otherwise becomes subject, voluntarily or involuntarily, to any proceeding under any domestic or foreign bankruptcy or insolvency law; (iii) makes or seeks to make a general assignment for the benefit of its creditors; or (iv) applies for or has appointed a receiver, trustee, custodian, or similar agent appointed by order of any court of competent jurisdiction to take charge of or sell any material portion of its property or business. 12.3. **Effect of Expiration or Termination.** Upon expiration or earlier termination of this Agreement, Customer shall immediately discontinue use of the Conductor IP and, without limiting Customer's obligations under Section 7, Customer shall delete, destroy, or return all copies of the Conductor IP and certify in writing to the Conductor that the Conductor IP has been deleted or destroyed. No expiration or termination will affect Customer's obligation to pay all Fees that may have become due before such expiration or termination or entitle Customer to any refund. 12.4. **Survival.** This Section 12.4 and Sections 1, 5, 7, 8, 9, 10, 11, 12.3, and 13 survive any termination or expiration of this Agreement. No other provisions of this Agreement survive the expiration or earlier termination of this Agreement. 13. **Miscellaneous.** 13.1. **Entire Agreement.** This Agreement, together with any other documents incorporated herein by reference, constitutes the sole and entire agreement of the Parties with respect to the subject matter of this Agreement and supersedes all prior and contemporaneous understandings, agreements, and representations and warranties, both written and oral, with respect to such subject matter. In the event of any inconsistency between the statements made in the body of this Agreement, the related Exhibits, and any other documents incorporated herein by reference, the following order of precedence governs: (i) first, this Agreement; and (ii) second, any other documents incorporated herein by reference. Excluding Orders, terms in business forms, purchase orders, quotes, or similar documents used by either Party will not amend or modify this Agreement; any such documents are for administrative purposes only. 13.2. **Notices.** All notices, requests, consents, claims, demands, waivers, and other communications hereunder (each, a "**Notice**") must be in writing and addressed to the Parties at the addresses set forth on the first page of this Agreement or in the Order (or to such other address that may be designated by the Party giving Notice from time to time in accordance with this Section). All Notices must be delivered by personal delivery, nationally recognized overnight courier (with all fees pre-paid) or email (with confirmation of transmission) or certified or registered mail (in each case, return receipt requested, postage pre-paid). Except as otherwise provided in this Agreement, a Notice is effective only: (i) upon receipt by the receiving Party; and (ii) if the Party giving the Notice has complied with the requirements of this Section. 13.3. **Force Majeure.** In no event shall either Party be liable to the other Party, or be deemed to have breached this Agreement, for any failure or delay in performing its obligations under this Agreement (except for any obligations to make payments), if and to the extent such failure or delay is caused by any circumstances beyond such Party's reasonable control, including but not limited to acts of God, flood, fire, earthquake, explosion, war, terrorism, invasion, riot or other civil unrest, strikes, labor stoppages or slowdowns or other industrial disturbances, or passage of law or any action taken by a governmental or public authority, including imposing an embargo. 13.4. **Amendment and Modification.** Conductor may change this Agreement (except for any Orders) from time to time at its discretion. The date on which the Agreement was last modified will be updated at the top of this Agreement. Conductor will provide Customer with reasonable notice prior to any amendments or modifications taking effect, either by emailing the email address associated with Customer's account on the Platform or by another method reasonably designed to provide notice to Customer. If Customer accesses or uses the Platform after the effective date of the revised Agreement, such access and use will constitute Customer's acceptance of the revised Agreement beginning at the next Renewal Subscription Period or, if Customer enters into a new Order with Conductor, as of the date of execution of such Order. 13.5. **Waiver.** No failure or delay by either Party in exercising any right or remedy available to it in connection with this Agreement will constitute a waiver of such right or remedy. No waiver under this Agreement will be effective unless made in writing and signed by an authorized representative of the Party granting the waiver. 13.6. **Severability.** If any provision of this Agreement is invalid, illegal, or unenforceable in any jurisdiction, such invalidity, illegality, or unenforceability will not affect any other term or provision of this Agreement or invalidate or render unenforceable such term or provision in any other jurisdiction. Upon such determination that any term or other provision is invalid, illegal, or unenforceable, the Parties shall negotiate in good faith to modify this Agreement so as to effect their original intent as closely as possible in a mutually acceptable manner in order that the transactions contemplated hereby be consummated as originally contemplated to the greatest extent possible. 13.7. **Governing Law.** This Agreement is governed by and construed in accordance with the internal laws of the State of California without giving effect to any choice or conflict of law provision or rule that would require or permit the application of the laws of any jurisdiction other than those of the State of California. 13.8. **Dispute Resolution.** For any dispute in connection with this Agreement, the Parties agree to first attempt to mutually resolve the dispute informally via negotiation. If the dispute has not been resolved after sixty (60) days, the Parties agree to resolve any claim, dispute, or controversy (excluding any claims for injunctive or other equitable relief as provided below) arising out of or in connection with or relating to this Agreement, or the breach or alleged breach thereof (collectively, "**Claims**"), by binding arbitration by JAMS, under the Optional Expedited Arbitration Procedures then in effect for JAMS, except as provided herein. The arbitration will be conducted in Los Angeles, California unless otherwise mutually agreed. Each Party will be responsible for paying any JAMS filing, administrative and arbitrator fees in accordance with JAMS rules, and the award rendered by the arbitrator may include costs of arbitration, reasonable attorneys' fees and reasonable costs for expert and other witnesses. Any judgment on the award rendered by the arbitrator may be entered in any court of competent jurisdiction. 13.9. **Assignment.** Customer may not assign any of its rights or delegate any of its obligations hereunder, in each case whether voluntarily, involuntarily, by operation of law or otherwise, without the prior written consent of Conductor. Any purported assignment or delegation in violation of this Section will be null and void. No assignment or delegation will relieve the assigning or delegating Party of any of its obligations hereunder. This Agreement is binding upon and inures to the benefit of the Parties and their respective permitted successors and assigns. 13.10. **Export Regulation.** The Platform utilizes software and technology that may be subject to US export control laws, including the US Export Administration Act and its associated regulations. Customer shall not, directly or indirectly, export, re-export, or release the Platform or the underlying software or technology to, or make the Platform or the underlying software or technology accessible from, any jurisdiction or country to which export, re-export, or release is prohibited by law, rule, or regulation. Customer shall comply with all applicable federal laws, regulations, and rules, and complete all required undertakings (including obtaining any necessary export license or other governmental approval), prior to exporting, re-exporting, releasing, or otherwise making the Platform or the underlying software or technology available outside the US. 13.11. **US Government Rights.** Each of the software components that constitute the Platform is a "commercial item" as that term is defined at 48 C.F.R. § 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. § 12.212. Accordingly, if Customer is an agency of the US Government or any contractor therefor, Customer only receives those rights with respect to the Platform as are granted to all other end users, in accordance with (a) 48 C.F.R. § 227.7201 through 48 C.F.R. § 227.7204, with respect to the Department of Defense and their contractors, or (b) 48 C.F.R. § 12.212, with respect to all other US Government users and their contractors. 13.12. **Equitable Relief.** Each Party acknowledges and agrees that a breach or threatened breach by such Party of any of its obligations under Section 7 or, in the case of Customer, Section 2.3, would cause the other Party irreparable harm for which monetary damages would not be an adequate remedy and agrees that, in the event of such breach or threatened breach, the other Party will be entitled to equitable relief, including a restraining order, an injunction, specific performance and any other relief that may be available from any court, without any requirement to post a bond or other security, or to prove actual damages or that monetary damages are not an adequate remedy. Such remedies are not exclusive and are in addition to all other remedies that may be available at law, in equity or otherwise. 13.13. **Publicity.** Conductor may identify Customer as a user of the Platform and may use Customer's name, logo, and other trademarks in Conductor's customer list, press releases, blog posts, advertisements, and website (and all use thereof and goodwill arising therefrom shall inure to the sole and exclusive benefit of Customer). Otherwise, neither Party may use the name, logo, or other trademarks of the other Party for any purpose without the other Party's prior written approval. ## Docs --- title: "Configure your project" url: "/docs/configure-your-project" description: "Set up shared Conductor project settings for new workspaces" --- # Configure your project Conductor can prepare every new workspace the same way, run your project from the Run button, and copy local files that Git does not track. For most projects, start by asking Conductor to inspect the repository and create shared project settings. Use the rest of this page to review what changed or make manual edits. ## Quick start: ask Conductor [#quick-start-ask-conductor] If you have more than one repository in Conductor, create a workspace in the project you want to configure, then paste this prompt there. Review the diff before committing the settings file. The agent should explain why it chose each setup script, run script, file copy pattern, or run mode. Configure personal run scripts in `Settings` in Conductor or `.conductor/settings.local.toml`. Use `.conductor/settings.toml` for team defaults that should be reviewed and merged before they apply to everyone. ## Create project settings [#create-project-settings] Create `.conductor/settings.toml` at the root of your repository when the settings should be shared after the change is merged: ```text your-repo/ ├── .conductor/ │ └── settings.toml ├── package.json └── ... ``` To configure the project manually, add the commands your project needs: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Commit this file when teammates should use the same setup: ```bash git add .conductor/settings.toml git commit -m "Add Conductor project settings" ``` ## Add a setup script [#add-a-setup-script] The setup script runs when Conductor creates a workspace. Use it for commands that prepare the workspace: * Install dependencies. * Generate files. * Create symlinks. * Initialize local project state. For details, see [Setup scripts](/docs/reference/scripts#setup-scripts). ## Add a run script [#add-a-run-script] A run script adds an app, server, test watcher, or other useful project command to the Run button. Use `CONDUCTOR_PORT` when the command starts a local server: ```toml title=".conductor/settings.toml" [scripts] run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Add more `[scripts.run.]` tables when the project has several useful scripts, such as starting a web app, starting a worker, or running a test watcher. Conductor gives each workspace its own port range, so multiple local servers can run at the same time. For details, see [Run scripts](/docs/reference/scripts#run-scripts) and [Conductor variables](/docs/reference/environment-variables). ## Copy local files when needed [#copy-local-files-when-needed] New workspaces start with files tracked by Git. Gitignored files such as `.env.local`, local certificates, and machine specific config appear only when Conductor copies them or your setup script creates them. Use [Files to copy](/docs/reference/files-to-copy) for static gitignored files that every local workspace needs. Use a setup script when the workspace needs commands, generated files, symlinks, or workspace specific values. ## Add project overrides to gitignore [#add-project-overrides-to-gitignore] Use `.conductor/settings.local.toml` for project settings that only apply on your machine. Add it to `.gitignore`: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` ## Know where settings live [#know-where-settings-live] Conductor layers settings from broad to specific: | Scope | File | Use it for | | ----------------- | --------------------------------------- | ----------------------------------------------- | | User settings | `~/.conductor/settings.toml` | Your defaults across projects | | Project overrides | `/.conductor/settings.local.toml` | Your local project overrides | | Project settings | `/.conductor/settings.toml` | Shared project setup after the change is merged | For precedence, schemas, managed settings, and supported keys, see [Settings](/docs/reference/settings) and [User and project settings](/docs/reference/settings/user-project). ## Next steps [#next-steps] * Use [Setup scripts](/docs/reference/scripts#setup-scripts), [Files to copy](/docs/reference/files-to-copy), and [Shell configuration](/docs/reference/shells) when you need workspace setup details. * Use [Run scripts](/docs/reference/scripts#run-scripts) when you need to run the project from Conductor. * Use [Settings reference](/docs/reference/settings/reference) when you need the exact TOML keys Conductor supports. --- title: "Your first workspace" url: "/docs/first-workspace" description: "Import a repository, configure it, and start agent work in an isolated Conductor workspace" --- # Your first workspace A workspace is an isolated copy of your project, backed by Git, for one task or pull request. This guide walks through the first loop: add a repository, prepare the workspace, give an agent context, and review the result. Conductor workspaces isolate development state, not system permissions. Agents and commands still run locally with your user permissions. ## Add a repository [#add-a-repository] After you [install Conductor](/docs/installation), add a repository with one of these options: * **Open project**: choose an existing local repository. * **Open GitHub project**: choose a repository from GitHub. * **Quick start**: create a new repository from Conductor. Conductor uses GitHub from your terminal environment. To confirm GitHub is available, run `gh auth status` in your terminal. ## Create the workspace [#create-the-workspace] After you add a repository, Conductor creates a workspace from it. Each workspace has its own: * Branch. * Working tree. * Setup and run context. Conductor copies files tracked by Git into the workspace. Ignored files, dependencies, local databases, and `.env` files come from your setup script or your project's setup workflow. For the underlying model, see [Isolated workspaces](/docs/concepts/workspaces-and-branches). ## Make it runnable [#make-it-runnable] Before agents change code, make sure the workspace can install dependencies, read local config, and run the project. Use a [setup script](/docs/reference/scripts#setup-scripts) for files and dependencies that Git does not track, such as `.env` files, local databases, generated files, and package installs. Use a [run script](/docs/reference/scripts#run-scripts) to launch your app, server, watcher, or tests from Conductor. Run scripts execute inside the workspace directory and can use `CONDUCTOR_PORT`, so multiple workspaces can run beside each other. You can manage scripts in Repository Settings or share them with your team in [`.conductor/settings.toml`](/docs/reference/scripts/share-with-teammates). ## Start work [#start-work] Start a chat with Claude Code, Codex, Cursor, or OpenCode in Conductor. For a simple task, use one agent in one workspace. Before you ask for changes, attach the context the agent needs: * Mention files, folders, or comments from the composer. * Attach notes, specs, screenshots, and logs. * Put uncommitted handoffs in `.context`. Use the Run button for saved commands and the terminal for ad hoc commands. Commands run inside the workspace, not your original checkout. If your app cannot run cleanly from a workspace directory, use [Spotlight testing](/docs/reference/scripts/spotlight-testing). ## Split work deliberately [#split-work-deliberately] Use multiple agents in the same workspace when they should share the same branch and code state, such as one agent implementing while another reviews or fixes tests. Use separate workspaces when tasks should move independently and become separate pull requests. Create more workspaces with Command + Shift + N or the `...` button next to `New workspace`. You can start from a branch, pull request, GitHub issue, or Linear issue. ## Review, merge, and archive [#review-merge-and-archive] When the workspace is ready: 1. Open the Diff Viewer with Command + Shift + D. 2. Run tests through the terminal, Run button, or Spotlight testing. 3. Open the Checks tab to review git status, CI, deployments, comments, and todos. 4. Create a pull request, merge when ready, and archive the workspace. Next, [configure your project](/docs/configure-your-project), learn the full [Conductor workflow](/docs/concepts/workflow), and decide how to use [parallel agents](/docs/concepts/parallel-agents). --- title: "Introduction" url: "/docs" description: "Learn what Conductor is and where to start in the docs" --- # Introduction Conductor lets you run Claude Code, Codex, Cursor, and OpenCode in parallel. Each task gets its own workspace, branch, files, terminal, diff, and review path. When the work is ready, Conductor helps you review the diff, open a pull request, merge, and archive the workspace. ## Get started [#get-started] Get Conductor running on your Mac. Create an isolated workspace and start agent work. ## Talk to us [#talk-to-us] Join the Conductor community and get support from the team. Send issues, ideas, and feedback to [support@conductor.build](mailto:support@conductor.build) Join the Conductor Discord for community support and discussion. Join the discussion on r/conductorbuild ## Learn more [#learn-more] Start with the workflow, then use the reference pages when you need exact behavior: * [Isolated workspaces](/docs/concepts/workspaces-and-branches) * [Workflow](/docs/concepts/workflow) * [Parallel agents](/docs/concepts/parallel-agents) * [Diff viewer](/docs/reference/diff-viewer) * [Checks](/docs/reference/checks) * [Agent modes](/docs/concepts/agent-modes) --- title: "Install" url: "/docs/installation" description: "Get Conductor running on your Mac" --- # Install Conductor is available for macOS. Install the app, then let Conductor check that your Mac is ready to create workspaces and run agents. ## Download for Mac [#download-for-mac] 1. Press `D` or click **Download Conductor**. 2. Drag the Conductor app to your Applications folder. 3. Open Conductor. Conductor is not available for Windows or Linux yet. [Sign up here](https://docs.google.com/forms/d/1jPQsC8oLNIyjHW3WOsUxK2XNm0Z-BAzdooZuMs9cbFM/viewform) and we will let you know when it is ready. ## Setup checks [#setup-checks] When you open Conductor, it checks for the tools and credentials it needs. If anything is missing, Conductor walks you through setup. Conductor checks for: * GitHub authentication in your terminal environment. To check manually, run `gh auth status`. * Claude Code login, if you plan to use Claude. To sign in manually, run `claude /login`. * Codex login, if you plan to use Codex. To sign in manually, run `codex login`. * Cursor API key, if you plan to use Cursor. Add it in `Settings` -> `Harnesses` -> `Cursor`. You need GitHub and at least one agent provider to use Conductor. ## Next step [#next-step] After Conductor confirms your setup, create [your first workspace](/docs/first-workspace). --- title: "FAQ" url: "/docs/faq" description: "Frequently asked questions about Conductor" --- # FAQ ## What are the city names? [#what-are-the-city-names] Each workspace in Conductor is named after a city. We use cities as memorable, distinct names for different workspaces. The city also serves as a stable name for the workspace directory, which lets your files live in a consistent place where coding agents and other programs can always find them. In addition to the city, we also identify a workspace by its branch name or PR title. In the left sidebar, you'll see the PR title (if a PR is open) or the branch name. Conductor always runs on your Mac, wherever you are. It doesn't actually run in the city, although that would be cool. You can see all the cities you've visited in Conductor at cmd+K -> Passport. ## How does Conductor authenticate to Claude Code, Codex, Cursor, and OpenCode? [#how-does-conductor-authenticate-to-claude-code-codex-cursor-and-opencode] By default, Conductor uses the auth tokens already saved on your machine. If you're logged into Claude Code with an API key, Conductor uses that; if you're logged in with Claude Pro or Max, Conductor uses that. You can also override this by choosing API key mode in Settings → Harnesses, then setting the key in Settings → Environment. Cursor sessions use a Cursor API key. Add it in Settings → Harnesses → Cursor, or set `CURSOR_API_KEY` in Conductor's environment settings. OpenCode sessions use OpenCode provider credentials and models. Add provider API keys in Settings → Harnesses → OpenCode, or configure OpenCode through its own provider setup. For setup and billing details by agent, see [Harnesses](/docs/reference/harnesses). ## What permissions do agents have? [#what-permissions-do-agents-have] Agents in Conductor run with the same permissions as your user account. They can read and write files, run shell commands, and access anything you can access on your machine. Agents run directly on your system without sandboxing. Most users don't experience any problems with this. If you want to be extra safe, you can run Conductor on a separate machine or VM dedicated to development work. ## Does Conductor add its own system prompts? [#does-conductor-add-its-own-system-prompts] Yes. Conductor injects system prompts that explain to the agent that it's running inside Conductor, what a workspace is, and other context. It also injects prompts in response to various actions you take in the Conductor UI (e.g., creating a new workspace, or clicking "Create PR"); you can see and customize these prompts in Settings → \[your repository] → Preferences. ## Why does Conductor request access to Downloads, Reminders, etc.? [#why-does-conductor-request-access-to-downloads-reminders-etc] When an agent or your shell tries to read a file in one of macOS's protected folders, the system displays a permissions pop-up. Conductor itself doesn't need access; it appears as "Conductor" because it's running the agent. Nothing unusual is happening on our end, and we're working to improve the user experience. ## How does Conductor make money? [#how-does-conductor-make-money] Right now we don't. We're a small team running on seed funding from a few great investors who believe in our vision. At some point we plan to charge for collaboration features that help teams make the most of AI agents, but for now we're focused on making Conductor an amazing free tool. ## Which versions of Claude Code, Codex, and OpenCode does Conductor use? [#which-versions-of-claude-code-codex-and-opencode-does-conductor-use] Conductor comes bundled with its own installation of Claude Code and Codex, so that we can ensure compatibility. You can find them at `~/Library/Application Support/com.conductor.app/bin`. Do not update or modify them, or they might be incompatible with Conductor. Cursor sessions use Conductor's Cursor integration and your Cursor API key. There is no Cursor executable path to configure in Conductor settings. OpenCode sessions use Conductor's managed OpenCode integration unless you configure a custom OpenCode executable path. ## Does Conductor support Claude Code agent teams? [#does-conductor-support-claude-code-agent-teams] Yes! In Settings → Environment, add `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to enable Claude Code's experimental agent teams feature. ## Where does Conductor get the repo icon? [#where-does-conductor-get-the-repo-icon] Conductor looks for an icon file in your repository root. It checks for common icon filenames in this order: * `public/apple-touch-icon.png` * `apple-touch-icon.png` * `public/favicon.svg` * `favicon.svg` * `public/favicon.png` * `public/icon.png` * `public/logo.png` * `favicon.png` * `app/icon.png` * `src/app/icon.png` * `public/favicon.ico` * `favicon.ico` * `app/favicon.ico` * `static/favicon.ico` * `src-tauri/icons/icon.png` * `assets/icon.png` * `src/assets/icon.png` The first match is used as the icon shown in the sidebar next to your repo name. ## I'm moving to a new computer, how can I transfer my chats? [#im-moving-to-a-new-computer-how-can-i-transfer-my-chats] The easiest way is to use Apple's Migration Assistant to transfer all your files. This will let you pick up exactly where you left off. If you're up for an adventure, you can also manually copy all files Conductor depends on. Conductor stores files at `~/Library/Application Support/com.conductor.app` and `~/conductor`. Claude Code and Codex store files in `~/.claude` and `~/.codex`. Make sure to copy while Conductor, Codex, and Claude Code are not running, and to use exactly the same destination paths. --- title: "Agent modes" url: "/docs/concepts/agent-modes" description: "Understand Plan Mode, Fast Mode, reasoning controls, and agent-specific session controls" --- # Agent modes Conductor lets you change how an agent approaches a task before or during a chat. These controls affect the current session, not the repository itself. Use Claude Code, Codex, Cursor, or OpenCode when you want a coding agent in a Conductor workspace. You can run one agent by itself, or run multiple agents in separate tabs or workspaces. For setup, billing, and provider-specific limits, see [Harnesses](/docs/reference/harnesses). ## Supported controls [#supported-controls] Open the model picker to choose a Claude Code, Codex, Cursor, or OpenCode model. If Cursor cannot start, check that `CURSOR_API_KEY` is configured in `Settings` -> `Harnesses` -> `Cursor`. If OpenCode cannot start or has no models, check `Settings` -> `Harnesses` -> `OpenCode`. If Codex cannot start, check your OpenAI authentication or subscription setup. Cursor sessions support Composer 2.5 in Conductor. OpenCode sessions use OpenCode models returned by your configured OpenCode providers. ## Plan Mode [#plan-mode] Plan Mode asks the agent to make a plan before editing files. Use it when the task is ambiguous, risky, or broad enough that you want to review the approach first. Plan Mode is useful for: * Refactors with unclear boundaries * Migrations * Multi-file product changes * Debugging where the root cause is not known yet * Work that should be split across multiple agents or workspaces When the plan looks right, approve it or give feedback. If you exit Plan Mode, the agent can move from planning into implementation. ## Fast Mode [#fast-mode] Fast Mode prioritizes speed. Use it for narrow edits, simple fixes, and quick follow-up work. Avoid Fast Mode when the task needs careful codebase analysis, large refactors, or high-stakes reasoning. ## Thinking and reasoning controls [#thinking-and-reasoning-controls] Some models expose thinking or reasoning controls. Higher settings give the agent more room to reason before answering, but may take longer or use more credits. Use higher reasoning for architecture, debugging, migrations, and code review. Use lower reasoning for straightforward edits and short questions. ## Codex personalities [#codex-personalities] Codex sessions can use personalities to change how Codex approaches work. Personalities are session-level controls. Use them when you want a different working style without changing repository instructions. ## Codex goals [#codex-goals] Codex sessions can work toward a goal: a standing objective that Codex keeps pursuing across turns instead of stopping after a single reply. Use a goal for longer tasks that should keep moving without a new prompt at every step. To set a goal, type `/goal` followed by the objective, or click the goal toggle in the composer to send your next message as a goal. While a goal is active, a goal bar above the composer shows the objective, its status, and its token usage when the goal has a token budget. Use the goal bar to pause, resume, edit, or clear the goal. Stopping a turn also pauses the goal, so Codex does not keep working after you ask it to stop. Goals are available for Codex sessions in local workspaces. Cloud workspaces do not support goals yet. ## Skills [#skills] Codex, Claude Code, and OpenCode can use skills in Conductor. If you already have repo or user skills for one agent, you can often reuse them so multiple agents follow the same project conventions. ## Run agents together [#run-agents-together] Use separate tabs when you want Claude Code, Codex, Cursor, or OpenCode to work in the same workspace. Use separate workspaces when the work should happen on different branches. ## Repository guidance [#repository-guidance] Mode controls are temporary. For durable guidance, use Repository Settings or checked-in instruction files such as `AGENTS.md`, `CLAUDE.md`, or skills. --- title: "Git worktrees" url: "/docs/concepts/git-worktrees" description: "Understand how Conductor uses Git worktrees to create isolated coding-agent workspaces" --- # Git worktrees Conductor uses Git worktrees to give each workspace its own files, branch, commands, chats, and review flow. A Git worktree is a second working tree attached to the same repository. Instead of copying the whole project or asking several agents to share one checkout, Conductor creates a separate working tree for each workspace. That lets agents work in parallel without editing the same files on disk. For Git's own reference, see the official [Git worktree documentation](https://git-scm.com/docs/git-worktree). ## How Conductor uses worktrees [#how-conductor-uses-worktrees] When you create a workspace, Conductor creates a Git worktree for that workspace and checks out a branch inside it. That workspace becomes the container for the rest of the workflow: * The agent edits files inside the workspace directory. * Setup, run, terminal, and test commands execute from that workspace directory. * The workspace branch becomes the unit you review, push, and turn into a pull request. * Chats, diffs, PR state, and archive actions stay attached to the same workspace. * Workspace notes and handoffs can live in the gitignored `.context` folder. The original repository checkout remains the project root. Conductor workspaces are usually created under `~/conductor/workspaces//`, but each one is still connected to the same underlying Git repository. ## What is isolated [#what-is-isolated] Each Conductor workspace gets its own working tree. That means code changes, generated files, local terminal commands, and running app processes can belong to one task instead of your main checkout or another agent's task. This is the foundation for parallel agents in Conductor: * One workspace can implement a feature while another investigates a bug. * One branch can be reviewed and merged while another stays experimental. * One agent can run a dev server or tests without taking over another workspace's terminal state. Workspace isolation is development isolation, not a security boundary. Agents and commands still run on your Mac with your user permissions unless you configure stricter controls. ## What is shared [#what-is-shared] Worktrees share the same Git repository data. They use the same history, refs, remotes, and object database, while each workspace has its own checkout on disk. That shared Git backing is why Conductor can create a workspace quickly without cloning the repository again. It is also why normal Git operations still work: you can commit, rename branches, push to `origin`, open a PR, or merge from the Conductor UI or the terminal. ## What Conductor copies [#what-conductor-copies] A new worktree starts from tracked files. Git does not automatically bring along untracked or gitignored local files from your main checkout. That matters for files such as: * `.env.local` * local certificates * generated configuration * tool state that is intentionally gitignored Use [Files to copy](/docs/reference/files-to-copy) when every new workspace needs specific gitignored files. Conductor uses `.worktreeinclude`-style patterns and only copies files that Git already ignores. Use a [setup script](/docs/reference/scripts#setup-scripts) when the workspace needs commands instead of copied files, such as dependency installation, code generation, symlinks, or database setup. ## Branches and worktrees [#branches-and-worktrees] Git only allows a branch to be checked out in one worktree at a time. In Conductor, that means a workspace branch usually belongs to exactly one workspace. If a branch is already checked out in one workspace, Git will not let another workspace or your project root check out that same branch at the same time. Use one of these patterns when you need similar work in more than one place: * Give each worktree its own branch. * Create a new branch from the existing branch. * Switch the first workspace to a different branch before checking out the branch somewhere else. Conductor's workspace and PR flow is built around this rule. A workspace branch is the review unit, and the workspace keeps the agent sessions, diff, terminal state, and PR status together. ## When to create another workspace [#when-to-create-another-workspace] Create another Conductor workspace when work should have its own branch, files, running environment, and review path. Keep agents in one workspace when they need to collaborate on the same branch and latest file state. For the decision model, see [Parallel agents](/docs/concepts/parallel-agents). For the full Conductor workspace model, see [Isolated workspaces](/docs/concepts/workspaces-and-branches). ## How this differs from raw Git worktrees [#how-this-differs-from-raw-git-worktrees] Raw Git worktrees give you separate checkouts. Conductor builds the agent workflow around those checkouts. Conductor handles the recurring workspace operations: creating the branch and worktree, copying allowed local files, running setup and run scripts, keeping the diff visible, connecting pull request state, and archiving the workspace when the task is done. You can still use normal Git commands inside a workspace. Conductor is adding structure around the worktree so each agent task has a clear place to run, review, merge, or discard. --- title: "Parallel agents" url: "/docs/concepts/parallel-agents" description: "Choose when to split work across workspaces or inside one workspace" --- # Parallel agents Parallel agent work starts with one decision: should these agents share a workspace, or should they move independently? Use multiple workspaces when tasks should land independently. Use multiple agents in one workspace when the work shares the same branch, code state, and context. For agent-specific workflows, see [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions), [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions), and [Run multiple Cursor sessions in parallel](/docs/guides/parallel-agents/run-multiple-cursor-sessions). ## Use multiple workspaces for independent work [#use-multiple-workspaces-for-independent-work] Create a new workspace with Command + N when work should have its own branch, files, running environment, and review path. This is the default choice for: * Independent features. * Bug fixes that can ship separately. * GitHub issues, Linear issues, or pull requests. * Experiments you may discard. * Tasks that need separate app processes or test runs. Each workspace gives the agent a separate branch and working tree. That lets you run, review, merge, or archive each stream of work on its own schedule. ## Use one workspace for shared work [#use-one-workspace-for-shared-work] Run multiple agents in one workspace when the work belongs on the same branch and should share the same files and context. This works well for: * One agent implementing while another reviews the same diff. * One agent fixing tests after another changes the code. * Frontend and backend changes that must land together. * Comparing approaches before choosing one path. * Multi-agent review of one branch before opening a pull request. The tradeoff is that agents in the same workspace can edit the same files. Use this when shared context matters more than separation. ## Decision guide [#decision-guide] | Task shape | Use | Why | | ------------------------------------------------ | ------------------- | ------------------------------------------------------------- | | Two features can ship separately | Multiple workspaces | Each gets its own branch, app state, and PR path. | | One feature needs implementation and test repair | One workspace | The agents need the same branch and latest changes. | | Several issues should be explored in parallel | Multiple workspaces | You can archive, merge, or discard each result independently. | | One branch needs a second opinion | One workspace | Review comments should apply to the same diff. | | A risky experiment may be thrown away | Multiple workspaces | The experiment stays isolated from ongoing work. | ## Common patterns [#common-patterns] For a review, fix, and test split, keep the agents in one workspace. They are collaborating on the same branch, so one agent can review the diff while another applies fixes and a third runs or repairs tests. For issue fanout, use multiple workspaces. Create one workspace per GitHub or Linear issue, give each agent the relevant context, then review and merge the branches that are worth keeping. For exploratory work, start with multiple workspaces if the branches may diverge. If you choose one path, archive the others or copy the useful context into the winning workspace. For the underlying workspace model, see [Isolated workspaces](/docs/concepts/workspaces-and-branches). For hands-on setup, use [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions), [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions), or [Run multiple Cursor sessions in parallel](/docs/guides/parallel-agents/run-multiple-cursor-sessions). --- title: "Testing" url: "/docs/concepts/testing" description: "Automate testing in Conductor" --- # Testing After you make changes in a workspace, test them with either a run script or Spotlight testing. Run scripts test from the workspace directory. Spotlight testing syncs one workspace back to the repository root and tests from there. ## Run scripts [#run-scripts] Use a run script to launch your web server, app, test watcher, or unit tests from the Run button in Conductor's workspace toolbar. Run scripts execute in the workspace directory. They can use `$CONDUCTOR_PORT`, so multiple workspaces can run their own copy of the app without fighting for the same port. For setup details, see [Run script reference](/docs/reference/scripts#run-scripts). ## Spotlight testing [#spotlight-testing] Use Spotlight testing when your project needs to run from the repository root instead of the workspace directory. Enable it in Repository Settings for the project you want to test, then use the Spotlight button from the workspace toolbar. When Spotlight is on, Conductor syncs tracked workspace changes back to the repository root and opens a terminal there. Because Spotlight testing is configured per repository, you can decide which projects use root-based testing and which projects keep isolated workspace run scripts. For when to use Spotlight instead of a run script, see [Spotlight testing](/docs/reference/scripts/spotlight-testing). ## Running microservices at once [#running-microservices-at-once] Conductor only supports automating testing one service at a time. If your application requires microservices to be tested at once, see [Linking multiple directories](/docs/guides/repositories/linking-multiple-directories). --- title: "Workflow" url: "/docs/concepts/workflow" description: "How Conductor turns isolated workspace streams into reviewed pull requests" --- # Workflow Conductor works best when each workspace represents one stream of work. The workspace is the unit of delegation. The branch and pull request are the unit of integration. Use this model after you have created your [first workspace](/docs/first-workspace). Break work into reviewable pieces, give each piece a workspace, then use Conductor's review, checks, pull request, and merge tools to bring finished branches back into the main codebase. ## Break down the problem [#break-down-the-problem] Start by deciding what should be reviewed and merged together. A feature, bug fix, issue, experiment, or pull request usually gets its own workspace. If a problem contains several independent changes, split it into smaller pieces first. Each piece should be clear enough for one agent or group of agents to own, test, review, and merge without waiting on unrelated work. Use one workspace when the work needs one shared branch and code state. Use multiple workspaces when the pieces can move independently. For more detail, see [Parallel agents](/docs/concepts/parallel-agents). ## Create one workspace per shippable unit [#create-one-workspace-per-shippable-unit] Create a workspace for each shippable unit of work. The workspace gets its own branch and working tree, so agents can change code, run commands, and build context without colliding with your main checkout or with other workspaces. Use Command + Shift + N or the `...` button next to `New workspace` to create a workspace from a branch, pull request, GitHub issue, or Linear issue. For first-time setup, see [Your first workspace](/docs/first-workspace). For the underlying workspace model, see [Isolated workspaces](/docs/concepts/workspaces-and-branches). ## Run agents independently [#run-agents-independently] Use Claude Code, Codex, Cursor, or OpenCode directly in Conductor, or open the workspace in your IDE. Each workspace has its own files, branch, app processes, and agent context, so agents can work on separate streams at the same time. For durable project guidance, use Repository Settings or checked-in instruction files. For task-specific context, use the chat, attachments, and `.context`. When you start another independent feature, bug fix, or issue, create another workspace instead of waiting for the first agent to finish. Each workspace can run its own app process and reach review on its own schedule. ## Verify, review, and resolve conflicts [#verify-review-and-resolve-conflicts] Use the terminal, Run button, or Spotlight testing to verify the workspace before it becomes a pull request. Open the Diff Viewer with Command + Shift + D. Review changed files, leave comments, and ask an agent to address anything missing. Start with a quick sanity check in the running app when possible, then review the code. Use the `Review` action for an agent review, and use the Diff Viewer for your manual review. Inline comments become composer attachments that you can send back to the agent that made the change. Use the [Checks tab](/docs/reference/checks) to inspect git status, CI, deployments, comments, and todos before you merge. If the branch has conflicts, ask an agent to help resolve them, then rerun tests and review the diff again before continuing. For a step-by-step final pass, see [Review and merge a workspace](/docs/guides/review-and-merge). ## Open the PR, merge, and archive [#open-the-pr-merge-and-archive] Create a pull request with Command + Shift + P. Conductor can help draft the PR description, respond to review comments, fix failing checks, and prepare the branch for merge. After the PR opens, Conductor follows the GitHub Actions and status checks for the branch. Merge when the PR is approved, checks are green, comments are resolved, and todos are complete. Archive finished workspaces so your sidebar stays focused. To restore an archived workspace later, open the History pane in the sidebar and restore it from there, including its chat history. To apply this flow to a GitHub or Linear issue, see [From issue to PR](/docs/guides/issue-to-pr). --- title: "Isolated workspaces" url: "/docs/concepts/workspaces-and-branches" description: "Understand projects, repositories, workspaces, branches, working trees, and running environments" --- # Isolated workspaces An isolated workspace is a separate, git-backed copy of a project for one stream of work. Conductor uses workspaces so agents can change code, run commands, and build context without colliding with your main checkout or with agents working in other workspaces. ## The core model [#the-core-model] These terms build on each other from the Conductor project down to the files and processes inside one workspace: | Term | What it means in Conductor | Relationship | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | Project | The Conductor entry for a codebase. It holds Repository Settings, scripts, instructions, and the list of workspaces for that codebase. | 1 project contains 1 repository | | Repository | The Git codebase behind a project. It can come from an existing local folder, GitHub project, or Quick start. | 1 repository contains many workspaces | | Workspace | An isolated copy of a project and repository for one task, issue, experiment, or pull request. | 1 workspace maps to 1 branch | | Branch | The Git branch checked out inside a workspace. This is usually the review and PR unit. | 1 branch has 1 working tree | | Working tree | The files on disk for one workspace. Conductor creates these separate checkouts with [Git worktrees](/docs/concepts/git-worktrees). | 1 working tree belongs to 1 workspace | | Running environment | The app, server, watchers, tests, and terminal commands running inside a workspace. | 1 workspace can run many processes | The easiest way to identify a workspace is often by its branch. For instance, this workspace is on the `scroll-to-bottom-btn` branch: The secondary name, such as `warsaw-v2`, is the workspace directory name. ## What isolation gives you [#what-isolation-gives-you] Each workspace gives an agent a separate place to work: * Code changes stay on that workspace's branch. * File edits happen in that workspace's working tree. * Setup and run scripts execute from that workspace directory. * App processes can use workspace-specific environment variables such as `CONDUCTOR_PORT`. * Notes and handoffs can live in the workspace's `.context` folder without being committed. This is why Conductor works well for parallel agent work. You can put independent tasks in independent workspaces, run each one, review each branch, and merge work when it is ready. Workspace isolation is development isolation, not a security boundary. Agents and commands still run on your Mac with your user permissions. ## Branches and review [#branches-and-review] Conductor wraps common GitHub and branch tasks in the app UI, but the branch is still the core unit that explains what a workspace is and how it fits into review and PR flow. When you create a new workspace, Conductor will create a new branch for it. When you start your first chat, Conductor will instruct the agent to rename this branch to match what you're working on. Conductor bases the new branch on the repository's configured base branch (for example `origin/main`), and it fetches from `origin` first. So a new workspace always starts from the latest remote commit, even if your local checkout is behind. To keep the branch in your root checkout current as well, see [Setup script reference](/docs/reference/scripts#setup-scripts). ## Switching branches [#switching-branches] If what you're working on changes, you can check out a different branch: ```sh git checkout some-other-feature ``` ...or rename the current branch: ```sh git branch -m new-name ``` ...or create a new branch: ```sh git checkout -b new-branch ``` ## Starting from an existing branch [#starting-from-an-existing-branch] If you have an existing branch and you want to start a new workspace from it, you can follow these steps: 1. Use Command + Shift + N or click the `...` icon next to the "New workspace" button 2. Choose the "Branches" tab and select a branch You could also create a new workspace and then switch to the branch you want using the instructions in the "Switching branches" section above. ## One workspace per branch [#one-workspace-per-branch] A branch can only be checked out in one workspace at a time. If you want to check out the `scroll-to-bottom-btn` branch in `tokyo`, but you already have that branch checked out in `warsaw`, try one of these: * In `tokyo`, run `git checkout -b scroll-to-bottom-btn-2 scroll-to-bottom-btn` to create a new branch based off of `scroll-to-bottom-btn` * In `warsaw`, switch to any other branch (e.g., `git checkout -b dummy`), then in `tokyo` run `git checkout scroll-to-bottom-btn` ## Where to go next [#where-to-go-next] Create your [first workspace](/docs/first-workspace), then use [Parallel agents](/docs/concepts/parallel-agents) to decide whether work belongs in one workspace or across several workspaces. If you want the broader Git model behind these workflows, see [Git Worktrees](/docs/concepts/git-worktrees). --- title: "Set up MCP servers" url: "/docs/guides/configure-mcp-servers" description: "Add MCP servers for Claude Code, Codex, and Cursor Composer workflows so agents can use shared tools and context" --- # Set up MCP servers Use MCP servers when every Conductor workspace should give agents the same external tool access: docs search, issue tracking, databases, dashboards, or internal APIs. This guide sets up a `stdio` MCP server for Claude Code, Codex, and Cursor Composer workflows. For exact config fields, transports, scopes, and security notes, see the [MCP reference](/docs/reference/mcp). ## Before you start [#before-you-start] You need: * A repository already added to Conductor. * A local Conductor workspace. * Claude Code, Codex, or Cursor Composer selected for the workflow you want to use. * Any required credentials for the MCP server. MCP servers are loaded by the agent host. If you change Claude Code or Codex MCP configuration after a Conductor session has started, refresh MCP status and start a new session when you need the new tools in the model context. Cursor Composer MCP servers are configured in Cursor. Use that path when you open a Conductor workspace in Cursor and want Cursor Composer to use project-level or user-level MCP servers. ## Add an MCP server [#add-an-mcp-server] ### Choose the scope [#choose-the-scope] Use user scope for personal tools you want everywhere. Use project scope for tools that should follow one repository. | Scope | Use it for | Claude Code path or command | Codex path or command | Cursor Composer path | | ------- | ------------------------------------------------- | ---------------------------------- | ------------------------------------- | ------------------------------------------- | | User | Personal docs search, personal issue tracker auth | `claude mcp add -s user ...` | `codex mcp add ...` | `~/.cursor/mcp.json` or Cursor MCP settings | | Project | Repository-local MCP config shared with teammates | `.mcp.json` in the repository root | `.codex/config.toml` for that project | `.cursor/mcp.json` in the repository root | If the server needs secrets, keep credentials out of committed files. Use environment variables or personal config for tokens. ### Add the server for Claude Code [#add-the-server-for-claude-code] Run the Claude Code MCP command from a terminal: ```bash claude mcp add context7 -s user -- npx -y @upstash/context7-mcp ``` The `--` separates Claude Code options from the command that starts the MCP server. For project-level Claude Code config, add `.mcp.json` at the repository root: ```json title=".mcp.json" { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` ### Add the server for Codex [#add-the-server-for-codex] Run the Codex MCP command from a terminal: ```bash codex mcp add context7 -- npx -y @upstash/context7-mcp ``` Codex writes the server to `~/.codex/config.toml`. You can also edit that file directly: ```toml title="~/.codex/config.toml" [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] ``` For Streamable HTTP servers, use the server URL instead of a local command: ```bash codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp ``` ### Add the server for Cursor Composer [#add-the-server-for-cursor-composer] Open the Conductor workspace in Cursor with `Open In` or Command + O. For project-level Cursor Composer config, add `.cursor/mcp.json` at the repository root: ```json title=".cursor/mcp.json" { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` Cursor also supports user-level MCP configuration in `~/.cursor/mcp.json` and through Cursor's MCP settings UI. Use user-level config for personal tools; use project-level config when everyone opening the repository in Cursor should get the same MCP server definition. ### Check status in Conductor [#check-status-in-conductor] Open the Conductor workspace and select the session that should use the MCP server. If the MCP status indicator is enabled, click the plug icon in the composer and use the refresh button. You can also run `/mcp-status` in the composer to open the status dialog. Conductor shows the Claude Code or Codex servers it can discover for the selected agent. If a server needs OAuth, use the authentication action from the status row. For Cursor Composer, check server status in Cursor's MCP UI. Conductor-hosted Cursor sessions do not currently surface Cursor MCP server status in Conductor's MCP status UI. ### Ask the agent to use the tool [#ask-the-agent-to-use-the-tool] Start a new message that names the server's purpose. For example: ```txt Use Context7 to look up the latest React Query docs, then update this hook. ``` When the agent calls an MCP tool, Conductor renders the tool call in the session transcript. Approval prompts may appear depending on your agent settings and the server's tools. ## Share MCP setup with a team [#share-mcp-setup-with-a-team] For shared repository behavior, prefer committed project config and personal credentials: * Commit `.mcp.json` only when the listed servers are safe and useful for everyone using Claude Code in the repository. * Commit `.cursor/mcp.json` only when the listed servers are safe and useful for everyone opening the repository in Cursor. * Keep tokens in environment variables, user config, or secret managers. * Document required tokens in your project README or setup docs. * Use [Conductor environment variables](/docs/reference/environment-variables) when a local workspace needs provider or tool credentials available to agent processes. If your team is migrating from Cursor MCP config to Claude Code in Conductor, copy project MCP servers from `.cursor/mcp.json` to `.mcp.json`. See [Migrate MCP servers from Cursor](/docs/guides/migrate-from-cursor#migrate-mcp-servers). ## Troubleshooting [#troubleshooting] Refresh MCP status in the composer or `MCP status` dialog. If you changed config while a session was already running, start a new session so the agent can load the new server list. For Codex, confirm the server appears in the CLI: ```bash codex mcp list ``` For Claude Code, confirm the server appears in the CLI: ```bash claude mcp list ``` For Cursor Composer, open Cursor's MCP UI and refresh the server list. Confirm that the workspace is opened at the Conductor workspace checkout that contains `.cursor/mcp.json`. Check whether the server command depends on files outside the workspace or environment variables that are not available to Conductor. Local MCP servers run as commands, so `PATH`, package manager availability, and token environment variables all matter. If the server needs repository-local files, prefer a project-level config and a command that works from the workspace checkout. ## Next steps [#next-steps] * Use [MCP](/docs/reference/mcp) for transports, scopes, config examples, and security notes. * Use [Cursor](/docs/reference/harnesses/cursor) for Conductor's Cursor Composer session behavior. * Use [Security and permissions](/docs/reference/security-and-permissions) to understand how agent tools and approvals work. * Use [Work with Cursor and VS Code](/docs/guides/migrate-from-cursor) if you are moving MCP servers from Cursor. --- title: "Configure settings" url: "/docs/guides/configure-settings" description: "Set personal defaults, project settings, and local project overrides in Conductor" --- # Configure settings Use this guide when you want to configure the settings most people edit directly: your global defaults, a project's shared settings, and your local overrides for one project. Conductor has a layered settings model: user settings apply to all projects, project settings apply to one repository, and local project settings override on a single machine. Organization-managed settings take precedence, if configured. ## Before you start [#before-you-start] You need: * A repository already added to Conductor. * A terminal open at the repository root if you are configuring project settings. * The commands your project uses to install dependencies and start the app. Use the in-app *Settings* page when you want Conductor to write settings for you. Open it from the File menu or the Settings button in the side nav. Find project-level settings in Settings > Repo, then select your project from the dropdown. You can also configure project settings as code in `.conductor/settings.local.toml`. ## Choose the settings layer [#choose-the-settings-layer] Pick the file that matches who should receive the setting: | Scope | Git | File | | -------------------------------- | -------------------- | --------------------------------------- | | You, across all repositories | Do not commit | `~/.conductor/settings.toml` | | Only you, in one repository | Add to `.gitignore` | `/.conductor/settings.local.toml` | | Everyone after merge into `main` | Commit and open a PR | `/.conductor/settings.toml` | Repository local settings win over repository shared settings. Repository shared settings win over user settings. The easiest way to edit run scripts is in Conductor app settings. The UI updates settings files without needing to edit configuration manually. Use `/.conductor/settings.local.toml` when a run script should apply only on your Mac. Changes there are reflected in this repository's workspaces on your machine. Use `/.conductor/settings.toml` only when a run script should become a shared team default. Conductor reflects those changes after the settings change is merged to the repository's default branch, usually `main`. If your organization manages Conductor settings, those values sit above the normal user and project stack. See [Managed settings](/docs/reference/settings/managed) for that separate flow. ## Configure your user defaults [#configure-your-user-defaults] Use user settings for personal defaults that should follow you across projects, such as model choices and reasoning defaults. ### Create the user settings file [#create-the-user-settings-file] Create the settings directory if it does not exist: ```bash mkdir -p ~/.conductor ``` Then create or edit `~/.conductor/settings.toml`: ```toml title="~/.conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.schema.json" [models] default = "gpt-5.5" review = "sonnet" default_plan_mode = true [models.codex] default_thinking_level = "high" personality = "direct" [models.claude_code] default_effort_level = "normal" ``` ### Adjust the values [#adjust-the-values] Keep only the defaults you actually want everywhere. For example, if you only want Codex sessions to start with higher reasoning, keep this smaller file: ```toml title="~/.conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.schema.json" [models.codex] default_thinking_level = "high" ``` ## Configure shared project settings [#configure-shared-project-settings] Use shared project settings for repository behavior that should travel with the project, such as setup scripts, run scripts, Files to copy patterns, prompts, environment variables, and Git behavior. ### Create the project settings file [#create-the-project-settings-file] From the repository root, create the settings directory if it does not exist: ```bash mkdir -p .conductor ``` Then create or edit `.conductor/settings.toml`: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Use your project's real setup and run commands. Use `CONDUCTOR_PORT` when the development server can accept a custom port, so multiple workspaces can run at the same time. This shared file affects the Run menu only after the change is merged to the repository's default branch. Use `Settings` for immediate configuration, or `.conductor/settings.local.toml` for a local-only override. ### Choose the run mode [#choose-the-run-mode] Keep `run_mode = "concurrent"` when each workspace can run independently. Use `run_mode = "nonconcurrent"` when the project depends on one fixed port, one local database, one Docker stack, or another shared resource: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run_mode = "nonconcurrent" [scripts.run.dev] command = "pnpm dev" default = true icon = "play" ``` ### Add project-specific details [#add-project-specific-details] Add sections only when the project needs them. For example, this project also copies gitignored environment files, sets an agent prompt, and customizes branch names: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" file_include_globs = ".env*\nconfig/*.local.json\n" [scripts] setup = "pnpm install" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" [prompts] general = "Prefer small, reviewable changes and run the narrowest relevant tests." [git] branch_prefix_type = "custom" branch_prefix = "agent" ``` ### Commit the shared settings [#commit-the-shared-settings] Commit `.conductor/settings.toml` when the settings should apply to the project: ```bash git add .conductor/settings.toml git commit -m "Add Conductor project settings" ``` ## Configure a local project override [#configure-a-local-project-override] Use `.conductor/settings.local.toml` for machine-specific overrides, such as a local run script or provider URL. ### Ignore the local override file [#ignore-the-local-override-file] From the repository root, add the local settings file to `.gitignore`: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` ### Add your local overrides [#add-your-local-overrides] For example, override the Run button command and a local provider URL on your machine: ```toml title=".conductor/settings.local.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --host 127.0.0.1 --port $CONDUCTOR_PORT" default = true icon = "play" [environment_variables] ANTHROPIC_BASE_URL = "http://127.0.0.1:4000" ``` This file overrides matching values from `.conductor/settings.toml` only for your local checkout. ## Verify the settings [#verify-the-settings] Create a new workspace from the repository. Conductor should run the setup script from `.conductor/settings.toml` and use the shared Run button command unless your local override replaces it. For a quick check, click `Run` in the workspace and confirm the command starts with the expected port behavior. If you configured `CONDUCTOR_PORT`, create a second workspace and confirm both workspaces can run at the same time. ## See also [#see-also] * [Settings](/docs/reference/settings) * [User and project settings](/docs/reference/settings/user-project) * [Sample settings configurations](/docs/reference/settings/example) * [Scripts](/docs/reference/scripts) * [Files to copy](/docs/reference/files-to-copy) --- title: "From issue to PR" url: "/docs/guides/issue-to-pr" description: "Take a GitHub or Linear issue through implementation, review, and pull request" --- # From issue to PR Use this guide when a GitHub or Linear issue should become a pull request. This is the issue-specific version of the [Conductor workflow](/docs/concepts/workflow): start from issue context, let agents implement and verify the change in an isolated workspace, then use the branch and pull request to integrate the result. ## Decide the shape of the work [#decide-the-shape-of-the-work] Before you create the workspace, decide whether the issue should become one pull request or several. Use one workspace when the issue has one reviewable outcome, one branch, and one pull request. Split the issue into multiple workspaces when it contains independent features, risky experiments, or changes that should be reviewed and merged separately. For more detail on choosing between shared and separate workspaces, see [Parallel agents](/docs/concepts/parallel-agents). ## Start from an issue [#start-from-an-issue] Create a workspace from the issue when you want the agent to inherit the issue title, description, and context. 1. Click the `...` button next to `New workspace`, or press Command + Shift + N. 2. Choose a GitHub issue or Linear issue. 3. Confirm the repository and workspace. 4. Wait for Conductor to create the workspace and branch. If the issue does not appear, check GitHub or Linear authentication. ## Ask for a plan [#ask-for-a-plan] Use Plan Mode when the issue is broad or ambiguous. Ask the agent to summarize the issue, inspect the relevant code, and propose an implementation plan before editing files. Approve the plan when it matches the intended scope for this workspace. Give feedback if the plan misses requirements, tests, rollout constraints, or work that belongs in a separate workspace. ## Implement and test [#implement-and-test] Let the agent make the change inside the isolated workspace, then test from that workspace: 1. Run the project with a [run script](/docs/reference/scripts#run-scripts), terminal command, or [Spotlight testing](/docs/reference/scripts/spotlight-testing). 2. Ask the agent to fix errors with logs or failing output attached. 3. Keep todos updated for work that must be complete before merge. ## Review the diff [#review-the-diff] Open the Diff Viewer with Command + Shift + D. Review: * Whether the change solves the issue. * Whether unrelated files changed. * Whether tests or docs need updates. * Whether comments or todos are still open. Send review comments to the agent when you want it to revise the diff. Use the [Checks tab](/docs/reference/checks) to watch git status, CI, deployments, comments, and todos. If there are conflicts, ask the agent to help resolve them, then rerun tests and review the diff again before creating or merging the pull request. ## Create the pull request [#create-the-pull-request] When the workspace is ready, click `Create PR` or use Command + Shift + P. Conductor sends the current diff and repository context to the agent so it can draft the pull request. After the PR exists, keep using the Checks tab and Diff Viewer to respond to CI, deployments, review comments, and todos. ## Merge and archive [#merge-and-archive] Merge when checks pass, review comments are resolved, and todos are complete. Archive the workspace after merge so it leaves your active work list. For more detail on the final review pass, see [Review and merge a workspace](/docs/guides/review-and-merge). --- title: "Work with Cursor" url: "/docs/guides/migrate-from-cursor" description: "Run Cursor sessions in Conductor, open workspaces in Cursor or VS Code, and bring Cursor MCP servers and rules into Conductor" --- # Work with Cursor Use this guide when you want to run Cursor as a Conductor session, open Conductor workspaces in Cursor, keep Cursor windows easy to identify, or migrate Cursor MCP servers and rules into Conductor. ## Run Cursor in Conductor [#run-cursor-in-conductor] Cursor sessions run inside Conductor workspaces, so the chat, branch, terminal, diff, checks, pull request, and archive state stay tied to the workspace. Conductor supports Cursor's Composer 2.5 for Cursor sessions. Before starting a Cursor chat, add your Cursor API key in `Settings` -> `Harnesses` -> `Cursor`. You can also set `CURSOR_API_KEY` in Conductor's environment settings. For parallel work, use one workspace per independent Cursor task. See [Run multiple Cursor sessions in parallel](/docs/guides/parallel-agents/run-multiple-cursor-sessions). ## Open workspaces in Cursor or VS Code [#open-workspaces-in-cursor-or-vs-code] From a workspace, click `Open In` or press Command + O to open the workspace directory in Cursor or VS Code. If the workspace is already open, Conductor focuses the existing editor window. ## Name Cursor windows by branch [#name-cursor-windows-by-branch] When several workspaces are open in Cursor, use the window title to show the branch and workspace name. 1. In Cursor, open User Settings with Command + Shift + P, then choose `Preferences: Open User Settings`. 2. Search for `window.title`. 3. Set it to: ```text ${activeRepositoryBranchName}${separator}${rootName}${separator}${profileName} ``` Cursor will show the branch name in the title bar, like: ```text my-feature — tokyo ``` ## Migrate MCP servers [#migrate-mcp-servers] Cursor stores MCP config in `~/.cursor/mcp.json` (global) and `.cursor/mcp.json` (project-level). Keep that config when you open Conductor workspaces in Cursor and want Cursor Composer MCP tools. For Claude Code and Codex sessions in Conductor, use Claude Code and Codex MCP config for those agents. ### Global MCP servers [#global-mcp-servers] Copy your servers from `~/.cursor/mcp.json` into `~/.claude.json`: Cursor (~/.cursor/mcp.json) Conductor (~/.claude.json) ```json { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` ```json { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` The format is the same. Copy the `mcpServers` object into `~/.claude.json`. ### Project-level MCP servers [#project-level-mcp-servers] Copy from `.cursor/mcp.json` to `.mcp.json` in your project root: Cursor (.cursor/mcp.json) Conductor (.mcp.json) ```json { "mcpServers": { "my-project-server": { "command": "node", "args": ["./tools/mcp-server.js"] } } } ``` ```json { "mcpServers": { "my-project-server": { "command": "node", "args": ["./tools/mcp-server.js"] } } } ``` You can also add MCP servers for Claude Code, Codex, and Cursor Composer directly. See [Set up MCP servers](/docs/guides/configure-mcp-servers) for the step-by-step flow and [MCP](/docs/reference/mcp) for scopes, transports, and syntax. ## Migrate rules and instructions [#migrate-rules-and-instructions] Cursor uses `.cursorrules` or `.cursor/rules/*.mdc` files for custom instructions. In Conductor, use shared repository instructions such as `AGENTS.md`, `CLAUDE.md`, or project prompts in Repository Settings. ### .cursorrules [#cursorrules] Copy the contents of your `.cursorrules` file into `AGENTS.md` or `CLAUDE.md` at the root of your project: ```bash cp .cursorrules AGENTS.md ``` ### .cursor/rules/\*.mdc [#cursorrulesmdc] `.mdc` files have YAML frontmatter that you'll want to strip. Copy just the markdown body into `AGENTS.md` or `CLAUDE.md`: ```bash for f in .cursor/rules/*.mdc; do echo "" >> AGENTS.md # Strip frontmatter (content between --- markers) sed '1{/^---$/!q;};1,/^---$/d' "$f" >> AGENTS.md done ``` ### Global instructions [#global-instructions] Cursor's global AI rules can move into user-level agent instructions. For Claude Code, that file is `~/.claude/CLAUDE.md`: ```bash # Create global instructions mkdir -p ~/.claude echo "Your global instructions here" > ~/.claude/CLAUDE.md ``` ## Use the migration script [#use-the-migration-script] We've published a script that automates all of the above. It handles global and project-level MCP servers, `.cursorrules`, and `.mdc` rule files. ```bash curl -fsSL https://gist.githubusercontent.com/cbh123/4187d4c6774a557b26ed6bcf054f42e2/raw/migrate-cursor-to-conductor.sh | bash ``` Or to preview what it would do without making changes: ```bash curl -fsSL https://gist.githubusercontent.com/cbh123/4187d4c6774a557b26ed6bcf054f42e2/raw/migrate-cursor-to-conductor.sh -o migrate.sh chmod +x migrate.sh ./migrate.sh --dry-run ``` The script won't overwrite existing MCP servers or CLAUDE.md content — it only appends. ## Quick reference [#quick-reference] | Cursor | Conductor / Claude Code | Codex | | --------------------- | -------------------------- | ---------------------- | | `~/.cursor/mcp.json` | `~/.claude.json` | `~/.codex/config.toml` | | `.cursor/mcp.json` | `.mcp.json` | `.codex/config.toml` | | `.cursorrules` | `AGENTS.md` or `CLAUDE.md` | `AGENTS.md` | | `.cursor/rules/*.mdc` | `AGENTS.md` or `CLAUDE.md` | `AGENTS.md` | | Global AI rules | `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` | --- title: "Configure model providers" url: "/docs/guides/providers" description: "Set up Claude Code, Codex, OpenCode, and Cursor credentials in Conductor" --- # Configure model providers Conductor runs each chat through one harness. Configure harness auth in `Settings` -> `Harnesses`. Use `Settings` -> `Environment` when a provider needs environment variables. Conductor does not bill or resell model usage. Usage is billed by the provider account, subscription, usage pool, or API key used by the selected harness. | Harness | Configure in | Credential | Notes | | ----------- | ------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------- | | Claude Code | `Settings` -> `Harnesses` -> `Claude Code` | Claude subscription, CLI auth, or `ANTHROPIC_API_KEY` | Environment variables can route Claude Code to compatible providers. | | Codex | `Settings` -> `Harnesses` -> `Codex` | Codex sign-in, subscription, or `CODEX_API_KEY` | Vercel AI Gateway uses `AI_GATEWAY_API_KEY`. | | OpenCode | `Settings` -> `Harnesses` -> `OpenCode` | OpenCode provider API keys | Visible models are managed in OpenCode settings. | | Cursor | `Settings` -> `Harnesses` -> `Cursor` | `CURSOR_API_KEY` | Cursor runs through the Cursor API. | ## Claude Code [#claude-code] Claude Code can use your Claude subscription, Claude CLI login, an Anthropic API key, or Claude-compatible provider environment variables. 1. Open `Settings` -> `Harnesses` -> `Claude Code`. 2. Choose CLI auth for an existing Claude Code login, or choose API key mode. 3. For API key mode, add your Anthropic key as `ANTHROPIC_API_KEY`. 4. Check the Claude Code auth status in the same settings panel. If `ANTHROPIC_API_KEY` is set in Conductor or in the shell environment that launches Conductor, Claude Code may use API billing instead of subscription usage. ## Codex [#codex] Codex can use Codex sign-in, an OpenAI subscription, or an API key. 1. Open `Settings` -> `Harnesses` -> `Codex`. 2. Choose CLI auth for an existing `codex login`, or choose API key mode. 3. For API key mode, add your OpenAI key as `CODEX_API_KEY`. 4. Start a Codex session and choose a model that is available to your account. For Vercel AI Gateway, add these values in `Settings` -> `Environment`: ```bash OPENAI_BASE_URL=https://ai-gateway.vercel.sh/v1 AI_GATEWAY_API_KEY=your-vercel-ai-gateway-api-key ``` ## OpenCode [#opencode] OpenCode uses provider credentials and the models returned by your OpenCode setup. 1. Open `Settings` -> `Harnesses` -> `OpenCode`. 2. Select `Providers`. 3. Add provider API keys. 4. Choose which OpenCode models should be visible in Conductor. Common OpenCode provider keys: ```bash OPENROUTER_API_KEY=your-openrouter-api-key BASETEN_API_KEY=your-baseten-api-key CEREBRAS_API_KEY=your-cerebras-api-key AI_GATEWAY_API_KEY=your-vercel-ai-gateway-api-key ``` OpenCode can also use provider credentials from local environment variables and its own provider configuration. ## Cursor [#cursor] Cursor sessions use Cursor Agent through the Cursor API. Conductor does not use a local Cursor executable for Cursor sessions. 1. Open `Settings` -> `Harnesses` -> `Cursor`. 2. Add your Cursor API key. 3. Or set `CURSOR_API_KEY` in Conductor environment settings. 4. Start a Cursor session. ```bash CURSOR_API_KEY=your-cursor-api-key ``` ## Advanced Claude Code providers [#advanced-claude-code-providers] Claude Code can use Anthropic-compatible providers through environment variables. Add these values in `Settings` -> `Environment`. When using a compatible provider, make sure `ANTHROPIC_API_KEY` is not set to an Anthropic key in Conductor or in the shell environment that launches Conductor. Otherwise Claude Code may authenticate with Anthropic directly. ### OpenRouter [#openrouter] ```bash ANTHROPIC_BASE_URL=https://openrouter.ai/api ANTHROPIC_AUTH_TOKEN=your-openrouter-api-key ``` Docs: [OpenRouter Claude Code integration](https://openrouter.ai/docs/guides/guides/claude-code-integration) ### Vercel AI Gateway [#vercel-ai-gateway] ```bash ANTHROPIC_BASE_URL=https://ai-gateway.vercel.sh ANTHROPIC_AUTH_TOKEN=your-vercel-ai-gateway-api-key ``` Docs: [Vercel AI Gateway Anthropic-compatible API](https://vercel.com/docs/ai-gateway/sdks-and-apis/anthropic-compat) ### Bedrock [#bedrock] ```bash CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-east-1 ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2 ANTHROPIC_DEFAULT_OPUS_MODEL=us.anthropic.claude-opus-4-7 ANTHROPIC_DEFAULT_SONNET_MODEL=us.anthropic.claude-sonnet-4-6 ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0 ``` Docs: [AWS Bedrock Claude Code](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-code.html) ### GLM [#glm] ```bash ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic ANTHROPIC_AUTH_TOKEN=your-zai-api-key ``` Docs: [GLM Claude integration](https://docs.z.ai/scenario-example/develop-tools/claude) For a full provider list, see the [Claude Code third-party integrations docs](https://code.claude.com/docs/en/third-party-integrations). --- title: "Review and merge a workspace" url: "/docs/guides/review-and-merge" description: "Use Conductor's review, checks, and PR tools before merging" --- # Review and merge a workspace Use this guide after an agent or teammate has changed code in a workspace. ## Review the diff [#review-the-diff] Open the Diff Viewer with Command + Shift + D. Review the changed files before you ask Conductor to create or merge a pull request. In the Diff Viewer, you can: * Inspect file changes. * Leave comments on changed lines. * Send comments back to the agent. * Resolve GitHub review threads when they no longer apply. * Revert files when you do not want to keep a change. ## Ask for review [#ask-for-review] Use the `Review` action when you want an agent to inspect the current diff. Add repository-specific review guidance in Repository Settings under `Code review preferences`. Good review prompts are specific. Tell the agent what to prioritize, such as correctness, migration safety, UI regressions, tests, or security-sensitive behavior. ## Check merge readiness [#check-merge-readiness] Open the Checks tab before you merge. It gathers the state that usually determines whether a workspace is ready: * Git status * Pull request metadata * CI and status checks * Deployments * GitHub and review comments * Todos Treat unresolved comments, failing checks, and open todos as blockers until you intentionally clear them. ## Create or update the PR [#create-or-update-the-pr] Use `Create PR` when the workspace is ready for review. Conductor sends the current diff and repository context to the agent so it can draft a pull request description. If you already have a PR, use the Checks tab and Diff Viewer to keep responding to review comments and status changes. ## Merge and archive [#merge-and-archive] Merge when the PR is approved, checks are green, comments are handled, and todos are complete. After merge, archive the workspace so it leaves your active work list. If you need to revisit the work later, restore the workspace from the History pane in the sidebar. --- title: "Use Files to copy" url: "/docs/guides/use-files-to-copy" description: "Copy .env files and other gitignored local config into local Conductor workspaces" --- # Use Files to copy Use Files to copy when every new local Conductor workspace needs the same gitignored local files before the app can run. The common case is `.env.local`: it should not be committed, but local workspaces still need it. A shared `.worktreeinclude` file lets Conductor copy it automatically. ## Before you start [#before-you-start] You need: * A repository already added to Conductor. * A local Mac workspace. Files to copy does not currently run for cloud workspaces. * A local file that exists in your main checkout, such as `.env.local`. * A `.gitignore` rule that ignores that file. Git worktrees start with tracked files only. They do not copy untracked files, gitignored files, local credentials, local config, generated files, dependency folders, or caches from your main checkout. Conductor's default Files to copy pattern is `.env*`, so gitignored files like `.env.local` are copied by default. Files outside that pattern are not copied unless you add matching Files to copy or `.worktreeinclude` patterns. Files to copy only copies files that Git already ignores. If the file is tracked, it will already be present in new worktrees. ## Set up Files to copy [#set-up-files-to-copy] ### Choose the files [#choose-the-files] Start with the files your app needs to boot in a new local workspace: ```txt .env.local config/local.json certs/local.pem ``` Do not include dependency folders or generated build outputs unless you have a strong reason. A [setup script](/docs/reference/scripts#setup-scripts) is usually better for generated workspace state. ### Create .worktreeinclude [#create-worktreeinclude] Create `.worktreeinclude` at the repo root: ```txt title=".worktreeinclude" .env.local config/local.json certs/local.pem ``` You can also use `.gitignore` syntax: ```txt title=".worktreeinclude" .env* config/**/local.json certs/** !certs/**/*.example ``` For the full syntax, including nested globs and negation, see the [Files to copy reference](/docs/reference/files-to-copy). ### Commit the patterns [#commit-the-patterns] Commit `.worktreeinclude` so the project shares the same copy rules: ```sh git add .worktreeinclude git commit -m "Add worktree include patterns" ``` Do not commit the files matched by `.worktreeinclude`. They should stay gitignored. ### Create a new workspace [#create-a-new-workspace] Create a new Conductor workspace with Command + N. When Conductor creates the local workspace, it checks the repo root for `.worktreeinclude`, lists gitignored files, and copies matching files into the new workspace. ### Verify the workspace [#verify-the-workspace] Open the terminal in the new local workspace and check for one expected file: ```sh test -f .env.local && echo "Copied" ``` If the file is missing, check these first: * `.worktreeinclude` is at the repo root. * The pattern matches the path from the repo root. * The target file exists in the main checkout. * The target file is ignored by Git. Run this from the main checkout: ```sh git check-ignore -v .env.local ``` If Git prints a matching ignore rule, the file is eligible for Files to copy. If Git prints nothing, add or fix the `.gitignore` rule first. Patterns are evaluated from the repository root. A leading `/` anchors a pattern to the root, and nested globs such as `config/**/local.json` can match deeper paths. For example, `/config/local.json` matches only `config/local.json` at the repo root. It does not match `packages/api/config/local.json`. The default pattern is `.env*`, but `.worktreeinclude` and repo settings replace that default. If you add custom patterns and still want environment files copied, include `.env*` in your `.worktreeinclude` file. ## Personal patterns [#personal-patterns] If you do not want to commit shared patterns, use Repository Settings instead: 1. Open Settings. 2. Select the repository. 3. Add one pattern per line in Files to copy. When `.worktreeinclude` exists at the repo root, it takes precedence and the settings UI becomes read-only for that repository. For the underlying model and tradeoffs, see [Manage secrets with .worktreeinclude](/docs/reference/worktreeinclude). --- title: "Agent behavior" url: "/docs/reference/agent-behavior" description: "Reference for agent instructions, modes, permissions, and checkpoints" --- # Agent behavior This page summarizes the controls that affect how agents behave in Conductor. ## Session controls [#session-controls] | Control | Scope | Use it for | | --------------------------- | ----------------- | --------------------------------------------------- | | Plan Mode | Current session | Ask the agent to plan before editing | | Fast Mode | Current session | Trade extra credits for faster work where supported | | Thinking or reasoning level | Current session | Adjust how much reasoning the model spends | | Codex personality | Codex session | Choose a Codex working style | | Checkpoints | Session/workspace | Revert code and chat state to an earlier turn | For conceptual guidance, see [Agent modes](/docs/concepts/agent-modes). ## Repository instructions [#repository-instructions] Use repository instructions for guidance that should apply repeatedly: * `General preferences` apply broad instructions to agents in a repository. * `Code review preferences` are sent when you click `Review`. * `Create PR preferences` are sent when you create a pull request. * `Fix errors preferences` are sent when Conductor asks an agent to fix errors. * `Resolve conflicts preferences` are sent when an agent helps with merge conflicts. * `Branch rename preferences` guide automatic branch naming. These preferences live in Repository Settings. ## Instruction files and skills [#instruction-files-and-skills] Agents can also use instructions stored in your repository or user configuration, such as: * `AGENTS.md` * `CLAUDE.md` * `.claude/commands` * Skills Keep durable project conventions in these files. Keep task-specific details in the chat or `.context`. ## Permissions [#permissions] Agents run locally and can use the same local permissions as your user account unless you configure stricter controls. Some actions may ask for approval before the agent continues. For security details, see [Security and permissions](/docs/reference/security-and-permissions). --- title: "Big Terminal Mode" url: "/docs/reference/big-terminal-mode" description: "Use a full terminal in the center panel" --- # Big Terminal Mode Big Terminal Mode replaces the center panel with a full terminal. Use it when you want a terminal-first workflow inside Conductor instead of launching only saved run scripts. Open Big Terminal Mode with Command + Shift + T. Enable Big Terminal Mode in `Settings` -> `Experimental`. ## Behavior [#behavior] * Terminal sessions restore after restart. * New terminals can use presets to start common commands or tools. * Big Terminal Mode can run any agent or command available in your terminal environment. ## Agent presets [#agent-presets] Big Terminal Mode is useful when you want to run an agent directly from a terminal. New terminal tabs can start from a preset so the agent command runs automatically. When tool approvals are off, Claude and Codex presets start in full-access mode. When tool approvals are on, those presets use CLI defaults instead. | Preset | Tool approvals off | Tool approvals on | | -------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------- | | Claude | `claude --dangerously-skip-permissions` | `claude` | | Codex | `codex -c model_reasoning_effort="high" --ask-for-approval never --sandbox danger-full-access` | `codex -c model_reasoning_effort="high"` | | OpenCode | `opencode` | `opencode` | | Amp | `amp` | `amp` | | Pi | `pi` | `pi` | | Copilot | `copilot --allow-all` | `copilot --allow-all` | | Gemini | `gemini -y` | `gemini -y` | | None | No command | No command | For saved commands attached to the Run button, use [run scripts](/docs/reference/scripts#run-scripts). ## Demo [#demo] --- title: "Checkpoints" url: "/docs/reference/checkpoints" description: "View turn by turn changes in a workspace and revert to previous turns" --- # Checkpoints Checkpoints are automatic snapshots of an agent's changes to your codebase. They show you what changed in the most recent turn and let you revert to previous turns. ## Restoring Checkpoints [#restoring-checkpoints] To restore to a previous turn, hover over your message and click the revert icon. Clicking the revert icon will **permanently delete** all user and AI messages from the selected turn and later. All code changes made since that user message was sent will also be reverted. Once the reversion is complete, the agent will have no knowledge of the changes or conversation you deleted. ## How Checkpoints Work [#how-checkpoints-work] * Checkpoints are stored locally, separate from your working branch's Git history. * Before each supported agent responds to a user message, Conductor captures the working branch state in a private Git ref. * Each checkpoint therefore captures all AI and user code changes between when the previous and current user messages were sent. Exercise caution when using checkpoints if multiple chats are running in the same workspace. --- title: "Checks" url: "/docs/reference/checks" description: "Reference for merge readiness signals in a workspace" --- # Checks The Checks tab collects the state you need before merging a workspace. ## What it shows [#what-it-shows] Checks may include: * Git status * Pull request metadata * CI and status checks * Deployments * GitHub comments and review threads * Todos The available sections depend on the repository, whether a pull request exists, and which integrations are connected. ## How to use it [#how-to-use-it] Use the Checks tab as the last review pass before merge: 1. Confirm the branch has the changes you expect. 2. Open or update the pull request. 3. Fix failing checks. 4. Send unresolved comments to the agent or resolve them yourself. 5. Complete todos. 6. Merge when the workspace is ready. ## Blockers [#blockers] Conductor may block or discourage merge actions when required work is still open, such as unresolved todos or failed checks. Treat these as prompts to inspect the workspace before merging. For the full workflow, see [Review and merge a workspace](/docs/guides/review-and-merge). --- title: "Cities" url: "/docs/reference/cities" description: "How Conductor names workspaces after cities" --- # Cities Every Conductor workspace gets a city name. Cities make workspace names memorable and distinct. They also give each workspace a stable directory base, so agents, shells, editors, and other tools can keep finding the same files on disk. Conductor still uses the branch name or pull request title as the main way to identify active work. In the sidebar, the work item is primary; the city name is the place where that work lives. ## Why cities exist [#why-cities-exist] Conductor creates isolated workspaces so you can run agents in parallel without making them fight over one checkout. Each workspace gets its own branch, working tree, files, running processes, and `.context` folder. The city name is the friendly, durable part of that workspace location. For example, a workspace might live in a directory like `san-antonio-v3` while the branch explains what the workspace is doing. For the underlying workspace model, see [Isolated workspaces](/docs/concepts/workspaces-and-branches). ## Passport [#passport] You can see the cities you have visited in Passport. Open it from Command + K and search for `Passport`. Passport is mostly for fun. It turns your workspace history into a little travel log, including the rare cities you have found along the way. ## Finding every city [#finding-every-city] Conductor currently has 295 cities. If you keep every spawned workspace active, Conductor avoids city bases that are already active. In that case, finding all cities is deterministic: it is impossible before 295 active workspaces and guaranteed at 295 active workspaces. The probabilities below describe a different situation: visiting cities over time, where archived or deleted workspaces no longer prevent repeats. In that model, repeats are possible, and the last few cities take much longer to find. ## Chance of seeing all cities [#chance-of-seeing-all-cities] Approximate likelihood of having seen all 295 cities after `n` workspace spawns: | Workspaces spawned | Chance all cities seen | | ------------------ | ---------------------- | | 5,000 | 0.29% | | 6,000 | 1.68% | | 7,000 | 5.34% | | 8,000 | 11.81% | | 9,000 | 20.69% | | 10,000 | 30.99% | | 11,000 | 41.65% | | 12,000 | 51.83% | | 13,000 | 60.98% | | 14,000 | 68.87% | | 15,000 | 75.47% | | 16,000 | 80.84% | | 18,000 | 88.55% | | 20,000 | 93.27% | | 22,000 | 96.08% | | 24,000 | 97.74% | | 26,000 | 98.70% | | 28,000 | 99.25% | | 30,000 | 99.57% | ## Confidence milestones [#confidence-milestones] | Confidence | Workspaces needed | | ---------- | ----------------- | | 50% | \~11,815 | | 75% | \~14,923 | | 90% | \~18,516 | | 95% | \~21,101 | | 99% | \~26,964 | --- title: "conductor.json" url: "/docs/reference/conductor-json" description: "Legacy repository configuration file for Conductor" --- # conductor.json `conductor.json` is Conductor's legacy repository configuration file. New shared repository settings should use [`.conductor/settings.toml`](/docs/reference/settings) instead. If a repository has `.conductor/settings.toml`, Conductor treats the repository as migrated and ignores repo-level `conductor.json`. ## Current recommendation [#current-recommendation] Use `.conductor/settings.toml` for shared team settings: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "npm install" run_mode = "concurrent" [scripts.run.dev] command = "npm run dev" default = true icon = "play" ``` Commit `.conductor/settings.toml` when teammates should share the same configuration. Add `.conductor/settings.local.toml` to `.gitignore` for personal repository overrides: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` For supported TOML fields, see [Settings reference](/docs/reference/settings/reference). For precedence and file locations, see [User and project settings](/docs/reference/settings/user-project). For the team workflow, see [Share repository settings with teammates](/docs/reference/scripts/share-with-teammates). ## Legacy file format [#legacy-file-format] Older repositories may still contain `conductor.json` at the repository root: ```json title="conductor.json" { "scripts": { "setup": "npm install", "run": "npm run dev" }, "runScriptMode": "concurrent" } ``` Supported legacy fields: | Field | Type | TOML replacement | | ----------------------- | ----------------------------------- | -------------------------- | | `scripts.setup` | string | `scripts.setup` | | `scripts.run` | string | `scripts.run..command` | | `scripts.archive` | string | `scripts.archive` | | `runScriptMode` | `"concurrent"` or `"nonconcurrent"` | `scripts.run_mode` | | `enterpriseDataPrivacy` | boolean | `enterprise_data_privacy` | ## Migrate to settings.toml [#migrate-to-settingstoml] To migrate manually: 1. Create `.conductor/settings.toml`. 2. Move each legacy field to its TOML replacement. 3. Delete `conductor.json`. 4. Commit both changes. Example migration: ```json title="conductor.json" { "scripts": { "setup": "pnpm install", "run": "pnpm dev --port $CONDUCTOR_PORT", "archive": "./script/workspace-archive.sh" }, "runScriptMode": "concurrent", "enterpriseDataPrivacy": true } ``` becomes: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" enterprise_data_privacy = true [scripts] setup = "pnpm install" archive = "./script/workspace-archive.sh" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` If Conductor shows a migration prompt in Repository Settings, use it to create a migration pull request automatically. ## Related pages [#related-pages] * [Settings quickstart](/docs/reference/settings) * [User and project settings](/docs/reference/settings/user-project) * [Scripts](/docs/reference/scripts) * [Share repository settings with teammates](/docs/reference/scripts/share-with-teammates) * [Conductor environment variables](/docs/reference/environment-variables) --- title: "Deep links" url: "/docs/reference/deep-links" description: "Open Conductor and trigger actions via conductor:// URLs" --- # Deep links Conductor registers the `conductor://` URL scheme. Clicking a deep link (or opening it via `open conductor://...`) will activate Conductor and trigger the corresponding action. ## Supported links [#supported-links] ### Prompt [#prompt] ``` conductor://prompt= ``` Creates a new workspace in the first available repository with the given prompt pre-filled. ### Prompt + repository path [#prompt--repository-path] ``` conductor://prompt=&path= ``` Same as above, but targets the repository at the given path. Falls back to the first repo if the path doesn't match. ### Linear issue [#linear-issue] ``` conductor://linear_id=&prompt= ``` Fetches the Linear issue, auto-detects the matching repository, and either navigates to an existing workspace on that issue's branch or creates a new one. Requires a connected Linear account. ### Async plan [#async-plan] ``` conductor://async?repo=&plan= ``` Creates a new workspace with a base64-encoded plan attached as a markdown file. The `repo` parameter is optional and defaults to the first repository. ## Notes [#notes] * All parameter values should be URL-encoded. * The generic links (`prompt`, `path`, `linear_id`) use a flat `key=value&key=value` format directly after `conductor://`, without a hostname or path. * The `async` link uses standard URL structure with a hostname (`conductor://async?...`). --- title: "Diff viewer" url: "/docs/reference/diff-viewer" description: "Review workspace changes, comments, and PR-ready diffs" --- # Diff viewer The Diff Viewer shows the code changes in a workspace. Use it before creating a pull request, after an agent makes changes, and whenever review comments need another pass. ## What to review [#what-to-review] Check the diff for: * Files changed by the agent. * Unrelated or accidental edits. * Missing tests or docs. * Local comments and GitHub review comments. * Conflicts or files that need manual inspection. Use the file list to move between changed files. If you are reviewing from a summary, comment, or search result, jump directly to the file before leaving feedback. Change the diff view when it helps review: * Use unified diff when you want the old and new code in one column. * Use commit filtering when you need to review one commit at a time. ## Comments [#comments] Use comments when you want to send specific feedback back to the agent. Comments can point at changed lines, so the agent gets more precise context than it would from a general chat message. GitHub review comments can also appear in Conductor. When a thread is handled, resolve it so the Checks tab reflects the current review state. ## PR actions [#pr-actions] Conductor recommends actions as a workspace moves toward merge. Use those actions to create a pull request, respond to feedback, fix checks, and merge when the workspace is ready. When the suggested action is `Create PR`, Conductor walks you through turning the current workspace changes into a pull request. For a step-by-step review flow, see [Review and merge a workspace](/docs/guides/review-and-merge). --- title: "Conductor environment variables" url: "/docs/reference/environment-variables" description: "Variables available to terminals and scripts in a workspace" --- # Conductor environment variables Conductor makes these environment variables available in workspace terminals and [scripts](/docs/reference/scripts). | Variable | Description | | -------------------------- | ----------------------------------------------------------- | | `CONDUCTOR_WORKSPACE_NAME` | Workspace name | | `CONDUCTOR_WORKSPACE_PATH` | Workspace path | | `CONDUCTOR_ROOT_PATH` | Path to the repository root directory | | `CONDUCTOR_DEFAULT_BRANCH` | Name of the default branch, usually `main` | | `CONDUCTOR_PORT` | First port in a range of 10 ports assigned to the workspace | | `CONDUCTOR_IS_LOCAL` | `1` in local workspaces, `0` in cloud workspaces | ## Configure custom variables [#configure-custom-variables] Use settings when every agent, terminal, setup script, or run script in a repository needs the same custom environment variables: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [environment_variables] API_BASE_URL = "http://localhost:3000" [environment_variables.local] CONDUCTOR_TARGET = "local" [environment_variables.cloud] CONDUCTOR_TARGET = "cloud" ``` Use `environment_variables` for values shared by local and cloud agents. Use `environment_variables.local` and `environment_variables.cloud` when a value should only apply to one execution environment. Do not commit secrets to `.conductor/settings.toml`; use `.conductor/settings.local.toml` for machine-local secret values. For the full key reference, see [Settings reference](/docs/reference/settings/reference). ## Common uses [#common-uses] Use `CONDUCTOR_ROOT_PATH` when a setup script needs a file from the repository root: ```bash ln -s "$CONDUCTOR_ROOT_PATH/.env" .env ``` Use `CONDUCTOR_PORT` when multiple workspaces need to run the same app without port conflicts: ```bash npm run dev -- --port "$CONDUCTOR_PORT" ``` For script behavior, see [Scripts](/docs/reference/scripts). --- title: "Files to copy" url: "/docs/reference/files-to-copy" description: "Configure gitignored files that Conductor copies into new workspaces" --- # Files to copy New git worktrees start with tracked files only. That keeps workspaces clean, but it also means untracked files such as `.env.local`, local service credentials, and machine-specific config do not appear in new Conductor workspaces. Files to copy solves that problem by copying selected gitignored files from your main checkout into each new local workspace. For setup steps, see [Use Files to copy](/docs/guides/use-files-to-copy). For the underlying worktree model, see [Git worktrees for coding agents](/docs/concepts/git-worktrees). ## Configure Files to copy [#configure-files-to-copy] You can configure Files to copy in Conductor or in a settings file: * In the app, open `Settings`, select the project, and edit Files to copy. * In the repository, add `file_include_globs` to `.conductor/settings.toml` when the same patterns should be shared with teammates. Use this repository configuration when every new workspace should receive the same gitignored files: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" file_include_globs = """ .env.local config/local.json certs/local/** """ ``` Commit `.conductor/settings.toml` when every teammate should copy the same gitignored local files into new workspaces. For settings file locations and precedence, see [User and project settings](/docs/reference/settings/user-project). You can also configure shared patterns with `.worktreeinclude` at the repository root: ```txt title=".worktreeinclude" .env.local config/local.json certs/local/** ``` Use `.worktreeinclude` when your project already uses worktree tools that read that file, or when you want a small pattern-only project file. If both `.worktreeinclude` and `file_include_globs` exist, `.worktreeinclude` wins. ## What gets copied [#what-gets-copied] Git worktrees do not copy untracked files from your main checkout. That includes: * Gitignored environment files such as `.env.local`, `.env.development.local`, and `.env.test.local`. * Local config files such as `config/local.json`, `settings.local.json`, or `*.local`. * Credentials and tokens such as service account JSON files, API key files, and local certificate files. * Local database files, seed data, or fixture files that are intentionally ignored by Git. * Dependency folders, cache directories, and generated build output such as `node_modules`, `.next`, `dist`, or `target`. Conductor copies a gitignored file into a new local workspace when both of these are true: 1. The file is gitignored. 2. The file matches a Files to copy or `.worktreeinclude` pattern. Tracked files are already present in the new worktree, so Conductor does not copy them. Untracked files that are not gitignored are not eligible for Files to copy. Generated files, dependency folders, and files that need commands to create them usually belong in a [setup script](/docs/reference/scripts#setup-scripts) instead. Dependency folders and build output are usually large, machine-specific, and easy to regenerate. Copying `node_modules`, `.next`, `dist`, `target`, or similar directories can make workspace creation slower and can carry stale state into a fresh workspace. Use a [setup script](/docs/reference/scripts#setup-scripts) when a workspace should install dependencies, generate build output, or prepare local state with commands. Files to copy only selects files that Git already ignores. That keeps the feature focused on local files that intentionally stay out of version control, such as secrets and machine-specific config. If a file should be copied into every workspace but should not be committed, add it to `.gitignore`, then add a matching Files to copy or `.worktreeinclude` pattern. Files to copy currently runs for local Mac workspaces. ## Resolution order [#resolution-order] The patterns used for a given repo come from the first source that exists: 1. **`.worktreeinclude`** at the repo root. If present, the file's contents win and the settings UI shows a read-only preview. 2. **Repo settings** (`Settings -> {repo name} -> Files to copy`), stored as `file_include_globs` in repository settings. 3. **Default pattern** `.env*`. For project-shared patterns, commit a `.worktreeinclude` file at the repo root or set `file_include_globs` in `.conductor/settings.toml`. `.worktreeinclude` wins when both exist. If you add `.worktreeinclude` or repo settings, those patterns replace the default `.env*` pattern. Include `.env*` yourself when you still want Conductor to copy environment files. ## Pattern format [#pattern-format] `.worktreeinclude` uses [`.gitignore` syntax](https://git-scm.com/docs/gitignore). Anthropic documents the same behavior for [Claude Code worktrees](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees). Common pattern rules: * Blank lines are ignored. * `#` starts a comment. Escape it as `\#` when the pattern itself starts with `#`. * `!` negates a previous match. Escape it as `\!` when the pattern itself starts with `!`. * A trailing `/` matches a directory only. * A leading `/` anchors the pattern to the repo root. * A slash in the middle of a pattern makes the pattern relative to the repo root. * `*` matches anything except `/`. * `?` matches one character except `/`. * Character ranges such as `[0-9]` match one character in the range. * `**/name` matches `name` at any depth. * `directory/**` matches everything inside `directory` at any depth. * `a/**/b` matches `a/b`, `a/x/b`, `a/x/y/b`, and deeper nested paths. ## Examples [#examples] Copy common environment files: ```txt title=".worktreeinclude" .env .env.* ``` Copy a root-only local file without copying files with the same name in packages: ```txt title=".worktreeinclude" /config/local.json ``` Copy nested secrets config files: ```txt title=".worktreeinclude" **/secrets.local.json config/**/local.json ``` Copy a directory of ignored local data, except examples: ```txt title=".worktreeinclude" .local-secrets/** !.local-secrets/**/*.example ``` ## Related pages [#related-pages] * [Use Files to copy](/docs/guides/use-files-to-copy) for a guided setup flow. * [`.worktreeinclude`](/docs/reference/worktreeinclude) for the shared project file format. * [Git worktrees for coding agents](/docs/concepts/git-worktrees) for the underlying worktree model. * [Run Claude Code with Git worktrees](/docs/guides/git-worktrees/run-claude-code-with-git-worktrees) and [Run Codex with Git worktrees](/docs/guides/git-worktrees/run-codex-with-git-worktrees) for agent-specific worktree workflows. --- title: "Keyboard shortcuts" url: "/docs/reference/keyboard-shortcuts" description: "Conductor shortcuts for navigation, workspaces, chat, review, Git, terminal, and app actions" --- # Keyboard shortcuts Use the keyboard shortcuts dialog for the current in-app list. Open it with Command + /. --- title: "MCP" url: "/docs/reference/mcp" description: "Configure Model Context Protocol servers for Claude Code, Codex, and Cursor Composer workflows" --- # MCP Conductor sessions can use Model Context Protocol (MCP) servers where the selected agent host supports MCP. Claude Code and Codex sessions load their agent-specific MCP configuration inside Conductor. Cursor Composer MCP servers are configured in Cursor and apply when you open a Conductor workspace in Cursor. Use MCP when an agent needs repeatable access to external tools, private data, or workflow actions such as documentation search, issue tracking, database queries, or internal APIs. For a step-by-step setup, see [Set up MCP servers](/docs/guides/configure-mcp-servers). ## How MCP works [#how-mcp-works] MCP uses a client-server model. The agent host starts or connects to one MCP server per configured integration, discovers the server's available tools, and routes tool calls to that server during the conversation. Official MCP docs describe three core server primitives: | Primitive | What it provides | Example use in coding work | | --------- | ----------------------------------------------- | -------------------------------------------------- | | Tools | Executable functions the agent can call | Search docs, create an issue, query a database | | Resources | Data sources the agent can read as context | Read API docs, schema metadata, or project records | | Prompts | Reusable prompt templates exposed by the server | Run a project-specific workflow | See the official [MCP architecture overview](https://modelcontextprotocol.io/docs/learn/architecture) for the protocol model. ## Transport types [#transport-types] | Transport | Use it when | Notes | | --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `stdio` | The server runs as a local command, such as `npx`, `node`, `python`, or a local binary. | The MCP client launches the process and exchanges JSON-RPC messages over stdin and stdout. | | Streamable HTTP | The server is hosted at a URL and supports the current MCP HTTP transport. | Remote servers can use bearer tokens, OAuth, API keys, and custom headers. | | SSE | You already depend on an older server that has not moved to Streamable HTTP. | Claude Code still documents SSE, but marks it deprecated in favor of HTTP where available. | The official [MCP transports specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) defines `stdio` and Streamable HTTP as the standard transports. ## Configuration scopes [#configuration-scopes] | Scope | Claude Code | Codex | Cursor Composer | Use it for | | ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------- | | User | `~/.claude.json` or `claude mcp add --scope user` | `~/.codex/config.toml` or `codex mcp add` | `~/.cursor/mcp.json` or Cursor's MCP settings UI | Personal MCP servers you want available across repositories. | | Project | `.mcp.json` in the repository root | `.codex/config.toml` scoped to the trusted project | `.cursor/mcp.json` in the repository root | Shared project MCP servers that should follow the repository. | | Local project | `~/.claude.json` under the current project path | Personal `~/.codex/config.toml` entries, optionally limited to trusted projects in the Codex config. | Local Cursor config that is not committed | Machine-specific credentials or experiments. | Conductor does not define a separate MCP config format. It uses the MCP configuration that Claude Code and Codex load for the session. Cursor Composer uses Cursor's MCP configuration when the workspace is open in Cursor. ## Add a Claude Code MCP server [#add-a-claude-code-mcp-server] Add a user-scoped `stdio` server with the Claude Code CLI: ```bash claude mcp add -s user -- [args...] ``` For example, add Context7 for documentation search: ```bash claude mcp add context7 -s user -- npx -y @upstash/context7-mcp ``` Use the `--` separator before the server command and arguments. Claude Code treats flags before `--` as Claude options and everything after `--` as the server command. For more options, see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp). ## Add a Codex MCP server [#add-a-codex-mcp-server] Add a `stdio` server with the Codex CLI: ```bash codex mcp add -- [args...] ``` For example, add Context7 for documentation search: ```bash codex mcp add context7 -- npx -y @upstash/context7-mcp ``` Codex stores MCP configuration in `~/.codex/config.toml`. The Codex CLI and IDE extension share that configuration. You can also edit `config.toml` directly: ```toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] ``` Codex also supports streamable HTTP MCP servers: ```bash codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp ``` For more options, see the [Codex MCP docs](https://developers.openai.com/codex/mcp) and [Codex configuration reference](https://developers.openai.com/codex/config-reference). ## Add a Cursor Composer MCP server [#add-a-cursor-composer-mcp-server] Add Cursor Composer MCP servers in Cursor's MCP settings UI or by editing `mcp.json`. Cursor supports user-level and project-level MCP configuration: ```json title=".cursor/mcp.json" { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` Use `.cursor/mcp.json` when the MCP server should follow a repository. If you open a Conductor workspace in Cursor, Cursor reads the project-level `.cursor/mcp.json` from that workspace checkout. For more options, see the [Cursor MCP docs](https://cursor.com/docs/mcp). ## Project-level MCP servers [#project-level-mcp-servers] If a repository has an `.mcp.json` file at its project root, Claude Code sessions in that Conductor workspace inherit those MCP servers. For Codex, you can scope MCP servers to a trusted project with `.codex/config.toml`. For Cursor Composer, use `.cursor/mcp.json` at the repository root. This is Cursor's project-level MCP config file, not the same file as Claude Code's root `.mcp.json`. If you're moving project-level MCP config from Cursor, see [Work with Cursor and VS Code](/docs/guides/migrate-from-cursor#migrate-mcp-servers). ## Status in Conductor [#status-in-conductor] Conductor can show MCP server status for Claude Code and Codex in the chat composer and the `MCP status` dialog. Before a session starts, the status reflects the workspace-level configuration Conductor can discover. After a session starts, the status reflects the running session. Use `Refresh status` after you change MCP configuration. For Codex, Conductor opens `codex mcp list` in a terminal when you run the MCP command flow, because the Codex CLI expects a concrete `mcp` subcommand. Cursor Composer MCP server status is managed in Cursor's MCP UI. Conductor-hosted Cursor sessions do not currently surface Cursor MCP server status in Conductor's MCP status UI. ## Good candidates [#good-candidates] MCP works best for tools an agent needs repeatedly, such as documentation search, issue tracking, databases, and internal APIs. Common examples include Context7 for documentation search and Linear for issue management. ## Security and privacy [#security-and-privacy] MCP servers can run local commands, read local data, and send data to external services depending on the server you configure. Review the server command, requested credentials, and tool list before adding it. For local MCP servers, prefer trusted packages or local code you control. The official [MCP security best practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) recommend clear consent before running local server commands and warn that local MCP servers run with the user's privileges unless sandboxed. Enterprise data privacy disables custom MCP servers. See [Security and permissions](/docs/reference/security-and-permissions#enterprise-data-privacy). --- title: "Privacy" url: "/docs/reference/privacy" description: "What we do (and don't do) with your data" --- # Privacy ## What data do we use? [#what-data-do-we-use] We don't look at your chats, and we don't want to. Your chats are between you and your AI. We do collect analytics data, like what features you use, crash logs, etc. This helps us fix bugs and learn which parts of Conductor to improve. ## Where do you store my chats? [#where-do-you-store-my-chats] Your chat history is saved locally in the Application Support directory `~/Library/Application Support/com.conductor.app`. None of it is stored on our servers. ## What types of data does Conductor collect? [#what-types-of-data-does-conductor-collect] Most app data is stored locally on your computer in the Application Support directory. Here's what we store elsewhere: In an encrypted Postgres database served by Fly, we store: * Your account data (such as your email address, and if you integrate with GitHub, installation data) We store analytics data in [PostHog](https://posthog.com/) when an event occurs in the app, such as * You create a workspace, select a model, or send a message (including metadata like which model was involved and which app features you’re using) * A model provider returns an error (including the error message) * An unexpected error occurs (including the error message and stack trace) PostHog stores data about your computer, like your OS and IP address. We don't capture or store any session recordings. ## Where does my network traffic go? [#where-does-my-network-traffic-go] All network traffic goes straight to your model provider. By default, this is Anthropic, but you can set custom provider variables, such as Bedrock or Vertex variables, in `Settings` -> `Environment`. ## What data do the model providers collect? Are my messages used for training? [#what-data-do-the-model-providers-collect-are-my-messages-used-for-training] You can find the privacy policy of our model providers here: * [Anthropic](https://www.anthropic.com/legal/privacy) * [OpenAI](https://openai.com/policies/row-privacy-policy/) ## Is my data encrypted? Who can access my data? [#is-my-data-encrypted-who-can-access-my-data] Any data we store (like your email) is encrypted in a Fly Postgres database or on PostHog's servers (both SOC 2 compliant). It can be accessed only by Conductor employees. ## Enterprise data privacy [#enterprise-data-privacy] Disable features requiring external AI providers, such as AI generated chat titles, as well as custom MCP servers. * **User level** — toggle it in `Settings` -> `Privacy`. This applies to your machine only. * **Repo level** — set `enterprise_data_privacy` to `true` in [`.conductor/settings.toml`](/docs/reference/settings/user-project). This applies to everyone working in the repo when the file is committed. ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" enterprise_data_privacy = true ``` These settings are independent — if either one is enabled, enterprise data privacy is enabled. You don't need to configure both. --- title: "Security and permissions" url: "/docs/reference/security-and-permissions" description: "How local execution, tool approvals, macOS permissions, and network traffic work" --- # Security and permissions Conductor runs agents on your Mac. Agents use your local environment and can interact with files, terminals, and tools that your user account can access. ## Local execution [#local-execution] Conductor is a Mac app, not a hosted IDE. Your workspaces, chats, and repository files are stored locally unless a connected provider or integration receives data as part of a request. ## Agent permissions [#agent-permissions] Agents can read and write files, run commands, and use configured tools. Some tool calls may ask for approval before the agent continues. Use approvals when you want to review actions such as shell commands, file changes, MCP tool use, web fetches, or other tool access before they run. For MCP setup and transport details, see [MCP](/docs/reference/mcp). For a setup workflow, see [Set up MCP servers](/docs/guides/configure-mcp-servers). ## macOS permission prompts [#macos-permission-prompts] macOS may show a permission prompt when an agent or shell command tries to access a protected folder such as Downloads, Desktop, or Reminders. The prompt may name Conductor because Conductor is the app launching the process. Approve only access you expect the task to need. ## Network traffic [#network-traffic] Model requests go to your model provider. By default, this is Anthropic for Claude Code. If you configure another provider, traffic goes to that provider. For provider setup, see [Configure model providers](/docs/guides/providers). ## Enterprise data privacy [#enterprise-data-privacy] Enterprise data privacy disables features that require external AI providers, such as AI-generated chat titles and custom MCP servers. You can enable it in: * `Settings` -> `Privacy` for your machine * `enterprise_data_privacy` in [`.conductor/settings.toml`](/docs/reference/settings/user-project) for a repository --- title: "Shell configuration" url: "/docs/reference/shells" description: "Configure shell setup" --- # Shell configuration Conductor uses your login shell environment to run setup scripts, run scripts, terminals, and agents. We try to make your environment work out of the box, the same way it would work in your terminal. To do this, Conductor launches an interactive login shell in each workspace to capture environment variables which will be reused later. (We use the workspace directory because tools like `mise` can change their behavior depending on the current directory.) Although Conductor captures your shell environment using your login shell (`$SHELL`), it runs most commands—including your setup and run scripts—using `zsh`. ## Common issues [#common-issues] If your shell configuration (e.g., `.zshrc` or `.zshenv`) is slow or contains errors, Conductor may fail to launch agents or run commands. Possible causes include * Interactivity: if shell startup tries to read input, it will hang inside Conductor's non-interactive environment * Slowness: Conductor gives your shell configuration 5 seconds to load. If it doesn't load within that time, it will abort. To check how long the shell takes to start, run: ```bash time "$SHELL" -ilc env ``` ## Put setup directly in your script [#put-setup-directly-in-your-script] Where possible, add required setup to your Conductor setup or run script so the command does not depend on interactive shell configuration. ```bash export PATH="$HOME/.local/bin:/opt/homebrew/bin:$PATH" eval "$(mise activate zsh)" pnpm install ``` This makes the script easier to understand, share, and debug because the required environment setup lives next to the command that needs it. ## Put minimal shared setup in .zshenv [#put-minimal-shared-setup-in-zshenv] Use `.zshenv` when configuration must be available to every zsh script, including non-interactive scripts. Keep `.zshenv` minimal. Avoid prompts, slow commands, terminal UI setup, or anything that assumes an interactive terminal. When reliability matters most, put setup directly into your scripts. Conductor tries to capture your interactive shell environment, but that capture can fail, time out, or become stale. --- title: "Slash commands" url: "/docs/reference/slash-commands" description: "Reusable prompt commands for agent chats" --- # Slash commands Slash commands are reusable prompts stored as Markdown files. Use them for prompts your team runs often, such as review checklists, release steps, or debugging workflows. ## Command location [#command-location] Create custom commands in `.claude/commands/`. They appear in the chat composer when you type `/`: ```bash mkdir -p ~/.claude/commands echo "Your prompt here" > ~/.claude/commands/.md ``` The file name becomes the slash command name. ## Good commands [#good-commands] Good slash commands are specific and reusable. Include the role, the task, the expected output, and any constraints the agent should follow. ## Learn more [#learn-more] For Claude Code command behavior, see the [Claude Code slash command docs](https://docs.anthropic.com/en/docs/claude-code/slash-commands). --- title: "Todos" url: "/docs/reference/todos" description: "Track merge-blocking work in a workspace" --- # Todos Todos track work that must be finished before a workspace merges. ## How todos work [#how-todos-work] The todos section shows what still needs to happen before merge. You can add your own todos, and agents can use todos to organize longer tasks. Workspaces are blocked until todos are checked off, so known unfinished work does not merge by accident. ## Send todos to the agent [#send-todos-to-the-agent] Mention `@todos` in the composer when you want the agent to see the current todo list. ## When to clear todos [#when-to-clear-todos] Clear a todo only when the work is complete or no longer applies. If a todo is no longer relevant, remove it instead of checking it off as completed. --- title: ".worktreeinclude" url: "/docs/reference/worktreeinclude" description: "Project file format for shared Files to copy patterns" --- # .worktreeinclude Git worktrees do not copy gitignored local files by default. `.worktreeinclude` is the project file format that tells Conductor which gitignored files to copy into new local workspaces. Add `.worktreeinclude` to the repository root when every new local workspace should receive the same local files. You can also configure the same behavior in `.conductor/settings.toml`. Use the [Files to copy reference](/docs/reference/files-to-copy) for settings examples, eligibility rules, precedence, defaults, and pattern syntax. Use [Use Files to copy](/docs/guides/use-files-to-copy) for a guided setup flow. ## What .worktreeinclude does [#what-worktreeinclude-does] A `.worktreeinclude` file lists gitignored files that should be copied into new local workspaces. Conductor reads `.worktreeinclude` through Files to copy. Claude Code also documents the same file for [copying gitignored files into worktrees](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees), so it is useful when a project uses both tools. The important safety rule is that `.worktreeinclude` does not make a file tracked. It only selects files that Git already ignores. For example: ```txt title=".worktreeinclude" .env.local config/secrets.json certs/local/** ``` This says: when a matching file exists in the main checkout and Git ignores it, copy it into the new local workspace. ## When to commit it [#when-to-commit-it] Commit `.worktreeinclude` when the project needs the same local files in every worktree. The file contains patterns, not secret values, so it can usually live safely in Git. That gives every teammate and every new local workspace the same rule: * keep secret values out of Git * keep the list of required local files in Git * create worktrees without repeating manual copy steps If the pattern is personal to one machine, use Conductor's per-repo Files to copy setting instead of committing `.worktreeinclude`. You can configure personal or repository-specific Files to copy patterns with `file_include_globs` in Conductor settings: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" file_include_globs = """ .env.local config/local.json """ ``` If `.worktreeinclude` exists, it wins over `file_include_globs`. See [Files to copy](/docs/reference/files-to-copy) for the full precedence rules. ## What not to solve with .worktreeinclude [#what-not-to-solve-with-worktreeinclude] Use `.worktreeinclude` for static gitignored files that already exist in the main checkout. Use a [setup script](/docs/reference/scripts#setup-scripts) when the workspace needs to run commands, install dependencies, generate files, create symlinks, or fetch secrets from a password manager or cloud secret store. Use your hosting provider or deployment environment for production secrets. `.worktreeinclude` is a local development convenience, not a production secret-management system. ## Pattern syntax [#pattern-syntax] `.worktreeinclude` uses [`.gitignore` pattern syntax](https://git-scm.com/docs/gitignore), including comments, root-anchored paths, nested globs, directory patterns, and negation with `!`. See [Files to copy](/docs/reference/files-to-copy) for the full syntax reference and examples. --- title: "Troubleshooting issues" url: "/docs/troubleshooting/issues" description: "Fix common authentication, agent, script, workspace, review, and known product issues" --- # Troubleshooting issues Use this page when Conductor cannot start work, run a project, restore a workspace, or merge a finished branch. ## Authentication issues [#authentication-issues] Use this section when Conductor cannot create workspaces, start agents, fetch GitHub data, or call a model provider. ### GitHub [#github] Conductor expects GitHub authentication to work in your terminal environment. Run: ```bash gh auth status ``` If the command fails, sign in again: ```bash gh auth login ``` Then restart Conductor and try the action again. ### Claude Code [#claude-code] If Claude Code cannot start or authenticate, run: ```bash claude /login ``` Conductor uses the Claude Code authentication available on your machine unless you configure provider-specific environment variables. ### Codex [#codex] If Codex cannot start, check the model picker and your OpenAI authentication or subscription setup. If you configured an API key, confirm it is available in Conductor's environment settings. ### Custom providers [#custom-providers] If a custom provider fails: 1. Confirm the provider environment variables are set in `Settings` -> `Environment`. 2. Confirm the provider supports the model you selected. 3. Restart the affected chat after changing provider variables. For provider examples, see [Configure model providers](/docs/guides/providers). ## Script issues [#script-issues] Use this section when setup scripts, run scripts, or archive scripts fail. ### Setup script fails [#setup-script-fails] The setup script runs inside the newly created workspace. It should only depend on files that exist in the workspace or paths exposed through Conductor environment variables. Check these common causes: * The script expects ignored files such as `.env` to be copied automatically. * Dependencies are installed in the repository root but not in the workspace. * The script assumes a fixed absolute path. * A command needs authentication that is not available in the workspace shell. Use `$CONDUCTOR_ROOT_PATH` when the script needs to read from the repository root. ### Run script fails [#run-script-fails] The run script runs when you click the Run button. Check these common causes: * The app uses a fixed port that is already in use. * Multiple workspaces are trying to use the same database, cache, or external service. * The script starts a background process with `&` instead of running the foreground process. * The command works in your root checkout but not in a workspace. Use `$CONDUCTOR_PORT` for workspace-specific ports. ### Archive script fails [#archive-script-fails] The archive script runs before Conductor archives a workspace. Keep it focused on cleanup for resources outside the workspace directory. If the script fails, archive may not complete. Fix the command and try again. ### Environment variables are missing [#environment-variables-are-missing] Conductor exposes variables such as `CONDUCTOR_WORKSPACE_PATH`, `CONDUCTOR_ROOT_PATH`, and `CONDUCTOR_PORT` to terminals and scripts. For the full list, see [Conductor environment variables](/docs/reference/environment-variables). ## Agent issues [#agent-issues] Use this section when a chat is not progressing as expected. ### The agent is waiting for input [#the-agent-is-waiting-for-input] If the sidebar shows that a session needs input, open the workspace and answer the agent's question. The agent may be blocked on a product decision, missing context, or a requested approval. ### The agent needs permission [#the-agent-needs-permission] Review the requested action before approving it. If the action is not needed, deny it or ask the agent to use a different approach. Permission prompts can appear for shell commands, tool use, MCP access, web access, or file changes. ### Claude Code or Codex cannot find a command [#claude-code-or-codex-cannot-find-a-command] Conductor bundles specific versions of Claude Code and Codex with the app to maximize compatibility. If your Claude Code or Codex setup depends on custom shell configuration, MCP configuration, or tools installed in your system `PATH`, use your system-installed agent executable instead. Cursor sessions do not use a Cursor executable path. If Cursor cannot start, confirm that `CURSOR_API_KEY` is configured in `Settings` -> `Harnesses` -> `Cursor`. Try these steps: 1. Open `Settings` -> `Storage`. 2. Find the `Claude Code executable path` or `Codex executable path` setting. 3. Click `Use system Claude Code (from PATH)` or `Use system Codex (from PATH)` if the button is available. 4. If the button is not available, enter the path returned by `which claude` or `which codex` in your terminal. 5. Restart the affected chat. ### The agent is in the wrong mode [#the-agent-is-in-the-wrong-mode] If the agent keeps planning instead of editing, exit Plan Mode. If it starts editing before you want it to, enter Plan Mode and ask for a plan first. For mode details, see [Agent modes](/docs/concepts/agent-modes). ### The agent appears stuck [#the-agent-appears-stuck] Try these steps: 1. Wait for any running command to finish. 2. Check whether the agent is waiting for approval or user input. 3. Cancel the current response if it is no longer useful. 4. Start a new message with the exact next action you want. 5. If the chat state is confused, start a new chat or use a checkpoint if available. Use [Checkpoints](/docs/reference/checkpoints) when you need to revert both code changes and later chat state. ## Workspace issues [#workspace-issues] Use this section when a workspace cannot open, cannot be restored, or conflicts with another workspace. ### Restore an archived workspace [#restore-an-archived-workspace] Open the History pane from the sidebar. Find the archived workspace and restore it. Conductor restores the chat history and workspace state it has saved. ### A workspace path is missing [#a-workspace-path-is-missing] If a workspace directory was moved or deleted outside Conductor, Conductor may not be able to open it. Use the History pane to inspect the workspace. If restore fails, create a new workspace from the branch or pull request and continue from there. ### A branch is already checked out [#a-branch-is-already-checked-out] A Git branch can only be checked out in one worktree at a time. If Conductor cannot create or switch to a branch, another workspace or local checkout may already be using it. Use one of these fixes: * Switch the other workspace to a different branch. * Create a new branch based on the existing one. * Archive the old workspace if you no longer need it. ### Old nested `.conductor` workspaces [#old-nested-conductor-workspaces] Older Conductor repositories may still have workspaces inside a `.conductor` folder under the repository root. Newer workspaces live under `~/conductor/workspaces/`. If nested source directories confuse your build tools, remove and re-add the repository: 1. Find the workspace name in the sidebar. 2. Next to the name, click the "Repository details" button. 3. Click "Remove". This deletes all workspaces and chats for that repository. 4. Add the repository again. If you still run into issues, contact [support@conductor.build](mailto:support@conductor.build). ## Review and merge issues [#review-and-merge-issues] Use this section when a workspace is close to merge but Conductor still shows blockers. ### Checks are failing [#checks-are-failing] Open the Checks tab and inspect the failing item. If the failure includes logs or enough context, send it to the agent and ask for a fix. Run the relevant test locally before trying to merge again. ### Comments are unresolved [#comments-are-unresolved] GitHub review comments and local review comments may appear in the Diff Viewer or Checks tab. For each comment: 1. Send it to the agent or fix it yourself. 2. Confirm the diff changed as expected. 3. Resolve the thread when the issue no longer applies. ### Todos are blocking merge [#todos-are-blocking-merge] Open the todos section and complete or remove each todo. Conductor blocks unfinished work so a workspace does not merge while known tasks are still open. ### Merge conflicts [#merge-conflicts] Pull the latest changes from the target branch, inspect conflicts, and ask the agent to resolve them if needed. Give the agent the conflict context and the intended behavior, not only the command output. After conflicts are resolved, rerun tests and review the diff before merging. ## Known issues [#known-issues] ### Why doesn't undo (cmd+z) work when I'm writing a message? [#why-doesnt-undo-cmdz-work-when-im-writing-a-message] The library we use to do @-mentions breaks the undo history. We're looking into other solutions. ### Why do I see garbage when I switch between terminal windows? [#why-do-i-see-garbage-when-i-switch-between-terminal-windows] We're streaming output from your shell along to the UI, and at some point along the way, the stream is probably getting corrupted. We're still working to track down this bug. --- title: "Run Claude Code with Git worktrees" url: "/docs/guides/git-worktrees/run-claude-code-with-git-worktrees" description: "Use Claude Code in Conductor workspaces so parallel sessions get separate branches, files, and setup" --- # Run Claude Code with Git worktrees Use this guide when you want two Claude Code tasks to run in parallel without sharing one checkout, one branch, or one run environment. Conductor solves that by creating a separate workspace for each task, then attaching the Claude chat, branch, setup, and review flow to that workspace. The workflow is: * Create a new workspace. * Let Conductor create the branch and git worktree. * Let Conductor run setup, copy local files, and keep the chat attached to that workspace. * Start a Claude Code session inside the workspace. For the full Conductor workflow, see [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions). For the underlying Git model, see [Git Worktrees](/docs/concepts/git-worktrees). For Claude's upstream worktree behavior, see the official [Claude Code worktrees docs](https://code.claude.com/docs/en/worktrees). ## Run Claude Code in a Conductor workspace [#run-claude-code-in-a-conductor-workspace] ### Add the repository to Conductor [#add-the-repository-to-conductor] Open your project in Conductor if it is not already there. ### Create a new workspace [#create-a-new-workspace] Create a workspace with Command + N when the Claude task should have its own branch, files, and review path. Conductor creates the new workspace as its own git worktree and branch. It bases that workspace on the repository's configured base branch and fetches from `origin` first, so the workspace starts from the latest remote commit. ### Prepare the workspace before Claude starts [#prepare-the-workspace-before-claude-starts] A fresh Conductor workspace starts with tracked Git files only. Use one of these Conductor setup paths: * Use [Files to copy](/docs/reference/files-to-copy) or `.worktreeinclude` for static gitignored files such as `.env.local` and local config. * Use a [setup script](/docs/reference/scripts#setup-scripts) for dependency installs, generated files, symlinks, or per-workspace resources. Files to copy currently runs for local Mac workspaces. If you need the same setup in cloud workspaces too, put the required steps in `scripts.setup`. ### Start a Claude Code chat [#start-a-claude-code-chat] Open the workspace and start a new chat with Claude Code as the agent. This keeps the Claude session attached to the workspace's branch, terminal, diff, checks, and PR flow. ### Run the project from the workspace [#run-the-project-from-the-workspace] Use the Run button or the terminal from inside the workspace. If your app needs separate ports per workspace, use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) in your run script or setup script. If the project cannot run cleanly from a workspace directory, use [Spotlight testing](/docs/reference/scripts/spotlight-testing). ## Why use Conductor instead of a raw Claude worktree [#why-use-conductor-instead-of-a-raw-claude-worktree] Conductor adds the parts around Claude Code that usually become manual: * Per-workspace branches and chats. * [Files to copy](/docs/reference/files-to-copy) for `.worktreeinclude`-style local files in local workspaces. * [Setup scripts](/docs/reference/scripts#setup-scripts) and run scripts per workspace. * Review and PR flow attached to the same workspace. * A repeatable path for running more than one Claude task in parallel. ## Caveats that matter [#caveats-that-matter] Conductor uses Git worktrees under the hood, so the normal branch rule still applies: one checked-out branch can only belong to one worktree at a time. When work should move independently, create another workspace instead of reusing the same branch elsewhere. Use Files to copy for static gitignored files that already exist in your main checkout. Use a setup script when the workspace needs commands, generated files, symlinks, or per-workspace resources. Most projects need both only if they have both copied local files and command-based setup. If your main pain is missing env files in new workspaces, start with [Use Files to copy](/docs/guides/use-files-to-copy). If you are setting up Conductor for the first time, start with [Your first workspace](/docs/first-workspace). For the broader multi-session workflow, see [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions). --- title: "Run Codex with Git worktrees" url: "/docs/guides/git-worktrees/run-codex-with-git-worktrees" description: "Use Codex in Conductor workspaces so each task gets its own branch, files, and run environment" --- # Run Codex with Git worktrees Use this guide when you want Codex to work on a task without taking over your main checkout or colliding with another agent session. Conductor solves that by creating a separate workspace for the task, then keeping the Codex chat, branch, terminal, and review flow attached to that workspace. You do not need to start from Codex app's own Worktree mode. Conductor already creates a separate git worktree and branch for each workspace, then lets you choose Codex as the agent in that workspace. For the full Conductor workflow, see [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions). For the Git model behind that workflow, see [Git Worktrees](/docs/concepts/git-worktrees). For Codex's upstream worktree behavior, see the official [Codex worktrees docs](https://developers.openai.com/codex/app/worktrees). ## Run Codex in a Conductor workspace [#run-codex-in-a-conductor-workspace] ### Add the repository to Conductor [#add-the-repository-to-conductor] Open the project in Conductor if it is not already there. ### Create a new workspace for the Codex task [#create-a-new-workspace-for-the-codex-task] Create a workspace with Command + N when the Codex task should have its own branch, files, terminal commands, and review path. Conductor creates the workspace as its own git worktree and starts it from the repository's configured base branch. ### Prepare the workspace before Codex starts [#prepare-the-workspace-before-codex-starts] Prepare the workspace the same way you would prepare any Conductor workspace: * Use [Files to copy](/docs/reference/files-to-copy) for static gitignored files in local workspaces. * Use a [setup script](/docs/reference/scripts#setup-scripts) for dependency installs, generated files, symlinks, and command-based preparation. * Use a [run script](/docs/reference/scripts#run-scripts) when the workspace should have a normal dev server or watcher behind the Run button. ### Start a Codex chat in that workspace [#start-a-codex-chat-in-that-workspace] Open the workspace and choose Codex as the agent for the session. That gives Codex a separate workspace path, branch, chat, terminal, diff, and PR flow without disturbing your main checkout or another active workspace. ### Review and merge from the workspace [#review-and-merge-from-the-workspace] When the work is ready, use the Diff Viewer, Checks panel, and PR flow from the same Conductor workspace. ## Caveats that matter [#caveats-that-matter] In Conductor, separate workspaces are the default tool for independent Codex tasks. If two tasks should ship separately, give them separate workspaces rather than separate chats in one workspace. Files to copy currently runs for local Mac workspaces. If a Codex workflow must behave the same in cloud workspaces, put the required preparation in `scripts.setup` instead of relying only on copied local files. ## Why use Conductor instead of raw worktrees [#why-use-conductor-instead-of-raw-worktrees] Conductor gives Codex the surrounding workflow that raw worktrees do not: * A workspace per task, branch, and agent chat. * [Files to copy](/docs/reference/files-to-copy) for ignored local files that new local workspaces need. * [Setup scripts](/docs/reference/scripts#setup-scripts) and run scripts per workspace. * GitHub review and PR flow attached to the workspace. * A clean way to run Codex beside Claude Code or other workspaces in parallel. If your main challenge is bringing `.env.local` and similar files into new workspaces, see [Use Files to copy](/docs/guides/use-files-to-copy). If you are setting up Conductor for the first time, start with [Your first workspace](/docs/first-workspace). For the broader multi-session workflow, see [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions). --- title: "Run multiple Claude Code sessions in parallel" url: "/docs/guides/parallel-agents/run-multiple-claude-code-sessions" description: "Use Conductor workspaces to run several Claude Code tasks at once without sharing one checkout, branch, or review path" --- # Run multiple Claude Code sessions in parallel Use this guide when you want more than one Claude Code task moving at the same time. In Conductor, the unit of independent Claude Code work is a workspace. Create one workspace for each task that should have its own branch, working tree, setup context, terminal, diff, and pull request path. Claude Code also documents a native `claude --worktree` workflow for parallel CLI sessions. Use Conductor when you want that separation plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the decision model, see [Parallel agents](/docs/concepts/parallel-agents). For Claude Code's native worktree behavior, see the official [Claude Code worktrees docs](https://code.claude.com/docs/en/worktrees) and [Claude Code overview](https://code.claude.com/docs/en/overview). ## Choose the unit of parallel work [#choose-the-unit-of-parallel-work] Before you start more sessions, decide whether the work needs isolation or shared state. Use separate workspaces when each Claude Code task should become its own branch, review, or pull request. This is the common path for independent features, bug fixes, issue fanout, and experiments. Use multiple chats in one workspace when the agents need the same branch and current code state, such as one Claude Code session implementing while another reviews or fixes tests. ## Run several Claude Code tasks [#run-several-claude-code-tasks] ### Prepare the repository once [#prepare-the-repository-once] Add the repository to Conductor and make sure a new workspace can run the project. Use [Files to copy](/docs/reference/files-to-copy) for static gitignored files such as `.env.local`. Use a [setup script](/docs/reference/scripts#setup-scripts) for commands that install dependencies, generate files, create symlinks, initialize local databases, or prepare other per-workspace resources. ### Create one workspace per independent task [#create-one-workspace-per-independent-task] Create a workspace with Command + Shift + N or the `...` button next to `New workspace`. Start from a GitHub issue, Linear issue, pull request, branch, or a new task. Conductor creates a separate git worktree and branch for the workspace, then keeps the Claude Code session attached to that workspace. ### Start Claude Code in each workspace [#start-claude-code-in-each-workspace] Open the workspace and start a Claude Code chat. Give each session a narrow prompt that names the task, expected outcome, constraints, and validation command. Repeat this for each independent task you want running in parallel. ### Run and test each workspace separately [#run-and-test-each-workspace-separately] Use a [run script](/docs/reference/scripts#run-scripts), terminal command, or [Spotlight testing](/docs/reference/scripts/spotlight-testing) from the workspace that owns the change. Setup and run scripts execute from the workspace directory. If several workspaces need local servers at once, use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) so each workspace gets a separate port range. ### Review and merge workspace by workspace [#review-and-merge-workspace-by-workspace] Open the Diff Viewer with Command + Shift + D and inspect one workspace at a time. Use the [Checks tab](/docs/reference/checks) to track git status, CI, deployments, comments, and todos. Merge and archive the workspaces that are ready; keep revising or archive the ones that are not worth shipping. ## Keep the sessions coordinated [#keep-the-sessions-coordinated] * Give each Claude Code session a task that can finish independently. * Avoid assigning two workspaces the same file-heavy refactor unless you expect merge conflicts. * Keep shared context in committed docs, repository instructions, or the workspace `.context` directory, not only in one chat. * Use one workspace when the agents need to see and edit the same in-progress branch. ## Caveats [#caveats] Conductor runs Claude Code through the Claude Code setup available on your machine. Parallel work can still be limited by your account, model access, local resources, and Claude Code permissions. Each workspace has separate files and branch state, but commands still run on your Mac with your user permissions unless you configure stricter controls. See [Security and permissions](/docs/reference/security-and-permissions). Files to copy runs for local Mac workspaces. If a workflow must also work in cloud workspaces, put required commands in `scripts.setup` and use [`CONDUCTOR_IS_LOCAL`](/docs/reference/environment-variables) for local-only steps. If you want to stay entirely in Claude Code's native surfaces, use Claude Code's `--worktree` workflow. Use Conductor when you want parallel Claude Code sessions plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the lower-level Git model behind this workflow, see [Run Claude Code with Git worktrees](/docs/guides/git-worktrees/run-claude-code-with-git-worktrees). If you want the same workflow with OpenAI's agent, see [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions). --- title: "Run multiple Codex sessions in parallel" url: "/docs/guides/parallel-agents/run-multiple-codex-sessions" description: "Use Conductor workspaces to run several Codex tasks at once with separate branches, files, terminals, and review state" --- # Run multiple Codex sessions in parallel Use this guide when you want several Codex tasks moving at the same time without one task taking over another task's checkout. In Conductor, the unit of independent Codex work is a workspace. Create one workspace for each task that should have its own branch, working tree, setup context, terminal, diff, and pull request path. Codex also has native surfaces for local terminal work and app worktrees. Use Conductor when you want parallel Codex sessions plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the decision model, see [Parallel agents](/docs/concepts/parallel-agents). For upstream Codex behavior, see the official [Codex CLI docs](https://developers.openai.com/codex/cli) and [Codex app worktrees docs](https://developers.openai.com/codex/app/worktrees). ## Choose the unit of parallel work [#choose-the-unit-of-parallel-work] Before you start more sessions, decide whether the work needs isolation or shared state. Use separate workspaces when each Codex task should become its own branch, review, or pull request. Use multiple chats in one workspace when the tasks need to share the same branch and current code state, such as one Codex session implementing while another reviews the same diff. This choice matters more than the number of sessions. Parallel agents help when the tasks are independent enough to review separately. ## Run several Codex tasks [#run-several-codex-tasks] ### Prepare the repository once [#prepare-the-repository-once] Add the repository to Conductor and make sure a new workspace can run the project. Use [Files to copy](/docs/reference/files-to-copy) for static gitignored files such as `.env.local`. Use a [setup script](/docs/reference/scripts#setup-scripts) for commands that install dependencies, generate files, create symlinks, initialize local databases, or prepare other per-workspace resources. Use a [run script](/docs/reference/scripts#run-scripts) for commands you want to start from the Run button. ### Create one workspace per independent Codex task [#create-one-workspace-per-independent-codex-task] Create a workspace with Command + Shift + N or the `...` button next to `New workspace`. Start from a GitHub issue, Linear issue, pull request, branch, or a new task. Conductor creates a separate git worktree and branch, then attaches the Codex chat, terminal, diff, and review state to that workspace. ### Start Codex in each workspace [#start-codex-in-each-workspace] Open the workspace and choose Codex for the chat. Give each Codex session a scoped prompt: what to change, what not to change, how to verify it, and when to stop for review. Repeat this for each independent task. ### Run and test each workspace separately [#run-and-test-each-workspace-separately] Use the Run button or terminal from the workspace that owns the change. Setup and run scripts execute from the workspace directory. If several workspaces need local servers at once, use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) so each workspace gets a separate port range. If your project cannot run cleanly from workspace directories, use [Spotlight testing](/docs/reference/scripts/spotlight-testing). ### Review and merge workspace by workspace [#review-and-merge-workspace-by-workspace] Open the Diff Viewer with Command + Shift + D and inspect one workspace at a time. Use the [Checks tab](/docs/reference/checks) to track git status, CI, deployments, comments, and todos. Merge and archive the workspaces that are ready; keep revising or archive the ones that are not worth shipping. ## Keep the sessions coordinated [#keep-the-sessions-coordinated] * Give each Codex session a task that can finish independently. * Avoid assigning two workspaces the same file-heavy refactor unless you expect merge conflicts. * Keep durable project context in `AGENTS.md`, repository instructions, or the workspace `.context` directory. * Use one workspace when the Codex sessions need to collaborate on the same in-progress branch. ## Caveats [#caveats] Conductor runs Codex through the Codex setup available to Conductor. Parallel work can still be limited by your OpenAI account, subscription, model access, local resources, and configured approvals. Each workspace has separate files and branch state, but commands still run on your Mac with your user permissions unless you configure stricter controls. See [Security and permissions](/docs/reference/security-and-permissions). Files to copy runs for local Mac workspaces. If a workflow must also work in cloud workspaces, put required commands in `scripts.setup` and use [`CONDUCTOR_IS_LOCAL`](/docs/reference/environment-variables) for local-only steps. If you want to stay entirely in Codex's native app surface, use Codex app worktrees. Use Conductor when you want parallel Codex sessions plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the lower-level Git model behind this workflow, see [Run Codex with Git worktrees](/docs/guides/git-worktrees/run-codex-with-git-worktrees). If you want the same workflow with Anthropic's agent, see [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions). --- title: "Run multiple Cursor sessions in parallel" url: "/docs/guides/parallel-agents/run-multiple-cursor-sessions" description: "Use Conductor workspaces to run several Cursor tasks at once with separate branches, files, terminals, and review state" --- # Run multiple Cursor sessions in parallel Use this guide when you want several Cursor tasks moving at the same time without one task taking over another task's checkout. In Conductor, the unit of independent Cursor work is a workspace. Create one workspace for each task that should have its own branch, working tree, setup context, terminal, diff, and pull request path. Conductor supports Cursor's Composer 2.5 for Cursor sessions, so Composer 2.5 tasks can run in the same workspace model as Claude Code and Codex tasks. Cursor also has native IDE and background-agent workflows. Use Conductor when you want parallel Cursor sessions plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the decision model, see [Parallel agents](/docs/concepts/parallel-agents). ## Before you start [#before-you-start] Cursor sessions, including Composer 2.5, need a Cursor API key. Add it in `Settings` -> `Harnesses` -> `Cursor`, or set `CURSOR_API_KEY` in Conductor's environment settings. You also need a repository that can run from a workspace directory. Use [Files to copy](/docs/reference/files-to-copy) for static gitignored files such as `.env.local`. Use a [setup script](/docs/reference/scripts#setup-scripts) for commands that install dependencies, generate files, create symlinks, initialize local databases, or prepare other per-workspace resources. ## Choose the unit of parallel work [#choose-the-unit-of-parallel-work] Before you start more sessions, decide whether the work needs isolation or shared state. Use separate workspaces when each Cursor task should become its own branch, review, or pull request. Use multiple chats in one workspace when the tasks need to share the same branch and current code state, such as one Cursor session implementing while another reviews the same diff. This choice matters more than the number of sessions. Parallel agents help when the tasks are independent enough to review separately. ## Run several Cursor tasks [#run-several-cursor-tasks] ### Create one workspace per independent Cursor task [#create-one-workspace-per-independent-cursor-task] Create a workspace with Command + Shift + N or the `...` button next to `New workspace`. Start from a GitHub issue, Linear issue, pull request, branch, or a new task. Conductor creates a separate git worktree and branch, then attaches the Cursor chat, terminal, diff, and review state to that workspace. ### Start Cursor in each workspace [#start-cursor-in-each-workspace] Open the workspace and choose Cursor for the chat. Use Composer 2.5 when you want Cursor's Composer model in a Conductor workspace. Give each Cursor session a scoped prompt: what to change, what not to change, how to verify it, and when to stop for review. Repeat this for each independent task. ### Run and test each workspace separately [#run-and-test-each-workspace-separately] Use the Run button or terminal from the workspace that owns the change. Setup and run scripts execute from the workspace directory. If several workspaces need local servers at once, use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) so each workspace gets a separate port range. If your project cannot run cleanly from workspace directories, use [Spotlight testing](/docs/reference/scripts/spotlight-testing). ### Open the workspace in Cursor when useful [#open-the-workspace-in-cursor-when-useful] If you want Cursor's editor surface for manual editing, click `Open In` or press Command + O and choose Cursor. Opening the workspace in Cursor does not replace the Conductor workspace. Conductor still owns the branch, terminal, diff, checks, pull request, and archive flow. ### Review and merge workspace by workspace [#review-and-merge-workspace-by-workspace] Open the Diff Viewer with Command + Shift + D and inspect one workspace at a time. Use the [Checks tab](/docs/reference/checks) to track git status, CI, deployments, comments, and todos. Merge and archive the workspaces that are ready; keep revising or archive the ones that are not worth shipping. ## Keep the sessions coordinated [#keep-the-sessions-coordinated] * Give each Cursor session a task that can finish independently. * Avoid assigning two workspaces the same file-heavy refactor unless you expect merge conflicts. * Keep durable project context in `AGENTS.md`, `CLAUDE.md`, repository instructions, or the workspace `.context` directory. * Use one workspace when the Cursor sessions need to collaborate on the same in-progress branch. ## Caveats [#caveats] Conductor runs Cursor through your Cursor API key. Parallel work can still be limited by your Cursor account, plan, API limits, local resources, and provider behavior. Each workspace has separate files and branch state, but commands still run on your Mac with your user permissions unless you configure stricter controls. See [Security and permissions](/docs/reference/security-and-permissions). Files to copy runs for local Mac workspaces. If a workflow must also work in cloud workspaces, put required commands in `scripts.setup` and use [`CONDUCTOR_IS_LOCAL`](/docs/reference/environment-variables) for local-only steps. If you want to stay entirely in Cursor's native IDE or background-agent surfaces, use Cursor directly. Use Conductor when you want parallel Cursor sessions plus Conductor's workspace sidebar, setup scripts, run scripts, diff review, checks, and pull request flow. For the same workflow with Anthropic's agent, see [Run multiple Claude Code sessions in parallel](/docs/guides/parallel-agents/run-multiple-claude-code-sessions). For the same workflow with OpenAI's agent, see [Run multiple Codex sessions in parallel](/docs/guides/parallel-agents/run-multiple-codex-sessions). --- title: "Linking multiple directories" url: "/docs/guides/repositories/linking-multiple-directories" description: "Let one workspace read and edit code across related repositories" --- # Linking multiple directories Conductor supports linking workspaces from multiple directories so one agent can read and edit code across related repositories. This is useful when a change spans a frontend, backend, shared package, or other service that lives outside the current workspace directory. ## /add-dir [#add-dir] To link multiple directories together in Conductor, we recommend: 1. Add each directory to Conductor 2. Create a workspace for each directory 3. In one workspace, enter `/add-dir` and select the other workspaces you'd like to link together. Now, agents in this workspace will be able to access files and code from the other linked workspaces. ## Running microservices at once [#running-microservices-at-once] To run microservices from different repositories at once, create a [run script](/docs/reference/scripts) for each repository. --- title: "Work in monorepos" url: "/docs/guides/repositories/monorepos" description: "Control which directories agents can see in a monorepo workspace" --- # Work in monorepos Conductor supports monorepos out of the box. ## Adding a monorepo [#adding-a-monorepo] Adding a monorepo to Conductor is the same as [adding any other repository](/docs/first-workspace). When you add a monorepo to Conductor, workspaces are created at the repository's root level. That means agents have access to all packages and services in your monorepo by default. ## Working with specific directories [#working-with-specific-directories] Frequently, you might want your agents to only work on a few directories in your monorepo. If you have multiple directories with similar file names, agents can get confused when grep'ing or glob'ing. When you create a workspace for your monorepo, you can select which working directories will be visible in the workspace. Any directories not selected will be hidden in the workspace using `git sparse checkout` ([Git sparse checkout docs](https://git-scm.com/docs/git-sparse-checkout)). You can also add or remove directories from the workspace at any time by clicking "Select working directories" in the git panel. ## Running microservices at once [#running-microservices-at-once] To run microservices at once in a workspace, create a [run script](/docs/reference/scripts) that launches *all* of the services you need. ## Using Git Submodules [#using-git-submodules] If your monorepo uses git submodules, we recommend putting `git submodule update --init --recursive` in your [setup script](/docs/reference/scripts). This will automatically initialize and clone all submodules on workspace creation. --- title: "Claude Code" url: "/docs/reference/harnesses/claude-code" description: "Details for running Claude Code inside Conductor" --- # Claude Code Claude Code is Anthropic's coding harness for interacting with Claude models. Conductor comes with Claude Code preinstalled and allows you to use an Anthropic API key or existing subscription from within the app. ## Setup notes [#setup-notes] Conductor can use the bundled Claude Code binary or a configured system Claude Code binary. Claude Code auth status appears in `Settings` -> `Harnesses`. Claude Code can authenticate through: * a Claude Pro or Max subscription connected to Claude Code * Claude Console or Anthropic API billing * supported third-party or cloud providers configured through environment variables Provider environment variables can be configured in `Settings` -> `Environment`. For setup examples, see [Configure model providers: Claude Code](/docs/guides/providers#claude-code). ## Auth path [#auth-path] Claude Code can use a subscription path or an API/provider path. If `ANTHROPIC_API_KEY` is set in Conductor or in the shell environment that launches Conductor, Claude Code may use that API key instead of Claude subscription usage. That can result in API charges. Claude Code's `/status` command reports the active account and remaining allocation when available. --- title: "Codex" url: "/docs/reference/harnesses/codex" description: "Details for running OpenAI Codex inside Conductor" --- # Codex Codex is OpenAI's coding harness for interacting with GPT-series models. Conductor comes with Codex preinstalled and allows you to use an OpenAI API key or existing subscription. ## Setup notes [#setup-notes] Conductor can use the bundled Codex binary or a configured system Codex binary. Codex auth can come from Codex CLI sign-in outside Conductor or from API-key based access. For setup examples, see [Configure model providers: Codex](/docs/guides/providers#codex). ## Model access [#model-access] The models visible in Conductor depend on your Codex setup, account, subscription, API access, and model availability when you start the session. --- title: "Cursor" url: "/docs/reference/harnesses/cursor" description: "Details for running the Cursor Agent harness inside Conductor" --- # Cursor Cursor Agent is Cursor's coding harness. Conductor runs Cursor sessions through the Cursor API with the Composer model exposed by Cursor. ## Setup notes [#setup-notes] Cursor Agent sessions use the Cursor API and need a Cursor API key. The key can be added in `Settings` -> `Harnesses` -> `Cursor`, or set as `CURSOR_API_KEY` in Conductor's environment settings. There is no Cursor executable path to configure in Conductor settings. For a setup walkthrough, see [Configure model providers: Cursor](/docs/guides/providers#cursor). Cursor's editor surface remains available through `Open In` or Command + O. Opening the workspace in Cursor does not replace the Conductor workspace. ## MCP [#mcp] Cursor Composer supports MCP through Cursor's own MCP configuration. Use `~/.cursor/mcp.json` for user-level servers or `.cursor/mcp.json` in the repository root for project-level servers. When you open a Conductor workspace in Cursor, Cursor reads project-level MCP config from that workspace checkout. Conductor-hosted Cursor sessions do not currently surface Cursor MCP server status in Conductor's MCP status UI. For the shared reference, see [MCP](/docs/reference/mcp#add-a-cursor-composer-mcp-server). For a setup flow, see [Set up MCP servers](/docs/guides/configure-mcp-servers#add-the-server-for-cursor-composer). --- title: "Overview" url: "/docs/reference/harnesses" description: "Compare the harnesses Conductor can run and where each one is configured" --- # Overview Conductor can run Claude Code, Codex, Cursor, and OpenCode sessions in isolated workspaces. A harness is the agent runtime that writes code; Conductor is the workspace layer around it. Claude Code, Codex, and OpenCode come bundled in Conductor. You do not need to install them separately. Cursor sessions use Cursor Agent through the Cursor API. Conductor is free to use. We do not bill or resell model usage. Harness usage is billed through the provider account or API key. ## Session behavior [#session-behavior] Each chat tab uses one harness and one selected model. Separate workspaces have separate branches and pull requests. Multiple chats in one workspace share the same branch and current code state. For session controls, see [Agent modes](/docs/concepts/agent-modes). For setup examples, see [Configure model providers](/docs/guides/providers). ## Provider references [#provider-references] * [Claude Code model configuration](https://support.claude.com/en/articles/11940350-claude-code-model-configuration) * [Codex models](https://developers.openai.com/codex/models) * [Cursor API docs](https://cursor.com/docs/api) * [OpenCode docs](https://opencode.ai/docs/) --- title: "OpenCode" url: "/docs/reference/harnesses/opencode" description: "Details for running the OpenCode harness inside Conductor" --- # OpenCode OpenCode is an open source AI coding harness. It supports many LLM providers, including OpenRouter, Baseten, Cerebras, and Vercel AI Gateway. These providers give OpenCode access to open-source and frontier models. ## Setup notes [#setup-notes] Conductor includes a managed OpenCode executable. To use your own OpenCode install instead, set a custom executable path in OpenCode settings. `Settings` -> `Harnesses` -> `OpenCode` shows provider status, provider API keys, visible models, and the custom OpenCode executable path. Conductor can use provider keys from: * OpenCode provider API keys saved in Conductor, including keys for providers such as OpenRouter, Baseten, Cerebras, and Vercel AI Gateway * local environment variables detected from your shell or Conductor environment settings * OpenCode provider configuration outside Conductor See the [OpenCode provider](https://opencode.ai/docs/providers/) docs for providers or setup details that Conductor does not surface directly. For a setup walkthrough, see [Configure model providers: OpenCode](/docs/guides/providers#opencode). ## Model access [#model-access] Conductor asks OpenCode for the models available to your provider configuration. If you are not seeing models you expect: start by checking your executable, provider credentials, and OpenCode config. OpenCode model IDs are provider-qualified, such as `anthropic/claude-sonnet-4-5` or `openai/gpt-5.1`. Conductor labels those as provider/model choices in the model picker. --- title: "Scripts" url: "/docs/reference/scripts" description: "Reference for setup, run, and archive scripts" --- # Scripts Project scripts give every Conductor workspace the same project workflow: prepare the workspace, run the project, and clean up after archive. Configure project scripts in Conductor or in a settings file: * In the app, open `Settings`, select the project, and edit setup, run, archive, or Spotlight settings. * In the repository, add `[scripts]` to `.conductor/settings.toml` when the same workflow should be shared with teammates. ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run = "pnpm dev --port $CONDUCTOR_PORT" archive = "./script/workspace-archive.sh" run_mode = "concurrent" ``` Commit `.conductor/settings.toml` when teammates should use the same project workflow. For settings file locations and precedence, see [User and project settings](/docs/reference/settings/user-project). For the full key list, see [Settings reference](/docs/reference/settings/reference). ## Script types [#script-types] | Script | Setting | When it runs | Use it for | | ----------- | ------------------ | ------------------------------------- | ------------------------------------------------------------ | | Setup | `scripts.setup` | After Conductor creates a workspace | Installing dependencies, generating files, creating symlinks | | Run scripts | `scripts.run` | When you click the Run button | Starting apps, servers, workers, watchers, or test loops | | Archive | `scripts.archive` | Before Conductor archives a workspace | Cleaning up resources outside the workspace directory | | Run mode | `scripts.run_mode` | When a run script starts | Choosing whether run scripts can overlap | Setup, run, and archive scripts run from the workspace directory, available as [`CONDUCTOR_WORKSPACE_PATH`](/docs/reference/environment-variables). Use [`CONDUCTOR_ROOT_PATH`](/docs/reference/environment-variables) when a script needs a file from the repository root. ## Setup scripts [#setup-scripts] The setup script prepares a new workspace after Git checks out the tracked repository files. Use it when the workspace needs commands, generated files, symlinks, or workspace-specific resources. ```toml title=".conductor/settings.toml" [scripts] setup = """ pnpm install cp "$CONDUCTOR_ROOT_PATH/.env" .env pnpm run build """ ``` If all you need is to copy gitignored local files such as `.env.local`, use [Files to copy](/docs/reference/files-to-copy) instead. If your app stores local state, make the setup script create resources for each workspace instead of sharing one development instance. Use [`CONDUCTOR_WORKSPACE_NAME`](/docs/reference/environment-variables) to name generated resources such as app identifiers, local data directories, application support folders, or development icons. Use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) when each workspace needs its own server port. Conductor creates new workspaces from the repository base branch, such as `origin/main`, and fetches from `origin` first. That fetch updates Conductor's remote view, but it does not move the branch checked out in the repository root directory. If you want the root checkout branch to stay current too, add a fast-forward pull to your setup script: ```bash git -C "$CONDUCTOR_ROOT_PATH" fetch --prune origin && git -C "$CONDUCTOR_ROOT_PATH" pull --ff-only || true ``` The `|| true` keeps setup from failing when the branch cannot fast-forward, such as when the root checkout has local commits. The [advanced setup script walkthrough](https://gist.github.com/cbh123/10b4e522252eb9d900872921fbeb736d) shows the Conductor setup script creating workspace-specific development resources for the desktop app. ## Run scripts [#run-scripts] Run scripts start your app, server, test watcher, worker, or another long-running command from the active workspace. A project can define one or more run scripts. Conductor shows them in the Run button menu. ```toml title=".conductor/settings.toml" [scripts] run = "pnpm dev --port $CONDUCTOR_PORT" run_mode = "concurrent" ``` Use [`CONDUCTOR_PORT`](/docs/reference/environment-variables) when a run script starts a local server. Conductor allocates ten ports to each workspace: `CONDUCTOR_PORT` through `CONDUCTOR_PORT+9`. Run scripts use non-interactive shells. If a tool works in your normal terminal but fails in a run script, see [Shell configuration](/docs/reference/shells). ### Multiple run scripts [#multiple-run-scripts] Add one named run script under `scripts.run` for each command. Conductor uses the run script ID to match the same script across user, project, and local project settings. ```toml title=".conductor/settings.toml" [scripts] run_mode = "concurrent" [scripts.run.web] available_in = [ "local", "cloud" ] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" [scripts.run.worker] available_in = [ "local", "cloud" ] command = "pnpm worker:dev" icon = "server" [scripts.run.test] available_in = [ "local", "cloud" ] command = "pnpm test:watch" icon = "test-tube" ``` Choose an ID that describes the command, such as `web`, `worker`, or `test`. Use letters, numbers, spaces, or hyphens. Conductor normalizes repeated spaces and treats hyphens as spaces for display. ### Run script fields [#run-script-fields] | Field | Type | Description | | -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `command` | string | Shell command to run from the active workspace. Required for a runnable script. | | `args` | array of strings | Optional arguments passed with the command. | | `options.cwd` | string | Optional working directory relative to the workspace. | | `default` | boolean | Marks the script Conductor should select by default when more than one script exists. | | `icon` | string | Lucide icon name shown with the script. Invalid icon names fall back to `play`. | | `hide` | boolean | Hides the script from the Run button. Set it in `.conductor/settings.local.toml` to hide a shared script on your machine only. | | `available_in` | `"local"`, `"cloud"`, or an array of both | Limits where the script appears. Omit it when the script should be available locally and in cloud workspaces. | ### Run script icons [#run-script-icons] `icon` accepts a [Lucide icon](https://lucide.dev/icons/) name written in lowercase kebab case. Common choices for run scripts include `play`, `terminal`, `square-terminal`, `server`, `globe`, `database`, `monitor`, `rocket`, `code`, `braces`, `package`, `test-tube`, `bug`, `wrench`, `settings`, `cloud`, `folder`, `file-code`, and `flame`. ### Legacy single run script [#legacy-single-run-script] Older settings files may use `scripts.run` for a single run script: ```toml title=".conductor/settings.toml" [scripts] run = "pnpm dev --port $CONDUCTOR_PORT" run_mode = "concurrent" ``` Conductor still reads `scripts.run` as a string for a single run script. New settings that need more than one command should define named run scripts under `scripts.run`. ### Where changes take effect [#where-changes-take-effect] For where run script changes apply, when to use local overrides, and how shared project settings reach teammates, see [User and project settings](/docs/reference/settings/user-project#when-file-changes-apply). ## Run mode [#run-mode] `scripts.run_mode` controls whether multiple run scripts can run at once. | Mode | Behavior | | --------------- | ------------------------------------------------------------ | | `concurrent` | Run scripts can run in multiple workspaces at the same time. | | `nonconcurrent` | Starting a run script stops any other run script first. | Use `nonconcurrent` when your project depends on one fixed port, one local database, one Docker stack, or another shared resource that multiple workspaces cannot use at the same time. If your run script starts multiple processes, keep them in the same process group so Conductor can clean them up together. Use [concurrently](https://www.npmjs.com/package/concurrently) or a similar tool instead of backgrounding commands with `&`. ```toml title=".conductor/settings.toml" [scripts.run.dev] command = "concurrently \"npm run server\" \"npm run worker\"" ``` Avoid backgrounding processes: ```toml title=".conductor/settings.toml" [scripts.run.dev] command = "npm run server & npm run worker" ``` When Conductor stops that script, the backgrounded server can keep running and hold ports, memory, or other resources. ## Archive scripts [#archive-scripts] The archive script runs before Conductor archives a workspace. Use it to clean up project-specific resources outside the workspace directory. ```toml title=".conductor/settings.toml" [scripts] archive = "./script/workspace-archive.sh" ``` For example, a desktop app might remove a workspace-specific application support directory: ```bash rm -rf "$HOME/Library/Application Support/com.example.app.dev.$CONDUCTOR_WORKSPACE_NAME" ``` ## Process handling [#process-handling] When Conductor stops a script process, it sends `SIGHUP`, waits up to 200ms, then sends `SIGKILL` if the process is still running. ## Related references [#related-references] * [Files to copy](/docs/reference/files-to-copy) for static gitignored files that should appear in each workspace. * [Conductor variables](/docs/reference/environment-variables) for workspace paths and allocated ports. * [Shell configuration](/docs/reference/shells) for non-interactive shell behavior. * [Spotlight testing](/docs/reference/scripts/spotlight-testing) for projects that need to run from the repository root. * [Share project settings](/docs/reference/scripts/share-with-teammates) for committing `.conductor/settings.toml` with teammates. --- title: "Run script reference" url: "/docs/reference/scripts/run" description: "Run scripts are covered in the project scripts reference" --- # Run script reference Run scripts are now covered in [Project scripts](/docs/reference/scripts#run-scripts). Use a run script when the Run button should start your app, server, test watcher, worker, or another long-running command from the active workspace. Open `Settings`, select the project, and edit run scripts, or use `.conductor/settings.local.toml` for local file-backed changes. For projects that cannot run cleanly from a workspace directory, see [Spotlight testing](/docs/reference/scripts/spotlight-testing). --- title: "Setup script reference" url: "/docs/reference/scripts/setup" description: "Setup scripts are covered in the project scripts reference" --- # Setup script reference Setup scripts are now covered in [Project scripts](/docs/reference/scripts#setup-scripts). Use a setup script when a new workspace needs commands, generated files, symlinks, or workspace-specific resources. Configure it with `scripts.setup` in `.conductor/settings.toml`, or open `Settings`, select the project, and edit the setup script. For static gitignored files such as `.env.local`, use [Files to copy](/docs/reference/files-to-copy) instead. --- title: "Share repository settings with teammates" url: "/docs/reference/scripts/share-with-teammates" description: "Commit .conductor/settings.toml so a repository can share Conductor scripts and settings" --- # Share repository settings with teammates By default, Repository Settings apply only on your machine. To share scripts and other repository settings with teammates, commit a `.conductor/settings.toml` file in the repository. Shared repository settings are useful for: * Setup, run, and archive scripts. * Run script mode. * Enterprise data privacy. * Spotlight testing. * Repository action prompts. * Provider and Git behavior that should apply to the whole team. ## Step 1: Create the file [#step-1-create-the-file] Create `.conductor/settings.toml` at the repository root. ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Adjust the commands for your project. Setup, run, and archive scripts run from each workspace directory, not from the original repository checkout. ## Step 2: Commit it [#step-2-commit-it] Commit `.conductor/settings.toml` to the repository: ```bash git add .conductor/settings.toml git commit -m "Add Conductor repository settings" git push ``` If you create `.conductor/settings.local.toml` for per-machine repository settings, add it to `.gitignore` from the repository root: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` ## Step 3: Pull it in other workspaces [#step-3-pull-it-in-other-workspaces] After teammates pull the commit, Conductor reads the shared settings for that repository. If a teammate has the same setting configured locally in `.conductor/settings.local.toml`, their local value wins. ## Example: scripts and privacy [#example-scripts-and-privacy] ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" enterprise_data_privacy = true [scripts] setup = "pnpm install" archive = "./script/workspace-archive.sh" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Use `run_mode = "nonconcurrent"` when the project depends on a fixed port, one local database, one Docker stack, or another shared resource that multiple workspaces cannot use at the same time. ## Legacy conductor.json [#legacy-conductorjson] Older repositories may still have `conductor.json` at the repository root. New shared settings should use `.conductor/settings.toml`. Once `.conductor/settings.toml` exists for a repository, Conductor ignores repo-level `conductor.json`. For complete copyable files, see [Sample settings configurations](/docs/reference/settings/example). For precedence and file locations, see [User and project settings](/docs/reference/settings/user-project). For supported keys, see [Settings reference](/docs/reference/settings/reference). For script behavior, see [Scripts](/docs/reference/scripts). --- title: "Spotlight testing" url: "/docs/reference/scripts/spotlight-testing" description: "Test one workspace from the repository root" --- # Spotlight testing Spotlight testing syncs one workspace back to your repository root so you can test from the root directory instead of the workspace directory. Use Spotlight testing when your project needs the root checkout, a fixed local resource, or one heavy local stack that should stay running while you switch between workspace changes. ## Spotlight testing or run scripts [#spotlight-testing-or-run-scripts] Use normal [run scripts](/docs/reference/scripts#run-scripts) when each workspace can run its own copy of the project. Run scripts are the default testing path because each workspace gets its own process, paths, and allocated ports. Use Spotlight testing when the project needs to run from the repository root, or when running one full stack per workspace would be too expensive. Spotlight testing is a good fit for: * Directory-dependent applications that assume they run from the repository root. * Projects with expensive initial builds that can reuse build artifacts in the repository root. * Apps that depend on a fixed port, one local database, or another single shared local resource. * Docker-heavy or microservice projects where running one full stack per workspace would consume too much CPU, memory, disk, or battery. * Apps that take a long time to start but can hot reload quickly once the root process is running. * Dev scripts with hard-coded local values that are difficult to make workspace-specific. Spotlight testing only tests one workspace at a time. If your project only needs to prevent multiple run scripts from sharing one port or database, consider `nonconcurrent` [run mode](/docs/reference/scripts#run-mode) first. Cloud workspaces are another option when local resource usage is the main problem. Spotlight is most useful when you want to keep agents working in local workspaces while only one local application stack runs from the repository root. ## Configure Spotlight testing [#configure-spotlight-testing] You can configure Spotlight testing in Conductor or in a settings file: * In the app, open `Settings`, select the project, and turn on `Use spotlight testing`. * In the repository, add `spotlight_testing` to `.conductor/settings.toml` when the same testing workflow should be shared with teammates. Use this repository configuration when every teammate should test this project from the repository root: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" spotlight_testing = true ``` Commit `.conductor/settings.toml` when every teammate should use Spotlight testing for the repository. For settings file locations and precedence, see [User and project settings](/docs/reference/settings/user-project). Spotlight testing only changes testing for that project. Other projects can keep using normal run scripts and workspace isolation. ## Spotlight a workspace [#spotlight-a-workspace] Before you start Spotlight, run your application from the repository root in Conductor. For example, start the Docker stack, dev server, or other long-running process from the root checkout. Then click the Spotlight button from the workspace you want to test. Conductor copies that workspace's tracked changes back to the repository root so the root process can run them. When you turn Spotlight mode off, Conductor restores the original repository root state. While Spotlight is on: * The project runs from the repository root, not the workspace directory. * Tracked workspace changes are swapped into the root as the workspace changes. * Switching Spotlight to another workspace replaces the root with that workspace's tracked changes. * Existing root build caches and long-running processes can keep hot reloading instead of starting from scratch. You can keep creating branches, chatting with agents, and preparing pull requests from separate workspaces. Spotlight only changes which workspace's tracked changes are active in the root process. ## How it works [#how-it-works] Spotlight testing watches your workspace for changes. When files change, Conductor creates a [checkpoint](/docs/reference/checkpoints) commit of your workspace and checks it out in the repository root. Only files tracked in git are copied back to the repository root. Build artifacts such as `node_modules` are not copied. Spotlight testing is a one-way sync. Changes in the repository root are not copied back to your workspace. Edit files in the workspace so Conductor can sync them to the repository root. ## Troubleshooting [#troubleshooting] If Spotlight cannot start, check whether the workspace or repository root has a rebase or merge in progress. Finish the operation with `git rebase --continue` or `git merge --continue`, or cancel it with `git rebase --abort` or `git merge --abort`. Run the command in the directory that has the pending operation. --- title: "Sample settings configurations" url: "/docs/reference/settings/example" description: "Example repository settings files for Conductor" --- # Sample settings configurations Start with the smallest `.conductor/settings.toml` file that makes your project runnable. Add sections only when the project needs them. Commit `.conductor/settings.toml` when the settings should travel with the project. Add `.conductor/settings.local.toml` to `.gitignore` for project overrides. ## Minimal script-only example [#minimal-script-only-example] Most repositories only need scripts at first: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm install" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` Use this when: * `pnpm install` prepares a fresh workspace. * `pnpm dev` starts the app or server. * The project can run multiple workspaces at once by using `CONDUCTOR_PORT`. Use `run_mode = "nonconcurrent"` instead when the project depends on one fixed port, one local database, one Docker stack, or another shared resource. ## More examples [#more-examples] Use this as a reference for the sections a larger project might configure. Remove anything your project does not need. ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" # Disable Conductor features that require external AI providers. enterprise_data_privacy = false # Copy these gitignored files into each new local workspace when # .worktreeinclude is not present. file_include_globs = ".env*\nconfig/*.local.json\n" [scripts] # Runs after Conductor creates a workspace. setup = "pnpm install" # Runs before Conductor archives a workspace. archive = "./script/workspace-archive.sh" # Use "nonconcurrent" if the project depends on a fixed port, one local # database, one Docker stack, or another shared resource. run_mode = "concurrent" [scripts.run.dev] # Runs from the Run button. Use CONDUCTOR_PORT so multiple workspaces # can run their own dev servers. command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" [scripts.run.test] command = "pnpm test --watch" icon = "test-tube" [environment_variables] # Top-level variables apply to local and cloud agents. ANTHROPIC_BASE_URL = "https://api.example.com" [environment_variables.local] # Local-only variables apply when agents run on your Mac. LOCAL_AGENT_MODE = "1" [environment_variables.cloud] # Cloud-only variables apply when agents run in cloud workspaces. OPENAI_BASE_URL = "https://openai.example.com" [prompts] general = "Prefer small, reviewable changes and run the narrowest relevant tests." code_review = "Focus on correctness, behavior changes, and missing tests." create_pr = "Write a concise PR description with test results." fix_errors = "Explain the likely cause before changing code." resolve_merge_conflicts = "Preserve user changes unless the conflict proves they are obsolete." rename_branch = "Use a short kebab-case branch name." [git] archive_on_merge = true delete_branch_on_archive = false worktree_push_auto_setup_remote = true branch_prefix_type = "custom" branch_prefix = "agent" ``` Use `.conductor/settings.local.toml` when your machine needs a different command or provider value. Add it to `.gitignore` from the repository root: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` ```toml title=".conductor/settings.local.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --host 127.0.0.1 --port $CONDUCTOR_PORT" default = true icon = "play" [environment_variables] ANTHROPIC_BASE_URL = "http://127.0.0.1:4000" ``` The local file overrides matching values from `.conductor/settings.toml` on your machine only. ## What to add next [#what-to-add-next] Add sections only when you need them: * Add `archive` when archiving a workspace should clean up project-specific resources. * Add `file_include_globs` when you need Conductor to copy gitignored files and you are not using `.worktreeinclude`. * Add `environment_variables` when agents need repository-specific variables that should not come from the normal shell environment. * Add `prompts` when the repository needs custom agent instructions. * Add `git` settings when the repository should override Conductor's Git defaults. For the full settings model, see [User and project settings](/docs/reference/settings/user-project). For supported keys, see [Settings reference](/docs/reference/settings/reference). --- title: "Settings" url: "/docs/reference/settings" description: "How Conductor settings configure workspaces, scripts, agents, and projects" --- # Settings Settings control how Conductor prepares workspaces, runs agents, starts projects, and configures providers. Use the Settings screen or `.conductor/settings.local.toml` for project changes that should apply on your Mac. Use `.conductor/settings.toml` only for shared project defaults; Conductor reflects those changes after they are merged to the repository's default branch, usually `main`. For a step-by-step setup flow, see [Configure settings](/docs/guides/configure-settings). ## Quickstart: project scripts [#quickstart-project-scripts] Create `.conductor/settings.toml` at the repository root when the setup and run scripts should be shared with the team: ```text your-repo/ ├── .conductor/ │ └── settings.toml ├── package.json └── ... ``` ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] setup = "pnpm i" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` This example is for a Node project. The setup script installs dependencies for the new workspace. Use the commands your project already uses. Use `CONDUCTOR_PORT` in run scripts so multiple Conductor workspaces can run dev servers at the same time. Commit the shared project settings: ```bash git add .conductor/settings.toml git commit -m "Add Conductor settings" ``` ## How settings are layered [#how-settings-are-layered] Conductor layers settings like VS Code: user settings apply across repositories, project settings apply to one repository, and local project settings override that repository on one machine. If two layers set the same value, Conductor uses the highest layer that applies. Settings precedence, highest first 1 Managed settings Organization-controlled values. Most users do not edit this layer. 2 Project overrides Your overrides for one project in{" "} .conductor/settings.local.toml. 3 Repository shared settings Project defaults committed in{" "} .conductor/settings.toml. 4 User shared settings Personal defaults in \~/.conductor/settings.toml . 5 Built-in defaults Conductor's fallback behavior when no settings file defines the value. ## Choose the right settings file [#choose-the-right-settings-file] | Scope | File | Use it for | | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | | User settings | `~/.conductor/settings.toml` | Your defaults across all repositories | | Project overrides | `/.conductor/settings.local.toml` | Your machine's override for one project | | Project settings | `/.conductor/settings.toml` | Shared setup, run, archive, prompts, environment, provider, and Git behavior after the change is merged | | Managed settings | `~/.conductor/settings.managed.toml` | Organization-controlled values | ## Next steps [#next-steps] * Follow [Configure settings](/docs/guides/configure-settings) for a step-by-step setup flow. * Use [User and project settings](/docs/reference/settings/user-project) for file locations, scope, and precedence. * Use [Settings reference](/docs/reference/settings/reference) for the complete key reference. * Use [Managed settings](/docs/reference/settings/managed) for organization-controlled settings. * Browse [Sample settings configurations](/docs/reference/settings/example) for copyable examples. * Migrating from legacy `conductor.json`? See [conductor.json](/docs/reference/conductor-json). --- title: "Managed settings" url: "/docs/reference/settings/managed" description: "Reference for organization-managed Conductor settings" --- # Managed settings Managed settings build on Conductor's normal [user and project settings model](/docs/reference/settings/user-project). In that model, user settings provide personal defaults, repository shared settings define project behavior, and project overrides apply to one project on one machine. Managed settings add one organization-controlled layer above that stack. They are for organizations that need to enforce selected Conductor settings on a user's Mac. Most users should configure user and project settings instead. Managed values override user and repository settings, disable the matching controls in Settings, and are used when Conductor launches agents. Managed settings are provisional. ## File location [#file-location] Write managed TOML settings to: ```text ~/.conductor/settings.managed.toml ``` Conductor still reads legacy `~/.conductor/settings.managed.json`, but TOML is the recommended format. ## Example [#example] ```toml title="~/.conductor/settings.managed.toml" "$schema" = "https://conductor.build/schemas/settings.toml.json" enterprise_data_privacy = true claude_code_executable_path = "/opt/homebrew/bin/claude" [models] default = "gpt-5.5" [environmentVariables.local] ANTHROPIC_BASE_URL = "https://api.example.com" [environmentVariables.cloud] OPENAI_BASE_URL = "https://openai.example.com" ``` ## Settings reference [#settings-reference] For the managed key list, see [Settings reference](/docs/reference/settings/reference#managed-settings). ## Precedence [#precedence] Managed settings have the highest precedence. When a managed file defines a supported setting, it overrides the normal settings stack: 1. Managed settings. 2. Project overrides. 3. Repository shared settings. 4. User shared settings. 5. Built-in defaults. For the full settings precedence model, see [User and project settings](/docs/reference/settings/user-project). --- title: "Settings reference" url: "/docs/reference/settings/reference" description: "Conductor settings keys by scope" --- # Settings reference Use this page as the key reference for Conductor settings files. For the layered settings model, file locations, and precedence rules, start with [User and project settings](/docs/reference/settings/user-project). ## Repository settings [#repository-settings] Repository settings apply to `/.conductor/settings.toml` and `/.conductor/settings.local.toml`. They support workspace and repository behavior, not every user preference. ### Scripts [#scripts] | TOML key | Type | Description | | ------------------ | ------ | ----------------------------------------------------- | | `scripts.setup` | string | Command to run when Conductor creates a workspace. | | `scripts.archive` | string | Command to run before Conductor archives a workspace. | | `scripts.run_mode` | string | `concurrent` or `nonconcurrent`. | ### Run scripts [#run-scripts] | TOML key | Type | Description | | ------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- | | `scripts.run..command` | string | Command to run from the Run button. | | `scripts.run..args` | string array | Optional arguments passed with the command. | | `scripts.run..options.cwd` | string | Optional working directory relative to the workspace. | | `scripts.run..default` | boolean | Selects this script by default when the project has many run scripts. | | `scripts.run..icon` | string | Lucide icon name shown with the script. | | `scripts.run..hide` | boolean | Hides the script from the Run button. Overridable per layer, so a local layer can hide a shared script. | | `scripts.run..available_in` | string or string array | `local`, `cloud`, or both. | | `scripts.run` | string | Legacy single run script. Use `scripts.run.` for multiple scripts. | ### Workspace behavior [#workspace-behavior] | TOML key | Type | Description | | ------------------------- | ------- | --------------------------------------------------------------------------- | | `enterprise_data_privacy` | boolean | Enables Enterprise data privacy for the repository. | | `spotlight_testing` | boolean | Uses Spotlight testing for projects that must run from the repository root. | | `file_include_globs` | string | Files to copy patterns used when `.worktreeinclude` is not present. | ### Environment variables [#environment-variables] | TOML key | Type | Description | | ----------------------------- | ----- | -------------------------------------------------------------------------- | | `environment_variables` | table | Environment variables passed to local and cloud agents in this repository. | | `environment_variables.local` | table | Environment variables passed to local agents only. | | `environment_variables.cloud` | table | Environment variables passed to cloud agents only. | ### Prompts [#prompts] | TOML key | Type | Description | | --------------------------------- | ------ | ----------------------------------------------------- | | `prompts.general` | string | Added to agent sessions for this repository. | | `prompts.code_review` | string | Custom prompt for the code review action. | | `prompts.create_pr` | string | Custom prompt for the create PR action. | | `prompts.fix_errors` | string | Custom prompt for the fix errors action. | | `prompts.resolve_merge_conflicts` | string | Custom prompt for the resolve merge conflicts action. | | `prompts.rename_branch` | string | Custom prompt for branch naming. | ### Harnesses [#harnesses] | TOML key | Type | Description | | ----------------------------- | ------ | --------------------------------------------------------------- | | `claude_code_executable_path` | string | Override the Claude Code executable path. | | `codex_executable_path` | string | Override the Codex executable path. | | `claude_provider` | string | Provider backing Claude, such as Anthropic, Bedrock, or Vertex. | | `codex_provider` | string | Provider backing Codex. | | `bedrock_region` | string | AWS Bedrock region for Claude. | | `vertex_project_id` | string | Google Vertex project ID for Claude. | | `ssh_key_path` | string | Path to the SSH private key used for cloud workspaces. | ### Git [#git] | TOML key | Type | Description | | ------------------------------------- | ------- | --------------------------------------------------------------- | | `git.delete_branch_on_archive` | boolean | Delete the workspace branch when archiving. | | `git.archive_on_merge` | boolean | Archive a workspace automatically when its pull request merges. | | `git.worktree_push_auto_setup_remote` | boolean | Automatically configure the upstream remote on first push. | | `git.branch_prefix_type` | string | How branch name prefixes are generated. | | `git.branch_prefix` | string | Custom branch name prefix. | ## User-only settings [#user-only-settings] User settings in `~/.conductor/settings.toml` support every file-backed setting. These settings are user-only and are ignored in repository settings files. | TOML key | Type | Description | | ----------------------------------------- | ------- | ------------------------------------------- | | `models.default` | string | Default model for new chats. | | `models.review` | string | Model used for code reviews. | | `models.default_fast_mode` | boolean | Enable fast mode by default for new chats. | | `models.default_plan_mode` | boolean | Start new chats in plan mode by default. | | `models.codex.default_thinking_level` | string | Default Codex thinking level for new chats. | | `models.codex.review_thinking_level` | string | Codex thinking level used for code reviews. | | `models.codex.personality` | string | Default Codex personality. | | `models.claude_code.default_effort_level` | string | Default Claude effort level for new chats. | | `models.claude_code.review_effort_level` | string | Claude effort level used for code reviews. | | `tool_approvals_enabled` | boolean | Require approval before agents run tools. | ## Managed settings [#managed-settings] Managed settings are for organizations. They live in `~/.conductor/settings.managed.toml` and override user and repository settings. | TOML key | Type | Description | | ----------------------------- | ------- | ---------------------------------------------------- | | `enterprise_data_privacy` | boolean | Enables Enterprise data privacy. | | `claude_code_executable_path` | string | Overrides the Claude Code executable path. | | `models.default` | string | Sets the default model. | | `environmentVariables.local` | table | Sets managed environment variables for local agents. | | `environmentVariables.cloud` | table | Sets managed environment variables for cloud agents. | For managed file behavior and examples, see [Managed settings](/docs/reference/settings/managed). ## Unsupported by scope [#unsupported-by-scope] | Case | Behavior | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | User-only settings in a repository file | Conductor ignores them. Put model defaults, tool approvals, and default workspace location in `~/.conductor/settings.toml`. | | Unknown keys in a repository settings file | Conductor rejects keys that are not in the repository schema. | | Unknown keys in a managed settings file | Conductor ignores unsupported managed keys and applies recognized valid keys. | ## Schema URLs [#schema-urls] | File | Schema | | --------------------------------------- | ----------------------------------------------------------- | | `~/.conductor/settings.toml` | `https://conductor.build/schemas/settings.schema.json` | | `/.conductor/settings.toml` | `https://conductor.build/schemas/settings.repo.schema.json` | | `/.conductor/settings.local.toml` | `https://conductor.build/schemas/settings.repo.schema.json` | | `~/.conductor/settings.managed.toml` | `https://conductor.build/schemas/settings.toml.json` | --- title: "User and project settings" url: "/docs/reference/settings/user-project" description: "Reference for Conductor user, project, and local project settings" --- # User and project settings User and project settings are the files most people manage directly. Use this reference when you need to choose a settings tier or understand precedence. For the complete key list, see [Settings reference](/docs/reference/settings/reference). For a step-by-step setup flow, see [Configure settings](/docs/guides/configure-settings). ## File locations [#file-locations] Most users work with these files: | Scope | File | Use it for | Commit it? | | ----------------- | --------------------------------------- | -------------------------------------------------- | ---------- | | User shared | `~/.conductor/settings.toml` | Your defaults across all repositories | No | | Project overrides | `/.conductor/settings.local.toml` | Your override for one project | No | | Repository shared | `/.conductor/settings.toml` | Team defaults after the change is merged to `main` | Yes | Organizations can also provide a managed settings file at `~/.conductor/settings.managed.toml`. Managed settings override user and project settings. See [Managed settings](/docs/reference/settings/managed) when you need organization-controlled configuration. ## Precedence [#precedence] When more than one settings layer configures the same setting, Conductor uses the first matching value in this order: 1. Managed settings. 2. Project overrides. 3. Repository shared settings. 4. User shared settings. 5. Built-in defaults. Most users will not have managed settings. When no managed file is present, project overrides are the highest layer. Example: ```toml title="~/.conductor/settings.toml" [scripts.run.dev] command = "pnpm dev" default = true icon = "play" ``` ```toml title="/.conductor/settings.toml" [scripts] run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" ``` For that repository, the Run button uses `pnpm dev --port $CONDUCTOR_PORT` because the repository shared file overrides the user shared file for repository-configurable settings. If your local file also defines the same run script, it wins for your machine: ```toml title="/.conductor/settings.local.toml" [scripts.run.dev] command = "pnpm dev:local" default = true icon = "play" ``` ## When file changes apply [#when-file-changes-apply] For most run script changes, use `Settings` > `Repo` > `Scripts` in Conductor. The UI writes the right settings layer and updates workspaces without making you reason about file propagation. Use `/.conductor/settings.local.toml` for machine-specific changes and local run script experiments. These changes are not tracked by Git and are only reflected on your machine. ## Repository shared settings [#repository-shared-settings] Use `/.conductor/settings.toml` when a repository should define shared Conductor behavior for everyone. Commit this file when the settings should travel with the project, and merge the change to the repository's default branch before expecting Conductor to reflect it as shared project settings. Common repository shared settings include setup scripts, run scripts, archive scripts, run mode, Files to copy patterns, Enterprise data privacy, action prompts, Git behavior, provider executable paths, and repository environment variables. Example: ```toml title=".conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" enterprise_data_privacy = true [scripts] setup = "pnpm install" archive = "./script/workspace-archive.sh" run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --port $CONDUCTOR_PORT" default = true icon = "play" [prompts] general = "Prefer small, reviewable changes and run the narrowest relevant tests." code_review = "Focus on correctness, behavior changes, and missing tests." ``` Use `run_mode = "nonconcurrent"` when the project depends on one fixed port, one local database, one Docker stack, or another shared resource that multiple workspaces cannot use at the same time. ## Project overrides [#project-overrides] Use `/.conductor/settings.local.toml` for settings that should apply only on your machine. Add it to `.gitignore` from the repository root: ```bash touch .gitignore grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignore ``` Project overrides are useful when your local environment differs from the project's shared setup. Example: ```toml title=".conductor/settings.local.toml" "$schema" = "https://conductor.build/schemas/settings.repo.schema.json" [scripts] run_mode = "concurrent" [scripts.run.dev] command = "pnpm dev --host 127.0.0.1 --port $CONDUCTOR_PORT" default = true icon = "play" [environment_variables] ANTHROPIC_BASE_URL = "http://127.0.0.1:4000" ``` This overrides the shared repository run script and environment variable values on your machine only. ## User settings [#user-settings] Use `~/.conductor/settings.toml` for personal defaults that should apply across repositories. User settings include every file-backed setting, including settings that repositories cannot control. Example: ```toml title="~/.conductor/settings.toml" "$schema" = "https://conductor.build/schemas/settings.schema.json" [models] default = "gpt-5.5" review = "sonnet" default_plan_mode = true [models.codex] default_thinking_level = "high" personality = "direct" [models.claude_code] default_effort_level = "normal" ``` Common user-only settings include model defaults, model reasoning defaults, tool approvals, and the default workspace location. If you put these settings in a repository file, Conductor ignores them because repositories are not allowed to set them. ## Schemas and legacy files [#schemas-and-legacy-files] Add a schema URL to a settings file for editor autocomplete and validation. Schema URLs are listed in [Settings reference](/docs/reference/settings/reference). Within one scope, Conductor reads legacy `.json` settings files first and `.toml` settings files second. If both exist, TOML wins. Conductor writes new settings files as TOML. Legacy `conductor.json` is separate from these settings files. New shared repository settings should use `.conductor/settings.toml`. For migration details, see [conductor.json](/docs/reference/conductor-json). ## Related pages [#related-pages] * [Settings quickstart](/docs/reference/settings) * [Configure settings](/docs/guides/configure-settings) * [Settings reference](/docs/reference/settings/reference) * [Managed settings](/docs/reference/settings/managed) * [Sample settings configurations](/docs/reference/settings/example) * [Share repository settings with teammates](/docs/reference/scripts/share-with-teammates) * [Scripts](/docs/reference/scripts) * [Files to copy](/docs/reference/files-to-copy)