Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Conway-Research/automaton/llms.txt

Use this file to discover all available pages before exploring further.

Git tools enable agents to interact with version control systems for code management, collaboration, and deployment.

​
Repository Inspection

​
git_status

Show git status for a repository.
​
path
string
default:"~/.automaton"
Repository path
Risk Level: safe Returns: Branch name, staged/modified/untracked counts, clean status
Example
await git_status({ path: '/workspace/repo' });
// Returns:
// Branch: main
// Staged: 2
// Modified: 1
// Untracked: 3
// Clean: false

​
git_diff

Show git diff for a repository.
​
path
string
default:"~/.automaton"
Repository path
​
staged
boolean
default:false
Show only staged changes (git diff —cached)
Risk Level: safe Returns: Full diff output 
await git_diff({ path: '/workspace/repo' });

​
git_log

View git commit history.
​
path
string
default:"~/.automaton"
Repository path
​
limit
number
default:10
Number of commits to show
Risk Level: safe Returns: Formatted list of commits with hash, date, and message
Example
await git_log({
  path: '/workspace/repo',
  limit: 5
});
// Returns:
// a1b2c3d 2024-01-15 Add new feature
// e4f5g6h 2024-01-14 Fix bug in auth
// ...

​
Commit Operations

​
git_commit

Create a git commit.
​
message
string
required
Commit message
​
path
string
default:"~/.automaton"
Repository path
​
add_all
boolean
default:true
Stage all changes first (git add -A)
Risk Level: caution Returns: Confirmation message 
await git_commit({
  path: '/workspace/repo',
  message: 'feat: Add user authentication'
});

​
Branch Management

​
git_branch

Manage git branches.
​
path
string
required
Repository path
​
action
string
required
Action: list, create, checkout, or delete
​
branch_name
string
Branch name (required for create/checkout/delete)
Risk Level: caution 
await git_branch({
  path: '/workspace/repo',
  action: 'list'
});

​
Remote Operations

​
git_push

Push to a git remote.
​
path
string
required
Repository path
​
remote
string
default:"origin"
Remote name
​
branch
string
Branch name (optional, uses current branch if omitted)
Risk Level: caution Returns: Push result message 
await git_push({
  path: '/workspace/repo',
  remote: 'origin'
});

​
git_clone

Clone a git repository.
​
url
string
required
Repository URL (https or git)
​
path
string
required
Target directory for clone
​
depth
number
Shallow clone depth (optional)
Risk Level: caution Returns: Clone result message 
await git_clone({
  url: 'https://github.com/user/repo.git',
  path: '/workspace/repo'
});
Use shallow clones (depth: 1) for faster downloads when you don’t need full history.

​
Common Workflows

​
Feature Development

// 1. Create feature branch
await git_branch({
  path: '/workspace/repo',
  action: 'create',
  branch_name: 'feature/user-auth'
});

// 2. Switch to branch
await git_branch({
  path: '/workspace/repo',
  action: 'checkout',
  branch_name: 'feature/user-auth'
});

// 3. Make changes...
await write_file({ path: '/workspace/repo/auth.js', content: '...' });

// 4. Check status
await git_status({ path: '/workspace/repo' });

// 5. Review changes
await git_diff({ path: '/workspace/repo' });

// 6. Commit
await git_commit({
  path: '/workspace/repo',
  message: 'feat: Implement JWT authentication'
});

// 7. Push
await git_push({
  path: '/workspace/repo',
  branch: 'feature/user-auth'
});

​
Code Review Preparation

// Check what changed
const status = await git_status({ path: '/workspace/repo' });

if (status.includes('Modified: 0')) {
  console.log('No changes to commit');
} else {
  // Review diff
  const diff = await git_diff({ path: '/workspace/repo' });
  
  // Check recent commits
  const log = await git_log({
    path: '/workspace/repo',
    limit: 5
  });
  
  // Commit if needed
  await git_commit({
    path: '/workspace/repo',
    message: 'refactor: Clean up error handling'
  });
}

​
Repository Setup

// Clone repository
await git_clone({
  url: 'https://github.com/org/project.git',
  path: '/workspace/project',
  depth: 1
});

// Create development branch
await git_branch({
  path: '/workspace/project',
  action: 'create',
  branch_name: 'develop'
});

// Switch to develop
await git_branch({
  path: '/workspace/project',
  action: 'checkout',
  branch_name: 'develop'
});

// Install dependencies
await exec({
  command: 'cd /workspace/project && npm install',
  timeout: 120000
});

​
Self-Modification Integration

Git tools integrate with Conway’s self-modification system:
  • edit_own_file automatically creates git commits with audit trails
  • revert_last_edit uses git revert HEAD to undo changes
  • reset_to_upstream fetches and hard-resets to origin/main
  • pull_upstream supports cherry-picking individual commits
See Self-Modification for details.

​
Best Practices

Run git_status before commits to verify what will be included.
Use git_diff to inspect changes and catch mistakes.
Follow conventional commits: feat:, fix:, refactor:, docs:
Keep main/master stable. Develop in feature branches.
Back up your work to remote repositories frequently.

​
Error Handling

// Clone may fail if directory exists
try {
  await git_clone({
    url: 'https://github.com/user/repo.git',
    path: '/workspace/repo'
  });
} catch (err) {
  if (err.includes('already exists')) {
    console.log('Repository already cloned');
  }
}

// Push may fail if remote is ahead
const pushResult = await git_push({
  path: '/workspace/repo'
});

if (pushResult.includes('rejected')) {
  // Pull first, then retry
  await exec({
    command: 'cd /workspace/repo && git pull --rebase'
  });
  await git_push({ path: '/workspace/repo' });
}

Self-Modification

Edit your own code with git auditing

VM Tools

Execute commands and manage files

Skills System

Install skill packages from git repos

Policy Engine

Safety constraints and auditing

Build docs developers (and LLMs) love

Get started for freeTalk to us