gitlore/docs/robot-mode-design.md

Robot Mode Design

Overview

Robot mode optimizes the gi CLI for AI agent consumption with structured JSON output, meaningful exit codes, and token-efficient responses.

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

Global Flags

Flag	Description
--robot	Force JSON output, structured errors
--quiet	Suppress progress/spinners (implied by --robot)

Exit Codes

Code	ErrorCode	Meaning
0	-	Success
1	INTERNAL_ERROR	Unknown/internal error
2	CONFIG_NOT_FOUND	Config file missing
3	CONFIG_INVALID	Config file malformed
4	TOKEN_NOT_SET	GitLab token not configured
5	GITLAB_AUTH_FAILED	Authentication failed
6	GITLAB_NOT_FOUND	Resource not found
7	GITLAB_RATE_LIMITED	Rate limited
8	GITLAB_NETWORK_ERROR	Network/connection error
9	DB_LOCKED	Database locked by another process
10	DB_ERROR	Database error
11	MIGRATION_FAILED	Migration failed
12	IO_ERROR	File I/O error
13	TRANSFORM_ERROR	Data transformation error

Error Output Format

When --robot is active, errors are JSON on stderr:

{
  "error": {
    "code": "CONFIG_NOT_FOUND",
    "message": "Config file not found at ~/.config/gi/config.toml",
    "suggestion": "Run 'gi init' to create configuration"
  }
}

Success Output Format

All commands return consistent JSON structure:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "count": 50,
    "total": 1234,
    "elapsed_ms": 45
  }
}

Command-Specific Output

gi list issues --robot

{
  "ok": true,
  "data": {
    "issues": [
      {
        "iid": 123,
        "project": "group/project",
        "title": "Bug in login",
        "state": "opened",
        "author": "username",
        "assignees": ["user1"],
        "labels": ["bug", "priority::high"],
        "discussions": { "total": 5, "unresolved": 2 },
        "updated_at": "2024-01-15T10:30:00Z",
        "web_url": "https://..."
      }
    ]
  },
  "meta": { "showing": 50, "total": 234 }
}

gi show issue 123 --robot

{
  "ok": true,
  "data": {
    "issue": {
      "iid": 123,
      "project": "group/project",
      "title": "Bug in login",
      "description": "Full markdown...",
      "state": "opened",
      "author": "username",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "discussions": [
        {
          "id": "abc123",
          "resolved": false,
          "notes": [
            {
              "author": "user1",
              "body": "Comment text...",
              "created_at": "2024-01-11T09:00:00Z",
              "system": false
            }
          ]
        }
      ]
    }
  }
}

gi ingest --type issues --robot

{
  "ok": true,
  "data": {
    "resource_type": "issues",
    "projects": [
      {
        "path": "group/project",
        "issues_synced": 45,
        "discussions_synced": 123
      }
    ],
    "totals": {
      "issues": 45,
      "discussions": 123
    }
  },
  "meta": { "elapsed_ms": 3400 }
}

gi count issues --robot

{
  "ok": true,
  "data": {
    "entity": "issues",
    "count": 1234,
    "breakdown": {
      "opened": 456,
      "closed": 778
    }
  }
}

gi doctor --robot

{
  "ok": true,
  "data": {
    "success": true,
    "checks": {
      "config": { "status": "ok", "path": "~/.config/gi/config.toml" },
      "database": { "status": "ok", "version": 6 },
      "gitlab": { "status": "ok", "user": "username" },
      "projects": [
        { "path": "group/project", "status": "ok" }
      ]
    }
  }
}

gi sync-status --robot

{
  "ok": true,
  "data": {
    "last_sync": {
      "status": "completed",
      "resource_type": "issues",
      "started_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:00:45Z",
      "duration_ms": 45000
    },
    "cursors": [
      {
        "project": "group/project",
        "resource_type": "issues",
        "cursor": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

Implementation Plan

Phase 1: Core Infrastructure

1. Add --robot global flag to Cli struct
2. Create RobotOutput trait for consistent JSON serialization
3. Add exit code mapping from ErrorCode
4. Implement TTY detection with atty crate

Phase 2: Command Updates

1. Update all commands to check robot mode
2. Add JSON output variants for commands missing them (count, ingest, sync-status)
3. Suppress progress bars in robot mode

Phase 3: Error Handling

1. Update main.rs error handler for robot mode
2. Add suggestion field to GiError variants
3. Emit structured JSON errors to stderr

Phase 4: Documentation

1. Update AGENTS.md with robot mode commands
2. Add --robot examples to help text