Askimo Development & Customization Guide

Welcome to the Askimo development hub. These guides show you how to extend and customize Askimo—whether you’re adding a new CLI command, integrating a new AI model provider, building reusable prompt recipes, or contributing localization for a new language.

Project Structure

Askimo uses a monorepo architecture with three main modules:

askimo/
├── cli/              # Command-line interface (GraalVM Native Image)
├── desktop/          # Desktop application (Compose Multiplatform)
├── desktop-shared/   # UI shared component (Compose Multiplatform)
├── shared/           # Shared core logic, models, and providers
└── detekt-rules/     # Detekt custom rules coding convention

Module Overview

• cli/: Terminal-based REPL for interactive AI conversations and automation scripts. Built with GraalVM Native Image for fast startup and single-binary distribution. No active support to the new user. Internal use only

• desktop/: Native desktop application with Material Design 3 UI. Built with Compose Multiplatform for a modern, responsive user experience.

• desktop-shared/: Native ui components with Material Design 3 UI.

• shared/: Core business logic shared between CLI and Desktop, including:

• AI provider implementations (OpenAI, Anthropic, Gemini, X AI, Ollama)

• Chat models and message handling

• Configuration and parameter management

• Security utilities

What You Can Customize

Desktop Customization

• Localization: Add support for new languages (see Contributing a New Locale)
• UI Components: Extend the Compose UI with new views and dialogs
• Themes: Customize colors and typography

Shared Customization

• Model Providers: Plug in any chat model API via a factory
• Parameters & Presets: Tune style, verbosity, and provider-specific settings
• Chat Models: Implement custom model behaviors

Prerequisites

Before extending Askimo, make sure you can build and run it locally:

git clone git@github.com:askimo-ai/askimo.git
cd askimo
./gradlew build

Requirements:

• JDK 25 or higher
• Gradle 9.x or higher

Development Conventions

• Keep public APIs documented (KDoc for Kotlin classes).
• Use clear, emoji-enhanced user feedback (✅, ⚠️, ❌, 🧹, 📦).
• Favor small, focused handlers/factories.
• Fail fast with helpful messages when configuration is missing.
• Avoid hardcoding secrets—use parameters (e.g., api_key).

Code Formatting

Askimo uses Spotless with ktlint to enforce consistent formatting. All code must be formatted before committing.

Install the Git Hook (recommended)

Run the one-time setup script to install a pre-commit hook that automatically formats your code before every commit:

./tools/git/pre-commit

After installation, every git commit will:

1. Run ./gradlew spotlessApply to auto-format all changed files
2. Re-stage any files that were reformatted
3. Proceed with the commit

Manual Formatting

If you prefer not to use the hook, you can format manually before committing:

./gradlew spotlessApply   # auto-fix formatting
./gradlew spotlessCheck   # verify only (no changes)

CI Safety Net

Even without the local hook, every pull request runs spotlessCheck via GitHub Actions. PRs with formatting violations are blocked until fixed. Install the hook to avoid the round-trip.

Tip

To skip the hook in an emergency: git commit --no-verify

Building and Testing

Build All Modules

Build the entire project:

./gradlew build

Build specific modules:

./gradlew :desktop:build  # Desktop only
./gradlew :shared:build   # Shared library only
./gradlew :desktop-shared:build   # Shared UI library only

Run the Applications

Desktop:

./gradlew :desktop:run

Testing Your Changes

Run the test suite for all modules:

./gradlew test

Desktop: Creating Distributable Package

Create platform-specific packages:

# Create distributable packages (DMG for macOS, MSI for Windows, DEB/RPM for Linux)
./gradlew :desktop:packageDistributionForCurrentOS

# Or create a runtime image
./gradlew :desktop:createDistributable

The packages will be in desktop/build/compose/binaries/.

Testing Your Changes in Context

Testing Desktop Features

# Start the desktop app
./gradlew :desktop:run

# Navigate through:
# - Chat interface
# - Settings dialog
# - Session management
# - Localization (if you added a new locale)

Feedback & Contribution

If you build a new provider or command that others may benefit from:

1. Fork the repo.
2. Add your feature + docs under this section.
3. Open a pull request following CONTRIBUTING.md.

Happy hacking! 🚀