Home / Latest / Manual / Integrations / ai / AI Agents
Propose Changes

AI Agents

SmartGit can run an installed Codex or Claude command-line agent with context from selected commits or refs. The agent uses its own authentication and execution permissions.

Configuring an agent

  1. Install the agent and configure its authentication outside SmartGit.
  2. Open Preferences -> AI Integration -> Codex or Preferences -> AI Integration -> Claude and enable that integration.
  3. Configure Path and the command arguments, then choose the model settings under Defaults. Codex uses one Arguments field; Claude uses New Arguments and Resume Arguments.

Codex defaults to gpt-6-sol with xhigh reasoning. Claude defaults to fable with medium effort.

Auto-Configure can fill in Codex and Claude settings on Windows, macOS, and Linux. It tries commands in PATH before common installer and package-manager locations, including Homebrew and npm. Before executing each candidate’s check, SmartGit shows its path and test arguments. Choose Probe to run the check, or Cancel to stop auto-detection without applying a configuration.

At startup, SmartGit also checks the filesystem for installed agents that have no configured Path. The notification offers Configure to open that agent’s preferences and start Auto-Configure. Choose Ignore to stop automatic checks for that agent, or close the notification to postpone checks for seven days. Manual Auto-Configure remains available.

Disable an agent on its own preferences page when you want to remove its run actions.

Starting a conversation

Select commits in the Graph and choose Run Codex… or Run Claude… from the context menu. In the Standard Window, these commands open a compact conversation pane beside the graph. They are also available for a ref in My History or All Branches + Tags. Enter a prompt and choose the model settings. Use Start conversation (the play icon) in the compact pane, or Start in the full view. The agent runs in the background. In the Log Window, the run commands open a separate Agent window. This window has one tab per repository. Each tab shows the number of running or unread conversations for that repository. Closing a tab leaves its agents running.

In the full conversation view, choose New Codex Conversation or New Claude Conversation to start from the current branch’s HEAD. The draft appears above stored sessions with a gray status dot. Select it to return to your prompt after viewing another session. Codex and Claude keep separate prompt drafts.

Reviewing conversations

When the agent supplies a task summary with its initial response, SmartGit uses it in the session list and conversation header. Follow-up runs keep this summary. Without a summary, the session list shows the initial prompt.

The conversation controls are:

  • Resume sends follow-up instructions when the agent has a resumable session.
  • Steer sends additional instructions while the agent is running and ready to accept them.
  • Stop cancels the running agent. Work already performed remains.

In either conversation view, focus the prompt and press Ctrl+Enter (Command+Enter on macOS) to invoke the available Start, Resume, or Steer action.

Compact conversations in History

In the Standard Window, select History, then Agents in the left accordion to keep a conversation beside the Graph. Click New Agent conversation (+) to compose a prompt for the current branch. If several agents are configured, choose which one to use.

Use the conversation selector at the top to switch conversations. It lists running conversations first, then unread finished conversations, then read conversations, with the most recently updated first in each group. Choose More… or click Open full Agents view to open the selected conversation in the full view. The views share prompt drafts and model settings, and remember their conversation selections separately.

The compact output shows only the latest run, with a prompt preview, assistant responses, and activity summaries. Output wraps automatically. The play icon changes to Resume conversation for a resumable session. While the agent is running, use Stop conversation or Steer conversation.

Selecting a conversation reveals its execution branch in the Graph. The graph keeps recent HEAD commits and the agent’s commits visible and compacts other linear history. Use the graph controls to expand or collapse sequences.

Note

The low-level property ai.agent.compact.maxEntryCount limits the conversation picker (default 10, range 3 to 100, including More…). Available screen space can reduce the number of rows further. ai.agent.output.compact.promptMaxLength limits prompt previews and activity summaries (default 128 characters). Previews also stop at the first line break; open the full view for the complete prompt and activity details. standard.graph.agent.headCommits sets how many recent first-parent HEAD commits stay visible (default 3, minimum 1).

Full conversation view

Click Agents in the main layout selector to open the full view in the Standard Window. With the conversation panel focused, press Ctrl+Shift+Enter (Command+Shift+Enter on macOS) to invoke the available Start or Resume action. The output has collapsible activity sections. To wrap long lines, right-click the output and choose Wrap long lines. Place the caret on a section heading and press Left to collapse it or Right to expand it. Press Enter or Space to toggle it.

The Bash and Tool Uses section headers summarize recent commands and tool names, newest first. Consecutive Git commands and repeated invocations are grouped. Expand a section to see arguments and output.

Select output text and choose Copy from the context menu, or press Ctrl+C (Command+C on macOS). Right-click an expanded section and choose Copy Markdown to copy its body as Markdown. The Agents button’s badge counts running or unread conversations for the repository. Selecting a finished session marks it read. When a run finishes while its conversation is visible, SmartGit marks the result read. To return to it later, select one or more sessions and choose Mark Agent Session as Unread from the context menu. Use the agent properties to adjust output grouping or disable the completion beep.

Expand Launch Parameters in the conversation output to inspect the execution Branch and Working Tree path. The Local Session Area identifies the directory containing the stored session data.

Note

In the Standard Window, starting a run from the full Agents layout returns to History by default. Set ai.agent.standard.switchToHistoryAfterLaunch to false to keep the full layout open.

Note

Reopened conversations may show Intermediate activity hidden for older runs. Their complete output remains in the run-*.jsonl logs under Local Session Area.

Note

The low-level property ai.agent.output.commandSummaryCount sets the number of recent invocations summarized in a header (default 10, minimum 1). The limit applies before grouping.

For Codex, expand a Sub-agent Activity section to see details of delegated work, including its thread ID and agent path.

If agents are still running when you exit SmartGit, the confirmation offers Stop Agents & Exit (Stop Agents & Quit on macOS). SmartGit stops the agents and waits for their processes to exit before closing.

Worktrees

Agents use a dedicated SmartGit worktree by default. The Run Codex in a dedicated SmartGit worktree or Run Claude in a dedicated SmartGit worktree option controls this on the agent’s preferences page. The restricted sandboxing profiles require this option to be enabled.

A new managed conversation creates an agent/ branch from the first selected commit in the dedicated worktree. The user’s original checkout stays on its branch. Follow-up runs reuse the conversation’s worktree and execution branch. If the agent advances the branch, SmartGit retains it and associates the conversation with its new tip.

If a newly created branch stays at its initial commit and its worktree is clean, SmartGit removes that branch and its worktree after the run. If the worktree contains local changes or untracked files, SmartGit keeps both for review, and the run can still finish successfully. Use Delete Agent Session to clean up a stored conversation and its managed worktree. The worktree must be clean before it can be removed.

Sandboxing

Choose a Sandboxing profile on the agent’s preferences page:

  • No restrictions (approval_policy=on-request, approvals_reviewer=auto_review) for Codex or No sandbox (permission-mode auto) for Claude leaves permissions to the agent’s automatic permission handling.
  • Write access restricted to workspace restricts writes while keeping the backend’s normal network rules.
  • Write access restricted to workspace, network basically disabled for Codex or Write access restricted to workspace, network disabled for Claude adds network restrictions.

The profile with network restrictions is the default and is selected by Auto-Configure. For native Windows Claude, Auto-Configure selects No sandbox instead and asks you to acknowledge the lack of filesystem and network isolation. Both restricted profiles require a dedicated SmartGit worktree.

Codex’s restricted profiles require a native app-server invocation. Claude’s sandbox requires macOS, Linux, or a supported WSL2 launcher; it is unavailable on native Windows. Claude’s profile with network disabled requires Claude Code 2.1.219 or newer.

Configure permissions through Sandboxing, rather than through Arguments, New Arguments, Resume Arguments, or Cleanup Arguments. For older configurations, remove sandbox and approval options such as approval_policy, sandbox_mode, or --permission-mode, or reapply Auto-Configure. SmartGit rejects these options even when No restrictions or No sandbox is selected.

Note

Restricted profiles allow writes to the repository’s common Git directory, so refs and repository metadata remain shared with other worktrees. Codex declines requests for command or file-change approval beyond the configured profile. Its network restriction does not disable its separate web-search capability. Claude’s operating-system sandbox covers Bash commands and their child processes; its built-in file tools use Claude’s permission rules. The Claude profile with network disabled also blocks WebFetch and WebSearch. These network restrictions do not disable the connection to the AI service.

Note

The sandboxing key in each backend’s ai.yml section accepts no-sandbox, profile-write-restricted, or profile-write-restricted-no-network. Codex’s Working Directory and Cleanup Arguments fields, under Custom containerized Codex, are intended for custom launchers. Claude’s Cleanup Arguments field is under Custom containerized Claude. Restricted profiles use the execution worktree as Codex’s working directory. A custom launcher that manages its own permissions can use the low-level sandboxing overrides.

Prompts and speech input

The menu above the prompt shows the selected preset or model settings. In the compact pane, click the model summary to open this menu. Use it to choose a preset or change Model, Reasoning Effort (Codex), or Effort Level (Claude). Codex also offers Service Tier and Context Window. Choose Custom… to open Model Settings and enter values not listed in the menus.

The Prompts menu lists submitted prompts for this repository and agent, newest first. Linked worktrees share this history. The menu also lists steering instructions for the current conversation and saved global prompts. Selecting a history entry or global prompt restores its model settings.

Choose Save as Global Prompt in this menu to reuse the current prompt and model settings in other repositories with the same agent. To remove it, load the prompt and choose Remove Global Prompt.

Backend configurations initially include Balanced and Deep Reasoning presets.

Note

Use the prompt history limit to change how many submitted prompts are remembered. The low-level property ai.agent.steeringHistory.maxCount sets the number of recent steering prompts shown in the menu (default 10, range 1 to 100). When upgrading to repository-specific history, SmartGit clears the older global history in ai.yml.

Note

Agent settings are stored under codex and claude in ai.yml in SmartGit’s settings directory. The built-in preset IDs are balanced and deep-reasoning. Edit the backend’s presets list to add, modify, or reorder presets. To modify a built-in preset, replace its id entry with a named entry like those below.

Close SmartGit before editing ai.yml, and merge the examples into the existing agent sections. Start SmartGit again to load the presets.

Example

Codex presets for a long context window and priority processing: The contextWindow value is in tokens.

codex:
  presets:
    - name: Astra Long Context
      model: gpt-6-astra
      reasoningEffort: high
      contextWindow: 1050000
    - name: Luna Priority
      model: gpt-6-luna
      reasoningEffort: xhigh
      serviceTier: priority

Example

Claude presets with low and high effort: For Claude, reasoningEffort sets the Effort Level.

claude:
  presets:
    - name: Sonnet Quick
      model: sonnet
      reasoningEffort: low
    - name: Fable Thorough
      model: fable
      reasoningEffort: high

Note

To customize prompts, create codex.md or claude.md in the same directory. The file replaces the bundled template and must contain {{ prompt }} for your prompt. Remove it to use the bundled default again. Bundled templates include the execution branch and the selected ref or commit IDs. They also request Markdown responses, lists instead of tables, and commit SHAs with at least 12 hexadecimal characters. To supply a session title, ask for one to three keywords on the last non-empty line of the initial response, for example SUMMARY: repository cleanup. Keep this line in plain text, without quotes or trailing punctuation. Use {% if not followUpPrompt %}...{% endif %} to request it only for the initial prompt.

Note

Auto-detection uses CODEX_HOME and CODEX_INSTALL_DIR for custom Codex installations. For custom package-manager locations, it uses HOMEBREW_PREFIX, HOMEBREW_CASKROOM, and npm_config_prefix or NPM_CONFIG_PREFIX from SmartGit’s environment. Startup notification choices are stored under autoDetection in ai.yml. To undo Ignore, set the agent’s codex or claude entry in its ignored section to false.

Press and hold Mic to record speech, then release it to insert the transcript into the prompt. You can also click Stop while recording to finish. Speech input requires Built-in AI to be enabled. It uses the first configured API provider of type openai, which must support audio/transcriptions with the whisper-1 model. SmartGit sends the recorded audio to that provider using its API credentials.

Deleting sessions

To delete stored data, select sessions and choose Delete Agent Session from the context menu. Stop a running agent first. The confirmation includes the session data and any dedicated worktree. If notes exist, Delete Git Note (or Delete Git Notes) is selected by default; clear it to retain the notes. Resolve local changes and untracked files in a dirty managed worktree before deleting the session. SmartGit retains commits on the execution branch.

ai.agent.ui.beepOnFinish

Set ai.agent.ui.beepOnFinish to false to disable the beep when an agent run finishes. The default is true.

ai.agent.output.aggregateToolUses

Set ai.agent.output.aggregateToolUses to false to display each tool use in its own output section. The default is true, which groups tool uses together.

ai.agent.output.autoCollapseLineLimit

An active output section is automatically collapsed when it exceeds this many lines. The default is 10; set it to 0 to disable this limit.

ai.agent.promptHistory.maxCount

This controls how many submitted prompts an agent remembers for each repository’s Prompts menu. The default is 10, and the permitted range is 1 to 100.

ai.agent.codex.disableSandboxing

Set ai.agent.codex.disableSandboxing to true when a custom launcher should manage Codex permissions instead of SmartGit’s sandboxing profiles. SmartGit then ignores the stored profile, disables the Sandboxing controls, and passes sandbox and approval arguments through without validating or overriding them. The default is false.

ai.agent.claude.disableSandboxing

Set ai.agent.claude.disableSandboxing to true when a custom launcher should manage Claude permissions. SmartGit then ignores the stored profile, disables the Sandboxing controls, and passes permission arguments through without validation. It also stops adding --permission-mode and --settings arguments. The default is false.