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

Manage folder access → Environment settings… chooses Inherited environment (default) or Minimal environment. Inherited uses the environment Gab AI received when it launched, not an interactive/login shell; tests, builds and servers do not run shell startup files. Trusted terminal environment behavior depends on the installed build; follow its Environment settings description. Include/exclude variable-name patterns control imports; exclusions win, * and ? are wildcards. Sensitive names such as KEY, TOKEN or SECRET are not automatically stripped. A Dock-launched app cannot see exports from an unrelated Terminal session. Check installed tools and PATH; do not ask users to paste secrets into chat. Changing these settings stops the folder’s commands/servers. Environment choices do not remove file/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. Unexpected environment: check how Gab AI was launched and review the variable-name filters in Environment settings. Tests, builds and servers do not run your shell startup files. Try Minimal environment to isolate inherited variables. 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

Trusted terminal for broader commands

Trusted terminal is a separate, explicit grant for a trusted read/write Mac project: Manage folder access → Trusted terminal → Allow trusted terminal… (or Settings → Mac app → Folder access). A chat request still needs the native confirmation. It can run authorized commands with the user’s normal home, saved credentials, network and account-accessible files outside the project, subject to macOS permissions. Tests/builds or server permission alone does not enable it. It is noninteractive, has no password/TTY entry and grants no new administrator privilege; some commands are unsupported. Commands/output go to the cloud agent. Use only for trusted tasks, and revoke in Folder access when no longer needed.

Commits and remote Git operations

Work can inspect Git status/diffs, stage/unstage selected files and make local commits in supported repositories with read/write folder access and action approval. Structured local commits do not require command permission. Requested push/fetch/pull/merge and agent-driven branch switching use separately approved Trusted terminal and the Mac’s existing Git authentication. The manual branch picker remains local and has its own busy-folder checks. Preserve unrelated edits; do not promise automatic stash, force push, merge-conflict resolution or remote publication. Stopping SSH cannot guarantee that remote jobs stop or roll back.

Coding checks and request recovery

Compatible coding builds can plan changes, search a codebase, apply focused edits and run configured repository checks before reporting success. Completion checks require command access and installed dependencies; a failed or unavailable check must be reported. Supported parallel coding uses separate worker copies and reviewed integration rather than changing the user’s branch/index automatically. Review changes → This task/Task history and a reply’s changes card show recorded edits; Undo request restores supported saved edits only when current files still match, and does not undo terminal/network side effects.