GyroCompass

AI writes 90% of your code & you're shipping fast.
Don't fly blind — keep architectural guardrails.

1000s of PRs later — does your architecture still make sense? Or has it become spaghetti?
GyroCompass reads your living architecture from source, blocks drift the moment a commit crosses a
boundary, and keeps Claude Code, Cursor, and every AI agent oriented — so your system stays coherent
no matter how fast you ship.

🌐 gyrocompass.vercel.app

What is GyroCompass?

AI coding agents (Claude Code, Cursor, Windsurf, Aider, Copilot) generate code faster than any human can review. GyroCompass is the architectural source of truth that keeps your system consistent as agents fill in the details.

It automatically extracts your living architecture from source code, detects drift when AI-generated changes deviate from your documented design, and feeds real-time context back to agents via MCP — so they make better decisions from the start.

Think of it like a coloring book. You designed the outlines. GyroCompass makes sure the agent colors inside the lines.

Features

Quick Start

1. Install

pip install gyrocompass
# or
pipx install gyrocompass

2. Onboard your repo — one command

cd my-project
gyro setup

gyro setup does everything: creates .gyro/, extracts your architecture with
Tree-sitter, installs the enforcement hooks, and prints a ship-readiness audit
summary. Then commit .gyro/.

Step by step instead? gyro init → gyro analyze --save → gyro install-hooks.

3. Connect to Your Agent (MCP)

gyro mcp start

Then add to Claude Code's ~/.claude/settings.json:

{
  "mcpServers": {
    "gyrocompass": {
      "command": "gyro",
      "args": ["mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}

Or for Cursor, add plugin/server.json to your .cursor/mcp.json.

4. Check Drift

gyro drift

LLM Configuration

GyroCompass works with any LLM provider. Set one of:

# OpenAI (default)
export OPENAI_API_KEY=sk-...

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-ant-...
export GYRO_LLM_PROVIDER=anthropic

# Ollama (local, privacy-first — zero data leaves your machine)
export GYRO_LLM_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=llama3.2

# Your company's LLM endpoint (OpenAI-compatible)
export GYRO_LLM_BASE_URL=https://llm.company.internal/v1
export GYRO_LLM_API_KEY=internal-key
export GYRO_LLM_MODEL=gpt-4o

GitHub Action

Add architectural drift detection to every PR in 3 lines:

# .github/workflows/drift-check.yml
name: Architecture Drift Check
on: [pull_request]
jobs:
  drift:
    uses: gyrocompass-io/gyrocompass/.github/workflows/gyrocompass-drift.yml@main
    secrets:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      # Or: ANTHROPIC_API_KEY, GYRO_LLM_BASE_URL + GYRO_LLM_API_KEY

PRs automatically get comments like:

## GyroCompass — Architectural Drift Report

Drift Score: 23%  |  Issues: 2 (1 high, 1 medium)

🟠 High (1)
Rule Violation (rule_violation)
> Payment flow bypasses SQS queue — direct DB write detected in checkout.ts:84
> Element: payment-service
> Suggestion: Route writes through PaymentService.processAsync()

🟡 Medium (1)
Undocumented Component (component_added)
> New component analytics-tracker detected in src/analytics/ but not in .gyrostate.yaml
> Suggestion: Run `gyro analyze --save` to document this component

Architecture State Format

GyroCompass stores state in human-readable, git-diffable YAML:

# .gyro/.gyrostate.yaml
metadata:
  version: "1.0"
  project: my-saas-app

# ── Architecture ──────────────────────────────────────────────────
architecture:
  api-server:
    type: container
    description: FastAPI REST server handling all business logic
    facts:
      - Requires authentication on all non-public endpoints
      - Uses SQLAlchemy for all database access
    relationships:
      postgres:
        type: sync
        protocol: TCP/PostgreSQL
        description: Primary data store

# ── Capabilities ──────────────────────────────────────────────────
capabilities:
  user-authentication:
    description: User signup, login, session management
    status: active
    acceptance_criteria:
      - OAuth via Google and GitHub
      - Session tokens expire after 24h

# ── Rules ─────────────────────────────────────────────────────────
# Defined in .gyro/.gyrorules.yaml

MCP Tools

When GyroCompass is connected as an MCP server, your agents have access to:

Self-Hosting

# Clone and start all services
git clone https://github.com/gyrocompass-io/gyrocompass
cd gyrocompass
cp .env.example .env
# Edit .env with your LLM API key
docker-compose up -d

# API: http://localhost:7700
# Dashboard: http://localhost:3000

Supported Languages

Why GyroCompass

Contributing

Contributions are welcome! Areas where help is needed:

• Language parsers — Add Ruby, Kotlin, Swift, PHP
• Framework detection — Extend tech stack detection rules
• Rules library — Contribute common rules for popular stacks
• Frontend — Improve the dashboard

git clone https://github.com/gyrocompass-io/gyrocompass
cd gyrocompass
uv install
uv run pytest

License

MIT — free for personal and commercial use.

Built for teams who refuse to ship blind.