Local coding & commands

Use Git branches, run local tests and builds, manage development servers, and configure command environments in Mac project folders.

Work in an existing codebase

Connect a local repository through Project folder before starting a Work chat. Work can read and search the code, edit files with your permission, and show repository changes. Install the project’s required tools and dependencies on your Mac before asking Work to run checks. Read and write folder access does not automatically enable commands. Local tests & builds and Development servers are separate settings for each saved folder. These commands run on the Mac and require a compatible build; Remote folder access does not grant command execution from your phone.

Choose or create a Git branch

  1. Connect the repository root — Select the repository folder in the Work composer. If it is a supported Git checkout, a branch label appears beside the folder. Open the label to see local branches and the current branch’s uncommitted change count.
  2. Switch before starting work — Search for and select a local branch, or choose Create and switch to a new branch…, enter a name, and select Create and switch. A new branch starts from the current branch.
  3. Resolve anything that prevents switching — Branch changes affect every chat using the same checkout. Finish active tasks and stop commands or servers in that folder before switching. The folder needs read and write access. Uncommitted changes are kept where Git can carry them across; conflicting edits show an error. The picker does not automatically stash or discard them.

Branch picker limits

The picker lists local branches and does not fetch remote-only branches. Linked worktrees, repositories with an external .git directory, bare repositories, and detached HEAD do not expose this picker. Use your normal Git workflow to prepare a supported checkout when needed. Switching a branch does not commit or push your work.

Enable and run local tests or builds

  1. Review command access — Open Settings → Mac app → Folder access → Manage folder access. Find the project and, under Local tests & builds, choose Allow commands…. Review and confirm the native permission prompt. Work can also request access in a chat approval card.
  2. Ask for a specific check — Tell Work which result to verify. Ask it to read the repository’s instructions and existing test scripts, then run the relevant installed check. Ordinary commands are limited to the connected project and private working areas, and network access is blocked.
  3. Read the result — Expand the command entry in the chat. Show output displays its logs; Refresh updates an active command’s output, and Previous/Next page through available output. Check the exit code and Work’s explanation. Stop command ends a running check.
Read this repository’s instructions and test scripts. Fix the problem described below, run the relevant installed tests once without watch mode, and summarize the changed files and test result. Ask for Local tests & builds access if needed. Problem: [describe the behavior, expected result, and steps to reproduce it].

Start and manage development servers

  1. Enable the separate server permission — In Manage folder access, find Development servers and choose Allow servers…. It starts off. Allowing servers also enables ordinary commands and requires read and write access. Review the prompt: servers can use the network and the project’s .env files.
  2. Describe the server you want — Ask Work to inspect the project’s startup scripts and existing listeners, reuse a suitable running server, or start the required one. Name the expected service and port if you know them. Review output and verify the app responds at its local address; Running alone does not establish that startup succeeded.
  3. Inspect or stop the server — Expand the server’s command entry for its name, state, ports, and Show output. Choose Stop server to shut it down. Manage folder access also lists servers for that project across local tasks.
  4. Understand its lifetime — Completing a Work reply or selecting Stop Run does not stop a managed development server. Stop it explicitly when finished. Disconnecting the owning task or folder, revoking access, signing out, quitting Gab AI, or losing the native connection stops it.

Choose the command environment

Open Manage folder access → Environment settings… for the folder. Login shell is the default and imports eligible exported variables from your shell startup configuration. Minimal environment uses a reduced environment. Include patterns restrict which names are imported; an empty include list allows all eligible names. Exclude patterns take priority. Patterns are case-insensitive; * matches any number of characters and ? matches one. For example, include PATH, DATABASE_URL, MY_APP_* and exclude AWS_*, PRIVATE_TOKEN. Variables with names such as KEY, TOKEN, or SECRET are not automatically removed. Commands can print environment values into task output, so choose the variables your project needs. An app opened from the Dock cannot see exports made only in an unrelated Terminal session. Put required exports in your shell’s login/interactive startup configuration, or launch the app executable from the shell that has them. New command starts read that configuration. Changing the folder’s environment settings stops its running commands and servers; start them again afterward. Environment settings do not remove the project’s file and network restrictions.

Review code changes and parallel work

Open the folder menu → Review changes to compare staged and unstaged Git changes. Task history records supported edits performed through Work’s file tools. Tests, builds, and servers may also change files; command side effects are not all covered by saved-edit Undo, so inspect the repository diff. If Work uses parallel coding workspaces, open Parallel work in change review. Each worker edits a separate saved copy. Review its files, then ask the task to integrate completed workers and run the combined checks. Conflicting edits remain in those copies until resolved. The app’s branch picker changes the shared checkout; it does not create an isolated copy for each chat.

If something goes wrong

Commands or servers are unavailable: confirm that the folder has edit access and the relevant permission, and check for an app update. Remote pairing alone does not enable commands. Command not found or a missing dependency: install the project’s supported tools/dependencies yourself, check PATH and Environment settings…, then retry. Importing PATH does not grant access to every tool or credential file in your home folder. A network-dependent build fails: ordinary tests/build commands have no network access. Prepare dependencies outside that restricted check. Development-server permission is intended for servers and has a separate network scope. Shell environment import fails: check that your shell startup completes promptly without waiting for input, or choose Minimal environment and try again. Port already in use: ask Work to inspect the listener and reuse the correct service. Request a restart only when intended; do not start duplicate copies. A process manager may require its own shutdown procedure. Switching branches is blocked: stop the active tasks, commands, and servers using the folder, then reopen the branch picker. Preserve and resolve conflicting uncommitted changes before retrying. Older logs are unavailable: finite command logs keep the latest 32 commands for up to 24 hours. Server output is a rolling window of up to 16 MiB, so older output can roll off.

Related guides