PyPI

Python

License

Multi-persona engineering mentor with 64 specialized AI personas orchestrating collaborative guidance

🚀 NEW in v0.9.0: Complete Third-Party MCP Integration Suite - Multi-MCP orchestration with 6 integrated MCP servers (Serena, OpenMemory, GitHub, Context7, Tavily, Playwright), 13 workflow templates, and 10 executable demos! Tactical code execution (Sensei → Serena), cross-project memory (OpenMemory), and GitHub-integrated workflows (PR reviews, commit analysis, issue triage). See Integration Guides for complete workflows.

NEW in v0.8.0: Complete Persona Portfolio (64 Personas) - All personas from claude-skills repository now integrated! Added 17 new personas including complete Design & UX team (6), Strategic Expansion skills (5), Critical Infrastructure gaps (5), and Meta-Navigation personas (2).

🌟 MCP Ecosystem Integration: Sensei MCP is designed to work seamlessly with other MCP servers (Context7, Tavily, Playwright, GitHub, OpenMemory, Sequential Thinking) to create a comprehensive CTO co-pilot. See MCP Integration Architecture for the complete vision.

v0.6.0: Granular Persona Content Access (Option B Architecture) - Fixed orchestrator placeholder bug with new content-provider architecture. MCP now provides persona SKILL.md content for Claude to analyze, instead of trying to perform analysis itself. 4 new granular tools for persona discovery, content access, session context, and consultation recording.

v0.5.0: Enhanced Discovery, CI/CD Integration, Team Collaboration & Database Expertise - Interactive demo mode, GitHub Actions/GitLab CI templates, session merging for teams.

v0.4.0: Analytics & Team Collaboration - Track persona effectiveness, export session summaries as ADRs, and share engineering decisions with your team.

Sensei transforms your engineering standards from passive documentation into an active mentor that injects relevant guidelines before Claude reasons, maintaining session memory of architectural decisions.

Human provides: Domain expertise, judgment, context, business constraints, strategic direction

LLM provides: Synthesis across 64 expert personas, pattern matching against 32,000 lines of wisdom, consistency checking, real-time intelligence

Together: CTO-level decisions at code-writing speed with multi-perspective analysis and no weak links

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">

claude mcp add sensei -- uvx sensei-mcp

{
 "mcpServers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

{
 "mcpServers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

{
 "mcpServers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

{
 "mcpServers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

{
 "context_servers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

{
 "mcpServers": {
 "sensei": {
 "command": "uvx",
 "args": ["sensei-mcp"]
 }
 }
}

The Problem: Output styles and custom instructions are cosmetic—applied AFTER Claude has already reasoned.

The Solution: Sensei injects engineering standards BEFORE reasoning based on:

• 50+ file types (Python, JS/TS, Go, Java, Kotlin, Swift, Rust, GraphQL, Docker, k8s, etc.)
• Operation context (CREATE, REFACTOR, DEBUG, SECURITY, etc.)
• Keywords (multi-tenant, payment, async, etc.)
• Session memory of architectural decisions

Result: Standards actually influence behavior, not just formatting.

Output Styles (Cosmetic):

User: "Write an API endpoint"
Claude: [reasons about design]
Claude: [writes code]
Output Style: [formats the response] ← Too late!

Sensei MCP (Active):

User: "Write an API endpoint"
Sensei: [injects API contracts, security, multi-tenancy standards]
Claude: [reasons WITH standards in context]
Claude: [writes code that follows standards]

• 🔧 Fixed Critical Bug: Orchestrator was returning placeholder text instead of real analysis
• 🏗️ New Architecture: MCP as content provider (not analysis engine)
  • MCP provides persona SKILL.md content
  • Claude (calling LLM) performs analysis using that content
  • Mirrors .claude/skills/ pattern for consistency
• 🛠️ 4 New Granular Tools:
  • get_persona_content() - Returns full SKILL.md for a specific persona
  • suggest_personas_for_query() - Intelligent persona selection with relevance scores
  • get_session_context() - Returns session memory (constraints, decisions, patterns) as JSON
  • record_consultation() - Records consultations after Claude performs analysis
• 📊 Benefits:
  • No LLM needed in MCP (no API keys, no costs, no latency)
  • Claude does what it's best at (analysis)
  • Predictable, deterministic MCP behavior
  • Extensible (just add SKILL.md files)

• 🔍 Interactive Persona Discovery - Find the right expert faster:
  • Enhanced list_available_skills() with 3 format modes (standard, detailed, quick)
  • CLI demo mode (sensei-mcp --demo) with 5 real-world scenarios
  • Intelligent context hints when <2 personas selected
  • Technology keyword detection (database, api, security, frontend, mobile, ml)
• 🔧 CI/CD Integration Pack - Integrate Sensei into your development workflow:
  • GitHub Actions workflows for PR reviews and architecture checks
  • Pre-commit hooks (consistency, security, cost analysis)
  • GitLab CI pipeline with 3-stage validation
  • Enhanced analyze_changes() with persona suggestions
  • Comprehensive integration guide (500+ lines)
• 🤝 Session Merge & Team Sync - Collaborate on architectural decisions:
  • Merge multiple developer sessions with conflict resolution
  • 4 merge strategies (latest, oldest, all, manual)
  • Session comparison for side-by-side analysis
  • Attribution tracking for all decisions
• 🗄️ Database Architect Persona - Specialized database expert joins the team:
  • Schema design and normalization expertise
  • Query optimization and indexing strategies
  • Migration planning and scalability patterns
  • Multi-tenancy architecture guidance

• 📊 Session Analytics - Data-driven insights into persona usage and decision patterns:
  • Track which personas are most/least used
  • Context distribution (SECURITY, CRISIS, ARCHITECTURAL, etc.)
  • Decision velocity and consultation patterns
  • Time-based filtering (last 7 days, last 30 days, all time)
  • Export as markdown, JSON, or text
• 📄 Consultation Export - Share individual consultations as professional reports:
  • Markdown format with metadata (ID, timestamp, mode, context)
  • JSON format for CI/CD integration
  • Plain text for communication tools
• 📋 Session Summaries - Export comprehensive ADRs (Architecture Decision Records):
  • Full decision history with rationale
  • Active constraints and agreed patterns
  • Recent consultation history
  • Configurable includes (decisions, consultations, constraints, patterns)
  • Perfect for team onboarding and alignment

• 🎭 47 Specialized Personas - Skill Orchestrator coordinates expert perspectives across 12 categories:
  • Core (3): Snarky Senior Engineer, Pragmatic Architect, Legacy Archaeologist
  • Specialized (6): API Platform Engineer, Data Engineer, Database Architect, Frontend UX Specialist, ML Pragmatist, Mobile Platform Engineer
  • Operations (3): Site Reliability Engineer, Incident Commander, Observability Engineer
  • Security (2): Security Sentinel, Compliance Guardian
  • Platform (3): DevEx Champion, Platform Builder, QA Automation Engineer
  • Cost (1): FinOps Optimizer
  • Leadership (4): Empathetic Team Lead, Product Engineering Lead, Executive Liaison, Technical Writer
  • DevRel (4): Developer Advocate, Solutions Architect, Staff IC Advisor, Open Source Strategist
  • Strategic (6): M&A Due Diligence, Vendor Management, Technical Recruiting, Engineering Transformation, AI Ethics Governance, Data Strategy
  • Management (3): Engineering Manager, Director of Engineering, VP Engineering
  • Technical Leadership (2): Chief Architect, Principal Engineer
  • Coordination (3): Technical Program Manager, Technical Product Manager, Engineering Operations
  • Infrastructure (6): Database Reliability Engineer, Release Engineering Lead, Performance Engineer, Cloud Architect, Test Engineering Lead, Customer Success Engineer
  • Meta (1): Skill Orchestrator
• 🧠 Context Detection - Intelligently routes queries to relevant personas (CRISIS, SECURITY, POLITICAL, ARCHITECTURAL, COST, TEAM, TECHNICAL)
• 🤝 Collaborative Synthesis - Multiple perspectives with conflict resolution and consensus building
• 📊 Consultation Tracking - Session memory records which personas were consulted and why
• ⚡ Multiple Modes:
  • orchestrated (default): 2-5 persona collaboration
  • quick: Just Snarky Senior Engineer for fast answers
  • crisis: Emergency team (Incident Commander, SRE, Executive Liaison)
  • standards: Legacy single-voice mode for backwards compatibility

• 🎯 Context-aware loading - Only 5-15% of rulebook per request (87.5% token savings)
• 🧠 Session memory - Remembers architectural decisions across conversations
• 🤝 Team Sync - Share decisions and rules via .sensei folder in your repo
• 🕵️ Git Awareness - Automatically infer context from staged files
• 📦 50+ file types - Comprehensive tech stack coverage
• 🔍 Smart inference - Automatically determines relevant standards
• 🛡️ Consistent enforcement - No more re-litigating patterns
• 🚀 Zero configuration - Works immediately after install
• 🔒 Privacy-first - Runs locally, no external services

Python, JavaScript, TypeScript, Go, Java, Kotlin, Swift, Ruby, Rust, PHP, C#, Scala, C/C++, Dart, Elixir, Clojure, Elm, Julia, R

React (JSX/TSX), Vue, Svelte, Astro, HTML, CSS, SCSS, SASS, LESS

Terraform, Docker, Kubernetes, nginx, Apache, Shell scripts (bash/zsh), Makefiles, HCL

SQL, Prisma, GraphQL, Protobuf, Avro, CSV, XML, Jupyter notebooks

YAML, JSON, TOML, ESLint, Prettier, Jest, Playwright, Cypress, Webpack, Vite, tsconfig.json

GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines

Android (AndroidManifest.xml, build.gradle), iOS (Info.plist, Podfile)

package.json, Gemfile, Cargo.toml, go.mod, requirements.txt, Pipfile

Prometheus, Grafana, Datadog, New Relic, Sentry

📖 NEW: Complete Usage Guide with Real-World Examples

See detailed use cases including API design review, production crisis response, cost optimization, code review, and session-aware architecture decisions.

Sensei provides 20 MCP tools (4 new in v0.6.0, 2 in v0.5.0, 3 in v0.4.0, 3 in v0.3.0) + CLI demo mode:

Get full SKILL.md content for a specific persona. Claude uses this content to analyze queries from that persona's perspective.

# Get full Security Sentinel content
content = get_persona_content(
 persona_name="security-sentinel",
 include_metadata=True # Optional: includes description and expertise
)
# Returns: Complete SKILL.md with principles, personality, expertise, guidelines
# Claude then uses this content as context to analyze your query
# Example workflow:
# 1. Claude suggests personas → ["security-sentinel", "api-platform-engineer"]
# 2. Claude gets content for each → Full SKILL.md files
# 3. Claude analyzes from each perspective using the content
# 4. Claude synthesizes all perspectives into recommendation

Intelligent persona selection based on query analysis with relevance scores and rationale.

# Get persona suggestions for a query
suggestions = suggest_personas_for_query(
 query="How should we handle authentication for our API?",
 max_suggestions=5, # Maximum number of suggestions (default: 5)
 context_hint="SECURITY" # Optional: force specific context
)
# Returns JSON:
# {
# "query": "How should we handle authentication...",
# "detected_context": "SECURITY",
# "suggestions": [
# {
# "name": "security-sentinel",
# "display_name": "Security Sentinel",
# "relevance": 0.95,
# "rationale": "Expert in authentication, security"
# },
# {
# "name": "api-platform-engineer",
# "display_name": "API Platform Engineer",
# "relevance": 0.82,
# "rationale": "Expert in API design, contracts"
# }
# ]
# }
# Auto-detect context from query
suggest_personas_for_query(
 query="Our AWS bill is too high",
 max_suggestions=3
)
# Returns: finops-optimizer, pragmatic-architect, site-reliability-engineer

Get session memory (constraints, decisions, patterns) as JSON for context-aware analysis.

# Get full session context
context = get_session_context(
 session_id="saas-backend",
 project_root="/path/to/repo" # Optional: for project-local sessions
)
# Returns JSON:
# {
# "session_id": "saas-backend",
# "active_constraints": ["AWS only", "Python 3.11+", "PostgreSQL"],
# "patterns_agreed": ["Use FastAPI", "JWT auth"],
# "recent_decisions": [
# {
# "id": "dec-001",
# "category": "architecture",
# "description": "Use PostgreSQL for primary data store",
# "rationale": "Team expertise, ACID guarantees",
# "timestamp": "2025-01-23T10:30:00"
# }
# ]
# }
# Claude includes this context when analyzing to ensure consistency

Record consultations in session history after Claude performs analysis.

# After Claude analyzes using persona content
record_consultation(
 query="Should we migrate to microservices?",
 personas_used=["pragmatic-architect", "site-reliability-engineer", "finops-optimizer"],
 session_id="saas-backend",
 project_root="/path/to/repo", # Optional
 synthesis="[Claude's complete analysis and recommendation]" # Optional
)
# Returns: "✅ Consultation recorded: consult_42"
# This consultation is now in session history for:
# - Analytics (get_session_insights)
# - Export (export_session_summary)
# - Future context

Interactive walkthrough of Sensei's multi-persona capabilities.

# Run the interactive demo
sensei-mcp --demo
# Shows 5 real-world scenarios:
# - Architecture Decision (microservices migration)
# - Production Crisis (database outage)
# - Security Review (authentication audit)
# - Cost Optimization (cloud spending)
# - Code Quality (technical debt)

Merge multiple developer sessions with intelligent conflict resolution.

# Merge two developer sessions
merge_sessions(
 session_ids=["alice-frontend", "bob-backend"],
 target_session_id="sprint-23",
 conflict_strategy="latest", # "latest", "oldest", "all", "manual"
 session_id="sprint-23",
 project_root="/path/to/repo"
)
# Returns: MergeResult with decisions merged, conflicts detected, attribution tracking
# Manual conflict resolution
merge_sessions(
 session_ids=["alice-session", "bob-session"],
 target_session_id="team-session",
 conflict_strategy="manual" # Returns conflicts for human resolution
)

Compare two sessions side-by-side before merging.

compare_sessions(
 session_a_id="alice-session",
 session_b_id="bob-session",
 session_id="default",
 project_root="/path/to/repo"
)
# Returns: Markdown comparison with decisions, constraints, patterns diff

Get data-driven insights into persona usage, consultation patterns, and decision velocity.

# Get insights for last 7 days
get_session_insights(
 session_id="saas-backend",
 time_range="last_7_days", # "last_7_days", "last_30_days", "all_time"
 format="markdown", # "markdown", "json", "text"
 min_consultations=2 # Only include personas with 2+ consultations
)
# Returns: Most/least used personas, context distribution, decision metrics
# Get JSON for CI/CD integration
get_session_insights(
 session_id="saas-backend",
 format="json"
)

Export a single consultation as a shareable report.

# Export as markdown with full metadata
export_consultation(
 consultation_id="c-2025年01月22日-001",
 session_id="saas-backend",
 format="markdown", # "markdown", "json", "text"
 include_metadata=True
)
# Returns: Professional report with query, personas consulted, synthesis, linked decision
# Export as JSON for API integration
export_consultation(
 consultation_id="c-2025年01月22日-001",
 format="json"
)

Export comprehensive ADRs and session summaries for team sharing.

# Full session export with all sections
export_session_summary(
 session_id="saas-backend",
 format="markdown", # "markdown", "json", "text"
 include=["decisions", "consultations", "constraints", "patterns"],
 max_consultations=10
)
# Returns: ADRs, consultation history, constraints, patterns in markdown
# Export only decisions as JSON
export_session_summary(
 session_id="saas-backend",
 format="json",
 include=["decisions"]
)

Note: get_engineering_guidance() and consult_skill() will be deprecated in v0.7.0. Use the new v0.6.0 granular tools instead (get_persona_content, suggest_personas_for_query, get_session_context, record_consultation).

Get collaborative multi-persona guidance on any engineering question.

# Example: Architecture decision
get_engineering_guidance(
 query="Should we use microservices or a monolith for our SaaS app?",
 mode="orchestrated", # default: auto-selects 2-5 relevant personas
 session_id="saas-backend",
 output_format="standard"
)
# Returns: Synthesis from Pragmatic Architect, Snarky Senior Engineer,
# Product Engineering Lead with consensus and tensions
# Quick mode - fast answer from just Snarky
get_engineering_guidance(
 query="How do I fix this API bug?",
 mode="quick" # Only Snarky Senior Engineer responds
)
# Crisis mode - emergency team
get_engineering_guidance(
 query="Production database is down!",
 mode="crisis" # Incident Commander, SRE, Executive Liaison
)
# Request specific personas
get_engineering_guidance(
 query="How do we reduce our AWS bill?",
 specific_personas=["finops-optimizer", "pragmatic-architect"]
)

Consult a single persona directly for targeted expertise.

consult_skill(
 skill_name="security-sentinel",
 query="Review this authentication implementation for vulnerabilities",
 session_id="saas-backend"
)

Discover all 64 available personas organized by category.

# List all personas (standard format)
list_available_skills()
# Detailed format with examples and metadata
list_available_skills(format="detailed")
# Quick format (names only)
list_available_skills(format="quick")
# List by category
list_available_skills(category="operations") # SRE, Incident Commander, etc.
list_available_skills(category="specialized") # Security, FinOps, Database Architect, etc.

Smart context injection - loads relevant standards based on files and operation.

Note: In v0.3.0, this is now called via get_engineering_guidance(..., mode="standards") for backwards compatibility.

# Example: Working on payment API
get_engineering_context(
 operation="CREATE",
 file_paths=["api/payments.py"],
 description="Building Stripe payment endpoint",
 session_id="saas-backend"
)
# Returns: API contracts, security, multi-tenancy, idempotency standards

Save architectural decisions to prevent re-litigation.

record_decision(
 category="architecture",
 description="Use PostgreSQL for primary data store",
 rationale="Team expertise, ACID guarantees, proven at scale",
 session_id="saas-backend"
)

Pre-implementation validation check.

validate_against_standards(
 design_description="REST API with JWT auth",
 focus_areas=["security", "multi-tenant"],
 session_id="saas-backend"
)

Review all decisions and constraints for current project.

get_session_summary(session_id="saas-backend")

Manage multiple projects with separate session states.

list_sessions()

Direct access to specific rulebook sections.

query_specific_standard(
 section_name="multi_tenancy",
 session_id="saas-backend"
)

Validate proposed changes against past decisions.

check_consistency(
 proposed_change="Switch from Postgres to MongoDB",
 session_id="saas-backend"
)

Automatically infer context from staged git changes (enhanced in v0.5.0 with persona suggestions).

analyze_changes(project_root="/path/to/repo")
# Returns: File changes, diff stats, and suggested personas based on file patterns

Sensei supports sharing decisions and rules with your team:

1. Create a .sensei folder in your project root.
2. Add rules.md for custom project-specific rules.
3. Run tools with project_root: Decisions will be saved to .sensei/decisions.md.

This allows you to commit your engineering memory to Git!

1. Context Inference Engine analyzes:

   • File patterns (API routes, DB schemas, tests, etc.)
   • Operation type (CREATE, REFACTOR, DEBUG, etc.)
   • Keywords (tenant, payment, async, etc.)

2. Rulebook Loader extracts relevant sections:

   • 57 total sections mapped to 32 file patterns
   • Core sections always loaded (principles, philosophy)
   • Task-specific sections loaded on demand

3. Session Manager persists decisions:

   • Stored in $HOME/.sensei/sessions/<project>.json
   • Human-readable JSON format
   • Loaded automatically on each tool call

# 1. Get multi-persona guidance on architecture
result = get_engineering_guidance(
 query="Should we migrate from a monolith to microservices? We have 5 engineers and 10K users.",
 mode="orchestrated", # Auto-selects relevant personas
 session_id="saas-backend"
)
# Personas consulted: Pragmatic Architect, Snarky Senior Engineer, Product Engineering Lead
# Synthesis includes: Consensus points, tensions/trade-offs, recommendation
# 2. Consult specific expert for follow-up
consult_skill(
 skill_name="finops-optimizer",
 query="What's the cost impact of microservices vs monolith?",
 session_id="saas-backend"
)
# 3. Record the decision
record_decision(
 category="architecture",
 description="Stay monolith for now, plan modular architecture",
 rationale="Team size and user scale don't justify microservices complexity yet",
 session_id="saas-backend"
)

# Crisis mode activates emergency response team
get_engineering_guidance(
 query="Production database has 10K connections and is timing out!",
 mode="crisis", # Incident Commander, SRE, Executive Liaison
 session_id="saas-backend"
)
# Returns: Immediate triage steps, communication plan, root cause analysis

# 1. Get context for the feature (legacy standards mode)
get_engineering_context(
 operation="CREATE",
 file_paths=["api/webhooks.py"],
 description="Stripe webhook handler for subscription events",
 session_id="saas-backend"
)
# 2. Record key decisions
record_decision(
 category="architecture",
 description="Use idempotent webhook processing with deduplication",
 rationale="Webhooks can be retried, need to handle duplicates safely",
 session_id="saas-backend"
)
# 3. Validate before implementation
validate_against_standards(
 design_description="POST /webhooks/stripe with signature verification",
 focus_areas=["security", "api"],
 session_id="saas-backend"
)

# Load relevant standards for review
get_engineering_context(
 operation="REVIEW",
 file_paths=["api/users.py", "db/queries.sql"],
 description="User management PR - check multi-tenancy",
 session_id="saas-backend"
)
# Check consistency with past decisions
check_consistency(
 proposed_change="Add user_id index without tenant_id",
 session_id="saas-backend"
)

# Get observability and debugging context
get_engineering_context(
 operation="DEBUG",
 file_paths=["services/payment_processor.py"],
 description="Investigating payment timeout issues",
 session_id="saas-backend"
)
# Query specific standards
query_specific_standard(
 section_name="observability",
 session_id="saas-backend"
)

• Quick Start Guide - 5-minute fast start
• Usage Guide - Comprehensive usage examples

• MCP Integration Architecture - Complete vision for human-LLM partnership
• MCP Integration Examples - Real-world workflows combining multiple MCP servers
• CI/CD Integration Guide - GitHub Actions, GitLab CI, pre-commit hooks

• Architecture Deep Dive - Technical implementation details
• Contributing Guide - How to contribute
• Publishing Guide - PyPI publishing workflow

git clone https://github.com/amarodeabreu/sensei-mcp.git
cd sensei-mcp
pip install -e .

pytest tests/

black src/ tests/
isort src/ tests/

Contributions welcome! See CONTRIBUTING.md for:

• Development setup
• Running tests
• Code style guidelines
• PR submission process

❌ Output styles applied after reasoning ❌ Repeating same context every conversation ❌ Re-litigating architectural decisions ❌ Forgetting past constraints ❌ Loading entire rulebook (40% of tokens)

✅ Standards influence reasoning before code is written ✅ Context-aware loading (5-15% of rulebook) ✅ Session memory persists decisions ✅ Consistent enforcement across conversations ✅ Multi-project support with isolation

Team of 5 engineers:

• 10 mins/day saved per engineer avoiding re-explanation
• 5 architectural re-litigations prevented/week
• 30 mins/incident saved with better observability

Annual Savings: ~500 hours of engineering time

Apache 2.0 - See LICENSE for details

• GitHub: https://github.com/amarodeabreu/sensei-mcp
• PyPI: https://pypi.org/project/sensei-mcp/
• Issues: https://github.com/amarodeabreu/sensei-mcp/issues

• Built with FastMCP
• Powered by Model Context Protocol
• Inspired by the need for consistent engineering standards

Made with 🥋 by amarodeabreu