Frogger

CLI, Python SDK, and MCP server for the GlassFrog API v3.

Manage Holacracy governance — circles, roles, people, policies, and more — from the command line or through AI agents.

Install

git clone git@github.com:PrecisionNutrition/frogger.git
cd frogger
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

API Key Setup

mkdir -p ~/.config/glassfrog
echo "YOUR_API_KEY" > ~/.config/glassfrog/api_key.txt

Or set the GLASSFROG_API_KEY environment variable.

CLI Usage

# List resources
frogger circles list
frogger roles list --circle-id 272
frogger people list --circle-id 272
frogger policies list --circle-id 272

# Get a single resource
frogger circles get 272
frogger people get 1082
frogger people get alaina@precisionnutrition.com   # lookup by email

# JSON output (for scripting / agents)
frogger --json circles list

# Full backup
frogger backup

# Organization info
frogger org

Write Operations

frogger people create --name "Jane Doe" --email "jane@example.com"
frogger projects create --description "New project" --circle-id 272 --role-id 2670 --person-id 1082
frogger people update 1082 --name "New Name"

Deleting Records

Deletes always require --force and automatically back up the record first:

frogger people delete 12345 --force

Use --dry-run to preview without executing:

frogger --dry-run people delete 12345 --force

Policy Proposals

Since policies can't be created via the API, generate a formatted proposal document:

frogger policies propose 272 --title "My Policy" --body "Policy text here"

This saves a markdown file to ./proposals/ with circle context and existing policies for reference.

All Resources

Command	Operations
circles	list, get
roles	list, get
people	list, get, create, update, delete
assignments	list, create, update, delete
projects	list, create, update, delete
metrics	list, create, update, delete
checklist-items	list, create, update, delete
custom-fields	list, create, update, delete
policies	list, propose
domains	list
actions	list, create, update, delete
tensions	list, create, update
proposals	list, create
backup	full backup
org	show org info

Global Flags

Flag	Description
--json	Machine-readable JSON output
--no-backup	Skip the full-backup prompt on writes
--dry-run	Preview write/delete without executing
--verbose	Show HTTP request details
--api-key	Override API key

Key Circle IDs

ID	Circle
272	PN Company (top-level)
432	Financial Operations
1281	People Operations
7215	Coaching and Education Operations
100741	Growth & Customer Experience
100747	Technology

Python SDK

Use the SDK directly in Python:

from glassfrog import GlassFrogClient
from glassfrog.resources import circles, policies

client = GlassFrogClient.from_key_file()

# List all circles
for circle in circles.list_circles(client):
    print(f"{circle.id}: {circle.name}")

# Get policies for PN Company
for policy in policies.list_policies(client, circle_id=272):
    print(f"{policy.title}: {policy.body[:80]}")

MCP Server

Expose GlassFrog as tools for Claude and other AI agents.

Claude Code

claude mcp add --transport stdio glassfrog -- python -m glassfrog_mcp

# Or user-wide (all projects):
claude mcp add --transport stdio --scope user glassfrog -- python -m glassfrog_mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "glassfrog": {
      "command": "python",
      "args": ["-m", "glassfrog_mcp"],
      "env": {}
    }
  }
}

The MCP server provides 41 tools (glassfrog_circles_list, glassfrog_people_get, etc.) and a glassfrog_guide prompt describing all capabilities.

Tests

# Unit tests (mocked HTTP)
pytest tests/unit/ -v

# Integration tests (live API, GET-only)
pytest tests/integration/ -m integration -v -s

# All tests
pytest -v

# Coverage (SDK)
pytest tests/unit/ --cov=src/glassfrog --cov-report=term-missing

Safety

• Deletes require --force and always back up the record first
• Per-record backup on delete is mandatory and cannot be skipped
• frogger backup creates a full timestamped snapshot of all data
• Backups are stored in ~/.config/glassfrog/backups/
• Integration tests only use GET — no writes against the live API