Git Worktree
Parallel workspace isolation with the git_worktree builtin tool — create, list, remove, and status
Git Worktree
The git_worktree builtin tool provides parallel workspace isolation via Git worktrees. Create feature branches in separate directories, work on them independently, and clean up when done — all without switching branches.
The git_worktree tool requires the session workspace to be inside a Git repository with at least one commit.
Direct Tool Calls
use a3s_code_core::Agent;
let agent = Agent::new("~/.a3s/config.hcl").await?;
let session = agent.session("/my-git-repo", None)?;
// Check worktree status
let r = session.tool("git_worktree", serde_json::json!({"command": "status"})).await?;
println!("{}", r.output);
// Create a worktree for a feature branch
let r = session.tool("git_worktree", serde_json::json!({
"command": "create",
"branch": "feature-auth",
"path": "/my-git-repo/wt-feature-auth"
})).await?;
assert!(r.exit_code == 0);
// List all worktrees
let r = session.tool("git_worktree", serde_json::json!({"command": "list"})).await?;
println!("{}", r.output); // Shows main + feature-auth
// Remove the worktree
let r = session.tool("git_worktree", serde_json::json!({
"command": "remove",
"path": "/my-git-repo/wt-feature-auth"
})).await?;
assert!(r.exit_code == 0);Run: cargo run --example test_git_worktree
Source: core/examples/test_git_worktree.rs
from a3s_code import Agent
agent = Agent("~/.a3s/config.hcl")
session = agent.session("/my-git-repo")
# Check worktree status
r = session.tool("git_worktree", {"command": "status"})
print(r.output)
# Create a worktree for a feature branch
r = session.tool("git_worktree", {
"command": "create",
"branch": "feature-auth",
"path": "/my-git-repo/wt-feature-auth",
})
assert r.exit_code == 0
# List all worktrees
r = session.tool("git_worktree", {"command": "list"})
print(r.output) # Shows main + feature-auth
# Remove the worktree
r = session.tool("git_worktree", {
"command": "remove",
"path": "/my-git-repo/wt-feature-auth",
})
assert r.exit_code == 0Run: python examples/test_git_worktree.py
Source: sdk/python/examples/test_git_worktree.py
const { Agent } = require('a3s-code');
const agent = await Agent.create('~/.a3s/config.hcl');
const session = agent.session('/my-git-repo');
// Check worktree status
let r = await session.tool('git_worktree', { command: 'status' });
console.log(r.output);
// Create a worktree for a feature branch
r = await session.tool('git_worktree', {
command: 'create',
branch: 'feature-auth',
path: '/my-git-repo/wt-feature-auth',
});
assert(r.exitCode === 0);
// List all worktrees
r = await session.tool('git_worktree', { command: 'list' });
console.log(r.output); // Shows main + feature-auth
// Remove the worktree
r = await session.tool('git_worktree', {
command: 'remove',
path: '/my-git-repo/wt-feature-auth',
});
assert(r.exitCode === 0);Run: node examples/test_git_worktree.js
Source: sdk/node/examples/test_git_worktree.js
LLM-Driven Usage
The agent can use git_worktree autonomously when asked to work on parallel features:
let result = session.send(
"Create a worktree for feature-auth, then list all worktrees.",
None,
).await?;
println!("{}", result.text);
assert!(result.tool_calls_count > 0);Subcommands
Prop
Type
API Reference
git_worktree input schema
Prop
Type