Welcome to Tanagram. This documentation helps you get the most out of it.

What is Tanagram?#

Tanagram generates and enforces rules in coding agents and code reviews. If you're a tech lead, founding engineer, or staff+ engineers, Tanagram enables you to scale your knowledge and influence and avoid repeating yourself.

Tanagram has three parts:

• Rules Engine: Tanagram watches your codebase and automatically generates rules. You can also write your own rules.

• CLI: Tanagram checks Claude and Cursor's output so they can generate better code before getting to code review time.

• Code Review Automation: Tanagram automates the mental checklist that you'd normally run through in code reviews. Some of our users require PR authors to address Tanagram feedback before having codeowners take a look.

Use Cases#

• Automatically enforcing patterns: For teams who own an API, Tanagram enforces consistent naming conventions, error handling, and semantics for external users, without requiring code authors to read and remember a long list of rules.
• Encode incident remediations: Mistakes happen. Someone generates an unindexed database query and it ends up doing a full-table scan on your users table. Someone adds the wrong middleware to an admin API route and leaks user data across sessions. Encode remediations as Tanagram rules to automatically prevent them from repeating on future code changes.
• Advancing New Patterns: Create a Tanagram rule to push forward a new pattern, architecture, or requirement (e.g. upgrading framework versions, avoiding implicit anys, using hooks correctly). Unlike linters, Tanagram only operates on changed code (so you won't get thousands of warnings on existing code). Tanagram rules can also support fuzzy requirements that would be impossible to express in a linter.

Getting Started#

1. Sign up at web.tanagram.ai.
2. Connect your GitHub repos.
3. Install the CLI.

After connecting your repository, Tanagram will analyze your existing repos to generate rule suggestions. Depending on the size of your repos, this typically takes 2–5 minutes. We'll send you an email when suggestions are ready for your review.

See Suggested Rules for more details.

Rules#

Rules are the core of Tanagram. They capture your team's coding conventions, best practices, and current architecture.

What Rules Should I Have?#

Most rules reflect security, reliability, performance, or business logic patterns. For example:

• API endpoints with a documentID parameter (directly or via a parent router) must call verifyAccessOrRaise() before doing anything else to ensure that the authenticated user has been granted permissions to a document.
• Tier 0 and tier 1 services must specify a staged rollout that can't exceed 10% of traffic for the first 30 minutes. to enforce a company-wide reliability directive.
• If you add a new transaction type to app/core/transactions.ts, also add that transaction type to the big switch in src/HandleRecord.scala to enforce changes that must happen together — unlike tradational linters, Tanagram rules can span different languages.
• For third-party libraries that are critical to our application (e.g. FastAPI itself), pin them to an exact version instead of using ^ — Tanagram rules can encode fuzzy logic.

Rules can prevent compliance or operational problems. For example:

• One of our users suffered outages from contractors replacing environment-variable reads with hard-coded values for testing and forgetting to reset those changes, so they added a rule to never replace an environment-variable read with a hard-coded value.
• On our own team, we used to use database migrations to backfill or correct invalid data. These migrations started failing when we expanded to multiple environments, so we added Never backfill data in a database migration to our own set of rules.

Rules can also be used to push forward strictness requirements or new architecture patterns. For example:

• One of our users migrated from an in-house "task" system to a new "workflow" system based on Temporal. They added a rule to accelerate this migration: Do not add new Tasks, which are now deprecated. Instead, create Workflows, which are built on our new Temporal service.

Writing Good Rules#

Rules educate team members and instruct coding agents.

• Completely specify what you want. E.g. instead of "avoid nested if statements", write "avoid if statements nested more than 2 levels deep; use an early return instead".
• Be explicit about exclusions. E.g. instead of "files should follow x naming convention", write "files should follow x naming convention, except for files whose paths contain generated/".
• Some rules require context beyond a few contiguous lines. If you're seeing false positives, encourage our agent to explore the codebase and verify its detections. E.g. instead of just saying "avoid N+1 queries", write "avoid N+1 queries. when you've found what you think might be a violation, explore the callstack to determine if the N+1 data has actually been fetched earlier in the call stack".

Creating Rules#

You can write a new rule from the "Add Rule" button on the website, or by asking @tanagram in a github comment on a connected repo.

Rules can be as short as a single sentence, although more detail will help improve accuracy. Tanagram will internally "rewrite" rules with context gathered from your codebase, including existing examples of violations and non-violations, which helps improve accuracy.

Rules are scoped to individual repos, and can be scoped to include or exclude specific directories within those repos.

Updating Rules#

You can update existing rules from the existing website by clicking into the "Description" input.

You can also disable, delete, or re-run the rewriting process by clicking on the ellipsis icon next to the rule name.

Suggested Rules#

Tanagram analyzes your repos' history to suggest rules. Suggestions show up at the top of your list of rules, with more visible on the "All Suggestions" page.

Suggestions are automatically generated when you first connect a repo, and then periodically in the background.

Each suggestion links to the data sources that inspired the suggestion.

You can accept a suggestion, which will turn it into a full rule. Once accepted, a suggestion also gets rewritten with additional context gathered from your codebase.

For a preview of what this looks like, install the CLI, open Claude, and run /tanagram-mine. It'll use your local github access (via gh) to pull some recent PR comments and suggest some rules from human feedback. Our server-side suggestions are much more robust.

CLI#

The Tanagram CLI enforces your team's rules directly in coding agents like Claude Code and Cursor. When your agent makes code changes, Tanagram automatically evaluates them against your rules. If a rule is violated, your agent sees the feedback and fixes the issue itself.

Installation#

Install from npm:

npm install -g @tanagram/cli

Then log in:

tanagram login

That's it. You don't need to do anything else; the CLI automatically installs a Stop hook in ~/.claude/settings.json that runs tanagram eval after every code change.

How It Works#

1. Use Claude as you normally would. Claude makes its changes.
2. Once done, Claude invokes Stop hooks, which includes the tanagram eval command.
3. If any rules are violated in the changed code, tanagram eval emits instructions for Claude to fix itself.

Rules are synced from your Tanagram account and cached locally in ~/.tanagram/, so evaluation is fast.

Commands#

Command	Description
tanagram login	Authenticate with Tanagram
tanagram logout	Sign out
tanagram eval	Evaluate current changes against rules
tanagram sync	Manually sync rules from Tanagram
tanagram list	View rules for current repository
tanagram config set-host <host>	Set your on-prem hostname

In-Agent Usage#

You can create, update, enable, disable, or delete rules directly from Claude using the tanagram CLI.

For example, after you steer Claude to do something differently, ask it to make a Tanagram rule:

# In Claude

> make the button red
…
> extract and use a theme variable instead of hard-coding a color
…
> create a tanagram rule for that

On-Prem#

For on-prem installations, configure your host before logging in:

tanagram config set-host yourcompany.tanagram.ai
tanagram login

This automatically routes all CLI traffic to your dedicated endpoints:

• Web: https://yourcompany.tanagram.ai
• API: https://api-yourcompany.tanagram.ai

To verify your configuration:

tanagram config get-host

Troubleshooting#

• "Not in a git repository": Tanagram must be run from within a git repository.

• "No rules configured": Your repository may not have rules set up yet. Visit web.tanagram.ai to configure rules.

• "authentication required" or "not logged in": Run tanagram login to authenticate.

Code Review Automation#

Once you connect a repo, Tanagram automatically reviews every pull request when the pull request is opened, and on subsequent pushes.

If the PR contains code that violates a rule, Tanagram will add an inline comment, just like you manually would have. If a subsequent push fixes the problem, Tanagram will automatically resolve the comment thread.