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