Git Worktree

The session git tool runs git as a privileged host operation. It accepts a structured command object (command, plus subcommand/name/path for worktrees) and returns a tool result with output and exitCode. This example inspects a repo, then creates, lists, and removes a worktree directly through the tool surface.

import { Agent } from '@a3s-lab/code';
import * as path from 'path';

const agent = await Agent.create('agent.acl');
const session = agent.session('/path/to/repo');

// Inspect the repo
const status = await session.git({ command: 'status' });
console.log(status.output);

// Create a worktree on a new branch
const wtPath = path.join('/path/to/repo', 'wt-feature-auth');
const created = await session.git({
  command: 'worktree',
  subcommand: 'create',
  name: 'feature-auth',
  path: wtPath,
});
if (created.exitCode !== 0) throw new Error(`create failed: ${created.output}`);

// List worktrees
const list = await session.git({ command: 'worktree', subcommand: 'list' });
console.log(list.output);

// Remove the worktree when done
const removed = await session.git({
  command: 'worktree',
  subcommand: 'remove',
  path: wtPath,
});
if (removed.exitCode !== 0) throw new Error(`remove failed: ${removed.output}`);

await session.close();

import os
from a3s_code import Agent, SessionOptions

agent = Agent.create(open("agent.acl").read())
session = agent.session("/path/to/repo", SessionOptions())

# Inspect the repo
status = session.git({"command": "status"})
print(status.output)

# Create a worktree on a new branch
wt_path = os.path.join("/path/to/repo", "wt-feature-auth")
created = session.git({
    "command": "worktree",
    "subcommand": "create",
    "name": "feature-auth",
    "path": wt_path,
})
if created.exit_code != 0:
    raise RuntimeError(f"create failed: {created.output}")

# List worktrees
listing = session.git({"command": "worktree", "subcommand": "list"})
print(listing.output)

# Remove the worktree when done
removed = session.git({
    "command": "worktree",
    "subcommand": "remove",
    "path": wt_path,
})
if removed.exit_code != 0:
    raise RuntimeError(f"remove failed: {removed.output}")

session.close()

Pass a command object rather than positional arguments: { command: 'status' }, { command: 'diff' }, or { command: 'worktree', subcommand: 'list' }. Each call returns a tool result, so check exitCode (Node) / exit_code (Python) before trusting the output.

Direct git calls are privileged host operations. Put push, publish, and release workflows behind application-level approval or automation gates.

A runnable version ships at crates/code/sdk/node/examples/git/test_worktree_git.ts.

Git Worktree

Git Worktree

On this page