AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

TDD Requirements

Test-first development is mandatory:

RED - Write failing test first
GREEN - Minimal implementation to pass
REFACTOR - Clean up while green

Key Patterns

Find the simplest solution that meets all acceptance criteria. Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math) Build extensible pieces of logic that can easily be integrated with other pieces. DRY principles should be loosely held. Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.

Third-Party Library Usage

If you aren't 100% sure how to use a third-party library, SEARCH ONLINE to find the latest documentation and mid-2025 best practices.

GitLab Inbox Robot Mode

The gi CLI has a robot mode optimized for AI agent consumption with structured JSON output, meaningful exit codes, and TTY auto-detection.

Activation

# Explicit flag
gi --robot list issues

# Auto-detection (when stdout is not a TTY)
gi list issues | jq .

# Environment variable
GI_ROBOT=1 gi list issues

Robot Mode Commands

# List issues/MRs with JSON output
gi --robot list issues --limit=10
gi --robot list mrs --state=opened

# Count entities
gi --robot count issues
gi --robot count discussions --type=mr

# Show detailed entity info
gi --robot show issue 123
gi --robot show mr 456 --project=group/repo

# Check sync status
gi --robot sync-status

# Run ingestion (quiet, JSON summary)
gi --robot ingest --type=issues

# Check environment health
gi --robot doctor

Response Format

All commands return consistent JSON:

{"ok":true,"data":{...},"meta":{...}}

Errors return structured JSON to stderr:

{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'gi init'"}}

Exit Codes

Code	Meaning
0	Success
1	Internal error
2	Config not found
3	Config invalid
4	Token not set
5	GitLab auth failed
6	Resource not found
7	Rate limited
8	Network error
9	Database locked
10	Database error
11	Migration failed
12	I/O error
13	Transform error

Best Practices

Use gi --robot for all agent interactions
Check exit codes for error handling
Parse JSON errors from stderr
Use --limit to control response size
TTY detection handles piped commands automatically

2.6 KiB Raw Blame History