glab-agent

GitLab-native AI agent orchestration platform. Define coding agents in YAML, manage them through GitLab's native interface, and enforce team standards through shared Skills.

Why Local Agent?

| | Cloud Agents (Devin, Jules) | glab-agent | |---|---|---| | Code location | Uploaded to cloud sandbox | Stays on your GitLab | | Data security | Code passes through third-party servers | Code never leaves your network | | Customization | Platform defaults | YAML-defined agents, skills, triggers | | Team standards | Each person configures individually | Shared Skills enforce team conventions | | Provider lock-in | Single model | Claude, Codex — switch with one line (Gemini planned) | | Observability | Platform UI | Reuses your existing GitLab boards |

Quick Start

Prerequisites

• Node.js >= 20 — node --version
• glab CLI — Install, then glab auth login
• Claude CLI or Codex CLI — the AI provider your agent will use
• GitLab bot account (recommended) — a dedicated user account so agent actions appear separately from yours

Setup

# 1. Install
npm install -g glab-agent

# 2. Initialize in your project
cd your-project
glab-agent init my-bot --provider claude

# 3. Create a GitLab Personal Access Token for the bot account
#    → Settings > Access Tokens > scopes: api, read_user, read_repository, write_repository
echo "GITLAB_TOKEN=glpat-xxx" >> .glab-agent/.env

# 4. Verify dependencies
glab-agent doctor

# 5. Test with a single poll cycle (synchronous, you see output immediately)
glab-agent run-once my-bot

# 6. Start background watcher
glab-agent start my-bot

Go to any GitLab issue and type @your-bot-username — the agent will pick it up, write code, run tests, and create a merge request. Use glab-agent watch my-bot to see what it's doing.

Try it in 30 seconds (no real project needed)

If you have a local GitLab (via pnpm gitlab:setup) or any test GitLab instance:

# Seed a demo project with a real bug and an issue
glab-agent demo setup

# Start the demo agent
glab-agent start demo-bot

# Open the issue in your browser, comment "@claude-bot can you look at this?"
# The agent will ship a merge request in ~2 minutes.

# Clean up when done
glab-agent demo teardown

See glab-agent demo list for available scenarios.

How It Works

┌─────────── GitLab ────────────────┐
│  Issues → @mention / assign → Todos│
└──────────────┬─────────────────────┘
               │ poll
        ┌──────▼──────┐
        │   Watcher   │  Filter by triggers, manage labels
        └──────┬──────┘
        ┌──────▼──────┐
        │  AI Agent   │  Read issue → Code → Test → Push → Create MR
        │ (Claude/    │
        │  Codex)     │
        └─────────────┘

Watcher polls GitLab for new todos, filters by your configured triggers, creates an isolated git worktree, and launches the AI agent. The Agent autonomously reads the issue, writes code, runs tests, commits, pushes, and creates a merge request.

Agent Definition (YAML)

# .glab-agent/agents/backend-bot.yaml
name: backend-bot
provider: claude
gitlab:
  token_env: GITLAB_TOKEN
prompt:
  preamble: "You are a backend engineer focused on API correctness and test coverage."
triggers:
  labels: [backend]
  actions: [mentioned, assigned]
skills:
  - test-before-commit    # Reference a shared skill by name
  - security-scan
poll_interval_seconds: 60

Shared Skills

Skills are reusable prompt fragments in SKILL.md format (YAML frontmatter + markdown body). Store them in .glab-agent/skills/:

<!-- .glab-agent/skills/test-before-commit.md -->
---
name: test-before-commit
description: Run tests before committing
---

After modifying code, run tests to ensure they pass.
If tests fail, fix the issues before committing.

Import skills from GitHub (including Anthropic's official skill library):

glab-agent skills                          # List all shared skills
glab-agent skills import anthropics/skills  # Import from GitHub

CLI Commands

| Command | Description | |---------|-------------| | glab-agent init [name] | Initialize project and optionally create an agent | | glab-agent list | List all agent definitions | | glab-agent start <name> | Start agent as background watcher | | glab-agent stop <name> | Stop agent | | glab-agent status [name] | Show agent status with heartbeat | | glab-agent watch <name> | Real-time agent monitoring | | glab-agent run-once <name> | Run single watcher cycle | | glab-agent cancel <name> | Cancel current task | | glab-agent retry <name> <iid> | Retry a failed issue | | glab-agent why <iid> | Diagnose why an issue wasn't picked up | | glab-agent history <name> | Show execution history | | glab-agent skills | List shared skills | | glab-agent gc <name> | Clean up old worktrees | | glab-agent doctor | Check prerequisites |

All commands support --project <dir> to target a different directory.

GitLab as Control Plane

No extra dashboards needed. glab-agent maps to GitLab's native features:

• User Status — Agent shows as 🟢 Ready / 🔧 Working / 🔴 Offline in team member list
• Issue Board — Agent work appears as cards moving through Backlog → In Progress → In Review → Done
• Labels — Status machine: In Progress, In Review, Done, Error
• @mention — Trigger agents just like you'd ping a colleague
• Assignment — Assign an issue to the bot like you'd assign a coworker
• User Bio — Agent's skills and instructions visible on its GitLab profile

Reliability

• API retry — Exponential backoff (1s/2s/4s) for transient failures
• Circuit breaker — Stops polling after 5 consecutive failures, backs off up to 5 minutes
• Atomic state writes — Write-to-temp + rename prevents corruption on crash
• Heartbeat monitoring — Detects stale watchers via glab-agent status
• Graceful shutdown — SIGTERM updates GitLab status before exit

Observability

• Structured logging — JSON Lines format via GITLAB_AGENT_LOG_FORMAT=json
• Metrics — Append-only JSONL per agent (.glab-agent/metrics/)
• Heartbeat — Cycle count and last error in .glab-agent/heartbeat/

Documentation

Development documentation lives in docs/:

• AGENTS.md — canonical shared instructions for Claude, Codex, and other coding agents
• Design Principles — P1-P17, architecture decision criteria
• Test Strategy — coverage policy, key modules, known gaps
• Harness Engineering — human + AI collaboration methodology

Run glab-agent doctor for environment diagnostics.

Requirements

• Node.js >= 20
• glab — GitLab CLI
• claude or codex — AI coding CLI
• A GitLab personal access token with api scope

License

MIT