Contributing to Jan

Guide for contributing to Jan - an open-source AI assistant that runs 100% offline.

Contributing to Jan

Thank you for considering contributing to Jan. It’s people like you that make Jan an amazing project for local AI.

Jan is an AI assistant that runs 100% offline on your device. Think ChatGPT, but private, local, and under your complete control. If you’re thinking about contributing, you’re already awesome - let’s make AI accessible to everyone, one commit at a time.

Quick Navigation

Web App

React UI and user interface logic

Core SDK

TypeScript SDK and extension system

Extensions

Supportive modules for features

Tauri Backend

Rust native system integration

How Jan Works

Jan is a desktop app that runs local AI models. Here’s the architecture:

┌──────────────────────────────────────────────────────────┐
│                   Web App (Frontend)                     │
│                      (web-app/)                          │
│  • React UI                                              │
│  • Chat Interface                                        │
│  • Settings Pages                                        │
│  • Model Hub                                             │
└────────────┬─────────────────────────────┬───────────────┘
             │                             │
             │ imports                     │ imports
             ▼                             ▼
  ┌──────────────────────┐      ┌──────────────────────┐
  │     Core SDK         │      │     Extensions       │
  │      (core/)         │      │   (extensions/)      │
  │                      │      │                      │
  │ • TypeScript APIs    │◄─────│ • Assistant Mgmt     │
  │ • Extension System   │ uses │ • Conversations      │
  │ • Event Bus          │      │ • Downloads          │
  │ • Type Definitions   │      │ • LlamaCPP           │
  └──────────┬───────────┘      └───────────┬──────────┘
             │                              │
             └──────────────┬───────────────┘
                            │
                            ▼
                        Tauri IPC
                    (invoke commands)
                            │
                            ▼
┌───────────────────────────────────────────────────────────┐
│                   Tauri Backend (Rust)                    │
│                      (src-tauri/)                         │
│                                                           │
│  • Window Management        • File System Access          │
│  • Process Control          • System Integration          │
│  • IPC Command Handler      • Security & Permissions      │
└───────────────────────────┬───────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────┐
│                   Tauri Plugins (Rust)                    │
│                   (src-tauri/plugins/)                    │
│                                                           │
│     ┌──────────────────┐        ┌──────────────────┐      │
│     │  Hardware Plugin │        │  LlamaCPP Plugin │      │
│     │                  │        │                  │      │
│     │ • CPU/GPU Info   │        │ • Process Mgmt   │      │
│     │ • Memory Stats   │        │ • Model Loading  │      │
│     │ • System Info    │        │ • Inference      │      │
│     └──────────────────┘        └──────────────────┘      │
└───────────────────────────────────────────────────────────┘

Communication Flow

1. JavaScript Layer: Web App imports Core SDK and Extensions as JavaScript modules
2. All → Backend: Through Tauri IPC using await invoke('command', data)
3. Backend → Plugins: Native Rust integration with direct function calls
4. Response Flow: Plugin → Backend → IPC → Requester → UI updates

Real Example: Loading a Model

When you click “Download Llama 3”:

1. Web App - User clicks download button
2. Download Extension - Handles download logic
3. Tauri Backend - Downloads file to disk
4. LlamaCPP Extension - Prepares model for loading
5. LlamaCPP Plugin - Starts llama.cpp process
6. Hardware Plugin - Detects GPU, optimizes settings
7. Model ready! - User can start chatting

Project Structure

jan/
├── web-app/              # React frontend (what users see)
├── src-tauri/            # Rust backend (system integration)
│   ├── src/core/         # Core Tauri commands
│   └── plugins/          # Tauri plugins (hardware, llamacpp)
├── core/                 # TypeScript SDK (API layer)
├── extensions/           # JavaScript extensions
│   ├── assistant-extension/
│   ├── conversational-extension/
│   ├── download-extension/
│   └── llamacpp-extension/
├── docs/                 # Documentation website
├── scripts/              # Build utilities
├── package.json          # Root workspace configuration
└── Makefile              # Build automation commands

Development Setup

Prerequisites

• Node.js ≥ 20.0.0
• Yarn ≥ 1.22.0
• Rust (for Tauri)
• Make ≥ 3.81

The Easy Way

git clone https://github.com/janhq/jan
cd jan
make dev

See the Build from Source guide for detailed instructions.

How to Contribute

Reporting Bugs

1. Search existing issues

   Check GitHub Issues to avoid duplicates

2. Open a new issue

   If not found, create a new issue

3. Include details

   Provide:

   • System specs (OS, RAM, GPU)
   • Error logs
   • Steps to reproduce
   • Expected vs actual behavior

Suggesting Features

1. Open a new issue with a clear title and description
2. Explain why this enhancement would be useful
3. Include mockups or examples if possible
4. Tag it appropriately (enhancement, feature-request)

Code Contributions

Choose Your Adventure

Frontend UI

Work on web-app/ for:

• React components
• Chat interface
• Settings pages
• UI/UX improvements

Core SDK

Work on core/ for:

• TypeScript APIs
• Extension system
• Type definitions
• Event bus

Extensions

Work on extensions/ for:

• Assistant management
• Conversation handling
• Download logic
• Model integration

Backend

Work on src-tauri/ for:

• Rust backend
• System integration
• IPC commands
• Native plugins

The Process

1. Fork the repository

   Create your own fork of the Jan repository

2. Create a branch

   git checkout -b feature/your-feature-name
   

   Use prefixes:

   • feature/ for new features
   • fix/ for bug fixes
   • docs/ for documentation
3. Make your changes

   • Write clean, documented code
   • Follow code standards (see below)
   • Add tests for new functionality
4. Commit your changes

   git commit -am 'feat: add support for Qwen models'
   

   Follow commit conventions

5. Push to your fork

   git push origin feature/your-feature-name
   
6. Open a Pull Request

   • Target the dev branch (not main)
   • Provide a clear description
   • Reference related issues
   • Wait for review

Code Standards

TypeScript/JavaScript

• TypeScript required - No plain JavaScript for new code
• ESLint + Prettier - Run yarn lint before committing
• Functional components - Use React hooks, not class components
• No any types - Proper typing is required

// Good
function processModel(model: Model): Promise<Result> {
  return api.process(model);
}

// Bad
function processModel(model: any): any {
  return api.process(model);
}

Rust

• Format code - Run cargo fmt before committing
• Clippy checks - Run cargo clippy and fix warnings
• Error handling - Use Result<T, E> pattern
• Documentation - Document all public APIs

// Good
pub fn load_model(path: &Path) -> Result<Model, LoadError> {
    // Implementation
}

// Bad
pub fn load_model(path: &Path) -> Model {
    // Implementation that might panic
}

Git Conventions

Branches

• main - Stable releases only
• dev - Development branch (target this for PRs)
• feature/* - New features
• fix/* - Bug fixes
• docs/* - Documentation updates

Commit Messages

Use conventional commits format:

type(scope): subject

body (optional)

footer (optional)

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• style: - Code style changes (formatting)
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

Examples:

feat: add support for Qwen models
fix: resolve memory leak in model loading
docs: update installation instructions
refactor: simplify extension loading logic

Testing

Run Tests

yarn test                    # All TypeScript tests
cd src-tauri && cargo test  # Rust tests
cd autoqa && python main.py # End-to-end tests

Write Tests

• Add tests for all new features
• Ensure existing tests pass
• Aim for high code coverage

Troubleshooting

Common Issues

Build failures

Check versions:

node --version   # ≥ 20.0.0
yarn --version   # ≥ 1.22.0
rustc --version  # should be installed

Clean and rebuild:

make clean
make dev

Extension not loading

Verify it’s properly registered and built:

ls -la pre-install/*.tgz
yarn build:extensions

Model not working

• Check hardware requirements
• Verify GPU drivers are up to date
• Check system memory availability

Get Help

1. Check troubleshooting docs
2. Ask in Discord #🆘|jan-help
3. Search GitHub Issues
4. Post in GitHub Discussions

Component-Specific Guides

For detailed contribution guides:

• Web App - React UI
• Core SDK - TypeScript SDK
• Extensions - Extension modules
• Tauri Backend - Rust backend
• Tauri Plugins - Hardware plugins

License

Apache 2.0 - By contributing, you agree that your contributions will be licensed under the Apache 2.0 License. See LICENSE for details.

Thank You

We’re building something special - an AI assistant that respects your privacy and runs entirely on your machine. Every contribution, no matter how small, helps make AI more accessible to everyone.

Thanks for being part of the journey. Let’s build the future of local AI together!

Build from Source

Ready to start? Learn how to build Jan from source