Tanagram CLI

A lightweight Go CLI that enforces policies from AGENTS.md files on your local git changes.

Quick Start

Run tanagram before committing to catch policy violations locally:

$ tanagram

✗ Found 1 policy violation(s):

webui/src/Button.tsx:42 - [No hardcoded colors] Don't use hard-coded color values; use theme colors instead
  > background: "#FF5733"

Installation

Quick Start (3 steps)

# 1. Install globally via npm
npm install -g @tanagram/cli

# 2. Automatically add a Claude Code hook
tanagram config claude
# and/or if you use Cursor:
tanagram config cursor

# 3. Run tanagram (will prompt for API key on first run)
tanagram

Requirements:

• Node.js >= 14.0.0
• Anthropic API Key (you'll be prompted to enter it on first run)

The CLI is written in Go but distributed via npm for easier installation and version management. During installation, npm automatically downloads the Go compiler and builds the binary for your platform (no manual setup needed!).

API Key Setup

Tanagram uses Claude AI (via Anthropic API) to extract policies from your instruction files. On first run, you'll be prompted to enter your API key, which will be saved to ~/.tanagram/config.json.

Get an API key:

1. Sign up at https://console.anthropic.com
2. Create an API key in the dashboard
3. Run tanagram and enter your key when prompted

Usage

# Check all changes (unstaged + staged) - automatically syncs if policies changed
tanagram
# or explicitly:
tanagram run

# Manually sync instruction files to cache
tanagram sync

# View all cached policies
tanagram list

# Show help
tanagram help

Smart Caching: Policies are cached and automatically resynced when instruction files change (detected via MD5 hash).

Commands

• run (default) - Check git changes against policies with auto-sync
• sync - Manually sync all instruction files to cache
• list - View all cached policies (shows enforceable vs unenforceable)
• help - Show usage information

Claude Code Hook

Install the CLI as a Claude Code hook to have Claude automatically iterate on Tanagram's output.

Easy setup (recommended):

tanagram config claude

This automatically adds the hook to your ~/.claude/settings.json. It's safe to run multiple times and will preserve any existing settings.

Check hook status:

tanagram config list

Manual setup (alternative): If you prefer to manually edit your settings, add this to your ~/.claude/settings.json (user settings) or .claude/settings.json (project settings):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "command": "tanagram snapshot",
            "type": "command"
          }
        ],
        "matcher": "startup|clear"
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "command": "tanagram",
            "type": "command"
          }
        ]
      }
    ]
  }
}

If you have existing hooks, you can merge this hook into your existing config.

Cursor Hook

Install the CLI as a Cursor Code hook to have Cursor automatically iterate on Tanagram's output.

Easy setup (recommended):

tanagram config cursor

This automatically adds the hook to your ~/.cursor/hooks.json. It's safe to run multiple times and will preserve any existing settings.

Check hook status:

tanagram config list

Manual setup (alternative): If you prefer to manually edit your settings, add this to your ~/.cursor/hooks.json (user settings) or .cursor/hooks.json (project settings):

{
  "hooks": {
    "beforeSubmitPrompt": [
      {
        "command": "tanagram snapshot"
      }
    ],
    "stop": [
      {
        "command": "tanagram"
      }
    ]
  },
  "version": 1
}

If you have existing hooks, you can merge this hook into your existing config.

How It Works

1. Finds instruction files - Searches for AGENTS.md, POLICIES.md, CLAUDE.md, BUGBOT.md, and .cursor/rules/*.mdc in your git repository
2. Checks cache - Loads cached policies and MD5 hashes from .tanagram/
3. Auto-syncs - Detects file changes via MD5 and automatically resyncs if needed
4. LLM extraction - Uses Claude AI to extract ALL policies from instruction files
5. Gets git diff - Analyzes all your changes (unstaged + staged)
6. LLM detection - Checks violations using intelligent semantic analysis
7. Reports results - Terminal output with detailed reasoning for each violation

Cache Location

Policies are cached in .tanagram/cache.gob at your git repository root. Add this to your .gitignore:

.tanagram/

What Can Be Enforced

Everything! Because the LLM reads and understands code like a human:

Simple patterns:

• "Don't use hard-coded colors" → Detects #FF5733, rgb(), etc.
• "Use ruff format, not black" → Detects black usage
• "Always use === instead of ==" → Detects == operators

Complex guidelines:

• "Break down code into modular functions" → Analyzes function length and complexity
• "Don't deeply layer code" → Detects excessive nesting
• "Ensure no code smells" → Identifies common anti-patterns
• "Use structured logging with request IDs" → Checks logging patterns
• "Prefer async/await for I/O" → Understands async patterns

Language-specific idioms:

• Knows Go uses PascalCase for exports (not Python's snake_case)
• Won't flag Go code for missing Python type hints
• Understands JavaScript !== Python !== Go

Exit Codes

• 0 - No violations found
• 2 - Violations found (triggers Claude Code automatic fix behavior)

Example

Create an AGENTS.md in your repo with policies:

# Development Policies

- Don't use hard-coded color values; use theme colors instead
- Use ruff format for Python formatting, not black
- Always use async/await for database operations

Or use Cursor rules files in .cursor/rules/:

---
description: TypeScript coding standards
globs: ["*.ts", "*.tsx"]
---

# TypeScript Standards

- Use strict type checking
- Avoid using 'any' type
- Prefer interfaces over type aliases

Then run tanagram to enforce them locally!

Note: For .mdc files, Tanagram extracts policies from the markdown content only (YAML frontmatter is used by Cursor and ignored during policy extraction).

Tanagram Web Integration

You can also use Tanagram to manage policies across your organization and enforce them on PRs. If you have policies defined online, you can enforce them while you develop locally with the CLI as well.

# Connect your account
tanagram login

# Download policies from your Tanagram account and cache them locally
tanagram sync

For customers with an on-prem installation, set the TANAGRAM_WEB_HOSTNAME environment variable to the URL of your Tanagram instance — for example:

export TANAGRAM_WEB_HOSTNAME=https://yourcompany.tanagram.ai

tanagram login
tanagram sync

Built by @fluttermatt and the Tanagram team. Talk to us on Twitter or email: founders AT tanagram.ai