How do I run with a specific adapter?

Use the -a flag to select the adapter (e.g., -a claude, -a openai). Some adapters require environment keys like OPENAI_API_KEY or GITHUB_TOKEN.

Where are repositories cached and how do I refresh?

Repos cloned with -r are cached at ~/.gitagent/cache/. Use --refresh to force a update or --no-cache to avoid using the cache temporarily.

How does auto-detection (-a git) work?

The git adapter inspects the repo for hints: a .gitagent_adapter file, model names, and framework files (CLAUDE.md, .cursorrules, crew.yaml, .lyzr_agent_id, .github_models). If nothing is found, it defaults to claude.

run-agent

npx machina-cli add skill open-gitagent/gitagent/run-agent --openclaw

Files (1)

SKILL.md

2.4 KB

Run Agents

When to Use

When a user wants to run an agent locally, from a git repo, or with a specific adapter/framework.

Basic Usage

# Run local agent with Claude (default)
gitagent run -d ./my-agent

# Run from git repo
gitagent run -r https://github.com/user/agent

# Run with a prompt (one-shot mode)
gitagent run -d ./my-agent -p "Review my code"

Adapters

Adapter	Flag	Env Var Required	Interactive
Claude	`-a claude`	(uses Claude Code auth)	Yes
OpenAI	`-a openai`	`OPENAI_API_KEY`	No
CrewAI	`-a crewai`	—	No
OpenClaw	`-a openclaw`	`ANTHROPIC_API_KEY`	No (`-p` required)
Nanobot	`-a nanobot`	`ANTHROPIC_API_KEY`	Yes
Lyzr	`-a lyzr`	`LYZR_API_KEY`	No (`-p` required)
GitHub	`-a github`	`GITHUB_TOKEN`	No (`-p` required)
Git	`-a git`	(auto-detects)	Depends
Prompt	`-a prompt`	—	Print only

Examples

# Claude (interactive)
gitagent run -d ./my-agent

# GitHub Models (one-shot, streaming)
export GITHUB_TOKEN="ghp_..."
gitagent run -d ./my-agent -a github -p "Explain this codebase"

# Lyzr (creates agent on Lyzr Studio + chats)
export LYZR_API_KEY="..."
gitagent run -r https://github.com/user/agent -a lyzr -p "Hello"

# Lyzr one-liner (clone + create + chat)
gitagent lyzr run -r https://github.com/user/agent -p "Hello"

# Auto-detect adapter from repo
gitagent run -r https://github.com/user/agent -a git -p "Hello"

# Just print the system prompt
gitagent run -d ./my-agent -a prompt

Git Caching

Repos cloned via -r are cached at ~/.gitagent/cache/:

# Use cache (default)
gitagent run -r https://github.com/user/agent

# Force refresh
gitagent run -r https://github.com/user/agent --refresh

# No cache (temp dir, deleted after)
gitagent run -r https://github.com/user/agent --no-cache

Auto-Detection (`-a git`)

The git adapter detects the best runner from the repo:

.gitagent_adapter file (explicit hint)
Model name (claude-* → claude, gpt-* → openai)
Framework files (CLAUDE.md, .cursorrules, crew.yaml, .lyzr_agent_id, .github_models)
Default: claude

Source

git clone https://github.com/open-gitagent/gitagent/blob/main/examples/gitagent-helper/skills/run-agent/SKILL.mdView on GitHub

Overview

Run agents locally or from a git repo using multiple adapters such as Claude, OpenAI, Lyzr, and GitHub Models. This gives you flexible backends and prompts to fit testing and production needs.

How This Skill Works

Select the adapter with the -a flag, supply necessary API keys via environment variables when required, and choose between local or git repo runs. The git adapter can auto-detect the best runner from the repository and repos are cached under ~/.gitagent/cache/ to speed up repeated runs.

When to Use It

Run a local agent with Claude (default)
Run an agent from a git repository
Run with a one-shot prompt using -p
Run using an adapter that requires API keys (OpenAI, GitHub)
Auto-detect the best adapter from the repo using -a git

Quick Start

Step 1: Decide if you want a local path or a git repo and choose an adapter with -a
Step 2: Run the agent using gitagent run with -d for local or -r for repo, and specify the adapter with -a
Step 3: Optionally provide a prompt with -p and manage caching with --refresh or --no-cache

Best Practices

Always specify the adapter with -a to avoid ambiguity
Set required API keys in environment variables (e.g., OPENAI_API_KEY, GITHUB_TOKEN)
Use the cached repo to speed up subsequent runs
Use --refresh to force updating the repo or --no-cache to avoid using the cache
Test prompts in interactive mode when the adapter supports it and adjust -p accordingly

Example Use Cases

Claude (interactive): gitagent run -d ./my-agent
GitHub Models (one-shot, streaming): export GITHUB_TOKEN=...; gitagent run -d ./my-agent -a github -p Explain this codebase
Lyzr (create + chat): export LYZR_API_KEY=...; gitagent run -r https://github.com/user/agent -a lyzr -p Hello
Lyzr one-liner (clone + create + chat): gitagent lyzr run -r https://github.com/user/agent -p Hello
Auto-detect adapter from repo: gitagent run -r https://github.com/user/agent -a git -p Hello

Frequently Asked Questions

Add this skill to your agents