Run Agents

When to Use

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

Troubleshooting

If you see authentication errors:

• Claude: Ensure Claude Code is authenticated (claude auth status)
• OpenAI: Verify OPENAI_API_KEY is set and valid
• GitHub: Check GITHUB_TOKEN has correct permissions
• Lyzr: Confirm LYZR_API_KEY is active

Basic Usage

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

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

# Run with a prompt (one-shot mode)
opengap 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

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

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

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

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

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

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

Git Caching

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

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

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

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

Auto-Detection (-a git)

The git adapter detects the best runner from the repo:

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