garc-gws-agent-runtime/CLAUDE.md

GARC — Google Workspace Agent Runtime CLI

Claude Code context file for this project.

Project Summary

GARC bridges OpenClaw-style coding agents with Google Workspace — enabling AI agents to operate on back-office and white-collar tasks using Google Drive, Sheets, Gmail, Calendar, and Tasks as the native data surface.

GARC is the Google Workspace counterpart to LARC (Lark Agent Runtime CLI). It reproduces the same architecture:

• Core pattern: Disclosure chain (SOUL.md → USER.md → MEMORY.md → HEARTBEAT.md) backed by Google Drive
• Permission-first: garc auth suggest "<task>" → keyword matching against config/scope-map.json → required OAuth scopes + identity type
• Target market: Organizations using Google Workspace (Gmail, Drive, Sheets, Calendar, Chat)

Repository Structure

bin/garc                    # Main CLI entrypoint (bash)
lib/
  bootstrap.sh              # Disclosure chain loading from Google Drive
  memory.sh                 # Daily memory sync ↔ Google Sheets
  send.sh                   # Gmail / Google Chat message sending
  agent.sh                  # Agent registration & management (Sheets)
  task.sh                   # Google Tasks operations
  approve.sh                # Approval gate logic
  heartbeat.sh              # System state logging to Sheets
  auth.sh                   # OAuth scope inference & authorization
  drive.sh                  # Google Drive file operations
config/
  scope-map.json            # GWS OAuth scopes × task types × profiles
  gate-policy.json          # Execution gate policies (none/preview/approval)
scripts/
  setup-workspace.sh        # One-shot workspace provisioning
  garc-auth-helper.py       # OAuth2 token management helper
docs/
  garc-architecture.md      # Full architecture reference
  garc-vs-larc.md           # GARC vs LARC comparison
  gws-api-alignment.md      # GWS API command mappings
.claude/skills/             # Claude Code skills for GWS operations

GWS → LARC Mapping

LARC (Lark)	GARC (Google Workspace)
Lark Drive folder	Google Drive folder
Lark Base	Google Sheets
Lark IM chat	Gmail / Google Chat
Lark Wiki	Google Docs (knowledge)
Lark Approval	Google Forms + Sheets approval flow
Lark Calendar	Google Calendar
Lark Task/Project	Google Tasks
lark-cli	gcloud + Google APIs
MCP (Lark)	MCP (Gmail/Drive/Calendar)

Key Architecture Decisions

Google API Access Layer

GARC uses two access methods:

1. Claude Code MCP tools (preferred for interactive use):

   • mcp__claude_ai_Gmail__* — email operations
   • mcp__claude_ai_Google_Drive__* — Drive file ops
   • mcp__claude_ai_Google_Calendar__* — calendar ops

2. Python googleapis client (for CLI/automation):

   • google-api-python-client + google-auth-oauthlib
   • Service account for bot operations
   • OAuth2 user tokens for user-identity operations

Disclosure Chain Storage

Google Drive folder (GARC_DRIVE_FOLDER_ID)
  └── SOUL.md         → agent identity & principles
  └── USER.md         → user profile
  └── MEMORY.md       → long-term memory
  └── RULES.md        → operating rules
  └── HEARTBEAT.md    → system state
  └── memory/
        └── YYYY-MM-DD.md  → daily context

Downloaded to: ~/.garc/cache/workspace/<agent_id>/
Consolidated:  ~/.garc/cache/workspace/<agent_id>/AGENT_CONTEXT.md

Memory Backend (Google Sheets)

Google Sheets replaces Lark Base for structured data:

Sheet Tab	Purpose	LARC Equivalent
memory	Long-term memory entries	Base memory table
agents	Agent registry (id, model, scopes)	Base agent ledger
queue	Task queue lifecycle	Base queue ledger
heartbeat	System state log	Base heartbeat table
approval	Approval instances	Lark Approval

Scope Map (config/scope-map.json)

Structure mirrors LARC's scope-map.json but uses Google OAuth scopes:

{
  "tasks": {
    "read_document": {
      "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
      "identity": "user_access_token",
      "description": "Read Google Drive files"
    }
  },
  "profiles": {
    "readonly": { "scopes": [...], "description": "..." },
    "writer": { "scopes": [...], "description": "..." },
    "admin": { "scopes": [...], "description": "..." },
    "backoffice_agent": { "scopes": [...], "description": "..." }
  }
}

Execution Gates

Same 3-tier gate policy as LARC:

none     → read-only ops (immediate execution)
preview  → medium risk (external visibility, writes) → --confirm flag required
approval → high risk (money, permissions, irreversible) → approval gate

Config (~/.garc/config.env)

GARC_DRIVE_FOLDER_ID=1xxxxx          # Google Drive folder for agent workspace
GARC_SHEETS_ID=1xxxxx                # Google Sheets for memory/registry/queue
GARC_GMAIL_DEFAULT_TO=xxx@gmail.com  # Default email recipient (agent notifications)
GARC_CHAT_SPACE_ID=spaces/xxx        # Google Chat space ID
GARC_CALENDAR_ID=primary             # Google Calendar ID
GARC_CACHE_TTL=300                   # Cache TTL in seconds
GARC_CREDENTIALS_FILE=~/.garc/credentials.json  # OAuth2 client credentials
GARC_TOKEN_FILE=~/.garc/token.json              # OAuth2 user tokens
GARC_SERVICE_ACCOUNT_FILE=~/.garc/service_account.json  # Service account (bot)

Common Commands

# Setup
garc init
garc bootstrap --agent main

# Daily use
garc memory pull
garc send "Draft an expense report for last month"
garc task list

# Permission management
garc auth suggest "create expense report and send for approval"
garc auth check --profile writer
garc auth login --profile backoffice_agent

# Agent management
garc agent list
garc agent register

# Knowledge graph
garc kg build
garc kg query "expense approval process"

Development Phases

• Phase 1A: Core CLI dispatch (garc init/bootstrap/memory/send/task/approve/agent/status)
• Phase 1B: Drive workspace setup + Sheets provisioning
• Phase 1C: OAuth scope map + garc auth suggest/check/login
• Phase 2A: Claude Code skills for GWS operations
• Phase 2B: Multi-agent YAML batch registration
• Phase 3: Queue/ingress system (Gmail-triggered)
• Phase 4: Knowledge graph via Google Docs links

Relation to LARC

GARC is intentionally parallel to LARC, not a replacement. Organizations using:

• Feishu/Lark → use LARC
• Google Workspace → use GARC
• Both → deploy both runtimes; agents registered in one can be mirrored to the other

The runtime governance model (permission intelligence, execution gates, disclosure chain) is identical. Only the backend APIs differ.