⚔️ Yama - AI-Native Code Review Guardian

Enterprise-grade autonomous code review powered by AI and MCP tools

Named after the Hindu deity of justice and death, Yama judges code quality and ensures only the worthy changes pass through.

Architecture

Aspect	Legacy	Current
Architecture	Coded orchestration	AI autonomous orchestration
Bitbucket Integration	Direct handler imports	External MCP server
Context Strategy	Pre-fetch everything	Lazy load on-demand
AI Role	Static analyzer	Autonomous agent with tools
Decision Making	TypeScript code	AI decides
Tool Access	None	All operations via MCP
File Analysis	All at once in prompt	File-by-file AI loop
Jira Integration	None	MCP tools for requirements
Comment Posting	Batch after analysis	Real-time as found
PR Blocking	Manual logic	AI decision based on criteria

Architecture Overview

YamaOrchestrator
    ↓
MemoryManager (per-repo condensed memory)
    ↓
NeuroLink AI Agent (Autonomous)
    ↓
MCP Tools (Bitbucket + Jira)
    ↓
Pull Request Operations

AI Autonomous Workflow

1. Context Gathering (AI-driven)

   • Reads per-repo memory (past review learnings)
   • Reads PR details
   • Finds and reads Jira ticket
   • Loads project standards from memory-bank
   • Reads .clinerules for review guidelines

2. File-by-File Analysis (AI-driven)

   • Reads each file diff individually
   • Searches code for context when needed
   • Reads reference files to understand patterns
   • Comments on issues immediately

3. PR Description Enhancement (AI-driven)

   • Analyzes changes and requirements
   • Generates comprehensive description
   • Updates PR with enhanced content

4. Final Decision (AI-driven)

   • Evaluates all findings
   • Applies blocking criteria
   • Approves or blocks PR

Installation & Setup

1. Prerequisites

# Node.js 20.18.1+ required
node --version

# Install Yama
npm install @juspay/yama

2. Environment Variables

Create a .env file:

# Bitbucket
BITBUCKET_USERNAME=your.email@company.com
BITBUCKET_TOKEN=your-http-access-token
BITBUCKET_BASE_URL=https://bitbucket.yourcompany.com

# Jira (optional)
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
JIRA_BASE_URL=https://yourcompany.atlassian.net

# AI Provider (optional - defaults to auto)
AI_PROVIDER=google-ai
AI_MODEL=gemini-2.5-pro

# Langfuse Observability (optional)
LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key
LANGFUSE_BASE_URL=https://cloud.langfuse.com

3. Initialize Configuration

# Create default config
npx yama init

# Or copy example
cp yama.config.example.yaml yama.config.yaml

# Edit configuration
vim yama.config.yaml

4. Verify Setup

# Test initialization
npx yama review --help

Usage

Basic Review

# Review by PR ID
npx yama review \
  --workspace YOUR_WORKSPACE \
  --repository my-repo \
  --pr 123

# Review by branch
npx yama review \
  --workspace YOUR_WORKSPACE \
  --repository my-repo \
  --branch feature/new-feature

Dry Run Mode

# Test without posting comments
npx yama review \
  --workspace YOUR_WORKSPACE \
  --repository my-repo \
  --pr 123 \
  --dry-run

Enhance Description Only

npx yama enhance \
  --workspace YOUR_WORKSPACE \
  --repository my-repo \
  --pr 123

Programmatic Usage

import { createYama } from "@juspay/yama";

const yama = createYama();

await yama.initialize();

const result = await yama.startReview({
  workspace: "YOUR_WORKSPACE",
  repository: "my-repo",
  pullRequestId: 123,
  dryRun: false,
});

console.log("Decision:", result.decision);
console.log("Issues:", result.statistics.issuesFound);

Local SDK Mode (No Config File Required)

Note: Local mode initializes Git MCP internally via the package script mcp:git:server (uvx mcp-server-git with npx @modelcontextprotocol/server-git fallback).

import { createYama } from "@juspay/yama";

const yama = createYama();

const result = await yama.reviewLocalDiff({
  mode: "local",
  repoPath: process.cwd(),
  diffSource: "staged", // staged | uncommitted | range
  focus: ["Security Analysis", "Code Quality"],
  prompt: "Prioritize correctness and edge cases",
  outputSchemaVersion: "1.0",
});

console.log(result.decision);
console.log(result.issues);

SDK override example (no config file edit needed):

const yama = createYama({
  configOverrides: {
    ai: {
      provider: "anthropic",
      model: "claude-3-7-sonnet-latest",
    },
  },
});

Precedence in SDK mode: configOverrides > config file > environment variables > defaults

CLI local mode:

npx yama review --mode local --repo-path . --diff-source staged

Configuration

Basic Configuration

version: 2
configType: "yama"

ai:
  provider: "auto"
  model: "gemini-2.5-pro"
  temperature: 0.2

mcpServers:
  jira:
    enabled: true

review:
  enabled: true
  focusAreas:
    - name: "Security Analysis"
      priority: "CRITICAL"
    - name: "Performance Review"
      priority: "MAJOR"

Advanced Configuration

See yama.config.example.yaml for complete configuration options.

Project-Specific Standards

Create custom review standards for your repository:

mkdir -p memory-bank

Create memory-bank/coding-standards.md:

# Project-Specific Review Standards

## Critical Security Rules

1. ALL payment data MUST be encrypted
2. NO credit card numbers in logs
3. ALL database queries MUST use parameterized statements

## Performance Requirements

- API response time: < 200ms p95
- Database queries: < 50ms p95

Yama AI will automatically read and apply these standards.

AI Autonomous Features

Lazy Context Loading

AI reads only what it needs:

• Sees unfamiliar function? → search_code("functionName")
• Needs to understand import? → get_file_content("path/to/file.ts")
• Confused about structure? → list_directory_content("src/")

Real-Time Feedback

AI comments as it finds issues:

• No batching - immediate feedback
• Severity-based emojis (🔒 CRITICAL, ⚠️ MAJOR, 💡 MINOR, 💬 SUGGESTION)
• Actionable suggestions with code examples

Requirement Alignment

AI reads Jira tickets:

• Extracts acceptance criteria
• Verifies implementation matches requirements
• Calculates requirement coverage
• Blocks PR if coverage < 70%

Code Context Understanding

AI uses tools to understand code:

• search_code() - Find function definitions
• get_file_content() - Read related files
• list_directory_content() - Explore structure

Per-Repo Memory

AI learns from past reviews and remembers across PRs:

• Reads condensed memory before each review for context
• Writes learnings after PR merge (false positives, missed issues, team conventions)
• LLM-powered condensation keeps memory within a configurable word limit
• Per-repo isolation — each repository gets independent memory keyed by workspace-repository
• Storage as .md files at configurable path (e.g., memory-bank/yama/memory/)
• Environment variable overrides for all settings (YAMA_MEMORY_ENABLED, YAMA_MEMORY_MAX_WORDS, etc.)

Blocking Criteria

AI applies these criteria automatically:

1. ANY CRITICAL issue → BLOCKS PR

   • Security vulnerabilities
   • Data loss risks
   • Authentication bypasses

2. 3+ MAJOR issues → BLOCKS PR

   • Significant bugs
   • Performance problems
   • Logic errors

3. Requirement coverage < 70% → BLOCKS PR (when Jira enabled)

   • Incomplete Jira implementation
   • Missing acceptance criteria

MCP Servers

Yama uses MCP (Model Context Protocol) servers for tool access:

Bitbucket MCP

• Package: @nexus2520/bitbucket-mcp-server
• Tools: get_pull_request, add_comment, search_code, get_file_blame, etc.
• Status: Production ready

Jira MCP

• Package: @nexus2520/jira-mcp-server
• Tools: get_issue, search_issues, get_issue_comments
• Status: Optional integration

Monitoring & Analytics

Track review performance with Langfuse integration:

# Set Langfuse environment variables
export LANGFUSE_PUBLIC_KEY=your-public-key
export LANGFUSE_SECRET_KEY=your-secret-key

Analytics include:

• Tool calls made
• Token usage
• Cost estimate
• Duration
• Decision rationale

Troubleshooting

MCP Server Connection Issues

# Verify environment variables
echo $BITBUCKET_USERNAME
echo $BITBUCKET_TOKEN
echo $BITBUCKET_BASE_URL

AI Not Finding Issues

• Check focusAreas in config
• Verify blockingCriteria are clear
• Ensure temperature is low (0.2-0.3)
• Review project-specific standards in memory-bank

High Token Usage

• Enable lazyLoading: true in config
• Reduce maxFilesPerReview
• Set maxToolCallsPerFile limit
• Use excludePatterns to skip generated files

Performance

Expected Metrics

Metric	Target
Review time	< 10 min for 20 files
Token usage	< 500K per review
Cost per review	< $2 USD
Accuracy	> 95% of V1 findings

Optimization Tips

1. Use lazy loading - Don't pre-fetch everything
2. Cache tool results - Reuse MCP responses
3. Exclude generated files - Skip lock files, minified code
4. Limit file count - Split large PRs

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE for details.

---

⚔️ Built with ❤️ by Juspay • Powered by AI & MCP • Autonomous Code Quality Justice