SkyModderAI

AI-powered mod compatibility checker for Bethesda games.

🚀 Quick Start

# Clone the repository
git clone https://github.com/SamsonProject/SkyModderAI.git
cd SkyModderAI

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py

Then open http://localhost:5000

✨ Features

Core Features

Feature	Description	Why It Matters
Conflict Detection	Finds incompatible mods, missing requirements, load order issues	Prevents CTDs and broken saves
Load Order Validator	Suggests correct load order based on LOOT rules + community data	Based on LOOT rules + community data
Requirements Checker	Validates mod dependencies	Catches missing masters before release
Compatibility Database	Crowdsourced mod compatibility from real users	Real-world data from actual users
LOOT Metadata Generator	Generates YAML for masterlist	Saves mod authors hours of work

Advanced Features

Feature	Description	Status
🐾 OpenCLAW	Automated modding assistant — learns from sessions, proposes improvements	✅ Browser-based
List Builder	Build mod lists from preferences (performance, stability, visuals)	✅ Complete
Community Builds	Share and discover community load orders	✅ Complete
Shared Load Orders	Save and share your mod lists with the community	✅ Complete
Feedback System	Rate conflicts, submit bugs, suggest improvements	✅ Complete
API	RESTful API for developers	✅ `/api/v1/`

Coming Soon

Mod Manager Integration — MO2, Vortex, Wabbajack plugins
Real-time Collaboration — Work on mod lists with friends
Advanced Analytics — Track mod performance over time
Mobile App — Check your mod list on the go

🎮 Supported Games

Game	Status	Notes
Skyrim SE/AE	✅ Production	Full support
Skyrim Legendary	✅ Production	Full support
Skyrim VR	✅ Production	Full support
Fallout 4	✅ Production	Full support
Oblivion	🧪 Beta	Community testing
Fallout 3	📋 Planned	Future release
Fallout: NV	📋 Planned	Future release
Starfield	📋 Planned	Future release

🐾 OpenCLAW — Automated Modding Assistant

OpenCLAW is your browser-based automated modding assistant. It learns from your modding sessions, proposes improvements, and guides implementation — all safely sandboxed.

What OpenCLAW Does

Analyzes your current mod conflicts and performance
Researches solutions from Nexus, Reddit, GitHub
Proposes a 5-phase improvement plan
Executes changes in a sandbox (with your permission)
Learns from your feedback to improve future suggestions

Access OpenCLAW

Navigate to the site
Click "OpenCLAW" in the main navigation
Grant permissions (8 granular scopes available)
Propose a plan (select goal, playstyle, game)
Execute and enjoy!

URL: /api/v1/openclaw/

OpenCLAW Safety

✅ Permission-based access (you control what it can do)
✅ Sandbox isolation (can't modify system files)
✅ Hard-coded denied operations (BIOS, kernel, drivers blocked)
✅ File extension whitelist (only safe types allowed)
✅ Path traversal protection (no escapes from sandbox)
✅ Audit logging (all operations tracked)

🏗️ Architecture

Design Principles

Deterministic First, AI Second — Rules don't hallucinate (90/10 split)
Privacy by Default — No PII in telemetry, local-first storage
Community-Driven — Crowdsourced compatibility data
Transparent — Show exactly why conflicts are flagged
Self-Limiting — Success means the problem is solved

Tech Stack

Backend: Python 3.11, Flask
Database: PostgreSQL (production), SQLite (development)
Cache: Redis (production), in-memory (development)
Frontend: Vanilla JS, no framework
Testing: pytest, hypothesis, locust

Repository Structure

SkyModderAI/
├── blueprints/          # Flask route blueprints
│   ├── api.py           # REST API
│   ├── analysis.py      # Analysis routes
│   ├── auth.py          # Authentication
│   ├── community.py     # Community features
│   ├── openclaw.py      # OpenCLAW automation
│   └── ...
├── services/            # Business logic
├── repositories/        # Data access layer
├── templates/           # HTML templates
├── static/              # Frontend assets
├── tests/               # Test suite
└── docs/                # Documentation

See ARCHITECTURE.md for full system design.

📚 Documentation

Getting Started

Quickstart Guides — MO2, Vortex, Wabbajack integration
Modding Glossary — ESP vs ESM, load order, conflicts
Common Conflicts — Known issues with popular mods

Technical Documentation

Architecture — System design, data flow, storage strategy
Build Guide — Setup, installation, deployment
Data Models — Database schema and ORM
Security — Security policies and best practices

OpenCLAW Documentation

User Guide — How to use OpenCLAW
Technical Plan — Enhancement roadmap

Research & Philosophy

Research Summary — Comprehensive research integration
Philosophy — Core principles
Samson Manifesto — Long-term vision

Full documentation index: docs/README.md

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test suite
pytest tests/test_conflict_detector.py -v

# Run OpenCLAW tests
pytest tests/test_openclaw.py -v

Test Coverage: 80%+ required (enforced in CI)

🤝 Contributing

Ways to Contribute

Code — New features, bug fixes, performance improvements
Documentation — Guides, tutorials, translations
Testing — Bug reports, compatibility data
Community — Help others, share builds, vote on features

Quick Start

git clone https://github.com/SamsonProject/SkyModderAI.git
cd SkyModderAI
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements-dev.txt
pre-commit install

See CONTRIBUTING.md for detailed guidelines.

Good First Issues

UI improvements for compatibility database
Load order share frontend
Mod author verification flow
SEO landing pages for mod pairs
Test coverage improvements

🔒 Security & Privacy

What We Track

Feature usage (anonymized)
Compatibility patterns (aggregated)
Session continuity (local UUID)

What We DON'T Track

Personal identifiers (email, IP — hashed only)
Full mod lists (unless explicitly shared)
Session duration (we don't optimize for addiction)

Your Rights

Export your data: GET /api/samson/telemetry/export
Delete your data: POST /api/samson/telemetry/delete
Opt-out: Set SAMSON_TELEMETRY_ENABLED=false

See SECURITY.md for full security policy.

📊 Performance & Scaling

Current Capacity

Users	PostgreSQL Pool	Max Overflow	Cache
10K	10	20	Redis
100K	20	40	Redis
1M	50	100	Redis Cluster

Optimizations

Redis caching (production)
LOOT data cached for 7 days
In-memory fallback (development)
Rate limiting (default: 100/minute)
Connection pooling

See docs/scaling_guide.md for detailed scaling strategies.

🎯 Roadmap

Q1 2026 (Current)

OpenCLAW browser integration
Codebase cleanup & consistency fixes
Compatibility database UI
Mod author verification program

Q2 2026

10K active users
Mod manager plugins (MO2, Vortex)
Real-time collaboration
Mobile-responsive UI

2027+

Phase II deployment (ecological beachhead)
Worker ownership pilot (first robot equity)
Ethical AGI research (cognitive architecture)

📞 Support & Community

Get Help

Email: support@skymodderai.com
GitHub: Issues
Reddit: r/skyrimmods (tag: [SkyModderAI])

Community Resources

Nexus Mods: Mod compatibility data
LOOT: Load Order Optimization Tool
UESP: Unofficial Elder Scrolls Pages

📜 License

MIT License — Free to use, modify, and distribute.

Copyright (c) 2026 SkyModderAI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

See LICENSE for full terms.

🙏 Acknowledgments

LOOT Team — Load order rules and masterlist data
Nexus Mods — Mod hosting and API
UESP — Game mechanics documentation
xEdit Team — Mod cleaning tools
Modding Community — Compatibility reports and feedback

🎮 Built by Modders, for Modders

SkyModderAI is 100% free + donations. No paywalls, no premium tiers, no bullshit.

If it saved your load order, consider buying us a mead. If not, no hard feelings — use it, leave it, come back when you need it.

Free forever. Open source. Privacy-first.

Last Updated: February 21, 2026
Version: 1.0.0 (Beta)

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.github		.github
blueprints		blueprints
config		config
data		data
docs		docs
extensions/mo2		extensions/mo2
migrations		migrations
repositories		repositories
research		research
scripts		scripts
services		services
static		static
templates		templates
tests		tests
.codecov.yml		.codecov.yml
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
AD_BUILDER_DESIGN.md		AD_BUILDER_DESIGN.md
ARCHITECTURE.md		ARCHITECTURE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
IMPROVEMENTS_SUMMARY.md		IMPROVEMENTS_SUMMARY.md
LANDING_PAGE_REFORMAT.md		LANDING_PAGE_REFORMAT.md
LICENSE		LICENSE
Makefile		Makefile
PHILOSOPHY.md		PHILOSOPHY.md
Procfile		Procfile
README.md		README.md
SECURITY.md		SECURITY.md
VISION_AUDIT.md		VISION_AUDIT.md
ad_builder_service.py		ad_builder_service.py
app.py		app.py
auth.py		auth.py
auth_utils.py		auth_utils.py
build.sh		build.sh
business_service.py		business_service.py
cache_service.py		cache_service.py
celery_worker.py		celery_worker.py
cleanup_clutter.sh		cleanup_clutter.sh
community_builds.py		community_builds.py
compatibility_service.py		compatibility_service.py
config.py		config.py
config_loader.py		config_loader.py
conflict_detector.py		conflict_detector.py
constants.py		constants.py
context_threading.py		context_threading.py
curation_service.py		curation_service.py
db.py		db.py
deterministic_analysis.py		deterministic_analysis.py
deviation_labeler.py		deviation_labeler.py
exceptions.py		exceptions.py
feedback_service.py		feedback_service.py
fix_svg.py		fix_svg.py
knowledge_index.py		knowledge_index.py
list_builder.py		list_builder.py
logging_utils.py		logging_utils.py
loot_parser.py		loot_parser.py
mod_author_service.py		mod_author_service.py
mod_images.py		mod_images.py
mod_recommendations.py		mod_recommendations.py
mod_warnings.py		mod_warnings.py
models.py		models.py
oauth_utils.py		oauth_utils.py
openclaw_engine.py		openclaw_engine.py
presentation_service.py		presentation_service.py
pruning.py		pruning.py
pyproject.toml		pyproject.toml
quickstart_config.py		quickstart_config.py
reliability_weighter.py		reliability_weighter.py
render.yaml		render.yaml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
research_pipeline.py		research_pipeline.py
result_consolidator.py		result_consolidator.py
rss_service.py		rss_service.py
run.bat		run.bat
run.ps1		run.ps1
run.sh		run.sh
samson_fuel.py		samson_fuel.py
samson_integration.py		samson_integration.py
samson_telemetry.py		samson_telemetry.py
saved_lists.py		saved_lists.py
scheduler.py		scheduler.py
search_engine.py		search_engine.py
security_utils.py		security_utils.py
sentry_config.py		sentry_config.py
setup.sh		setup.sh
shared_load_orders.py		shared_load_orders.py
shopping_service.py		shopping_service.py
sponsor_service.py		sponsor_service.py
system_impact.py		system_impact.py
transparency_service.py		transparency_service.py
version.py		version.py
walkthrough_manager.py		walkthrough_manager.py
web_search.py		web_search.py

Folders and files

Latest commit

History

Repository files navigation

SkyModderAI

🚀 Quick Start

✨ Features

Core Features

Advanced Features

Coming Soon

🎮 Supported Games

🐾 OpenCLAW — Automated Modding Assistant

What OpenCLAW Does

Access OpenCLAW

OpenCLAW Safety

🏗️ Architecture

Design Principles

Tech Stack

Repository Structure

📚 Documentation

Getting Started

Technical Documentation

OpenCLAW Documentation

Research & Philosophy

🧪 Testing

🤝 Contributing

Ways to Contribute

Quick Start

Good First Issues

🔒 Security & Privacy

What We Track

What We DON'T Track

Your Rights

📊 Performance & Scaling

Current Capacity

Optimizations

🎯 Roadmap

Q1 2026 (Current)

Q2 2026

2027+

📞 Support & Community

Get Help

Community Resources

📜 License

🙏 Acknowledgments

🎮 Built by Modders, for Modders

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages