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)
├── shared/           # Shared core logic, models, and providers
└── docs/             # Documentation

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.

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

• 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

CLI Customization

• Commands: Add new :yourcommand interactions in the REPL
• Recipes: Create reusable YAML-based prompt workflows
• Projects & RAG: Index local codebases for retrieval-augmented chat

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:haiphucnguyen/askimo.git
cd askimo
./gradlew build

Requirements:

• JDK 21 or higher
• Gradle 8.x or higher
• For GraalVM Native Image (CLI): GraalVM distribution

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).

Building and Testing

Build All Modules

Build the entire project:

./gradlew build

Build specific modules:

./gradlew :cli:build      # CLI only
./gradlew :desktop:build  # Desktop only
./gradlew :shared:build   # Shared library only

Run the Applications

CLI (Development Mode):

./gradlew :cli:run

Desktop:

./gradlew :desktop:run

Testing Your Changes

Run the test suite for all modules:

./gradlew test

CLI: Building Native Image

The CLI can be built as a GraalVM Native Image for single-binary distribution. This is ideal for CLI tools: ultra-fast cold startup, lower memory footprint, simpler installation (just drop the askimo executable in PATH), reduced attack surface (no dynamic classloading), and predictable runtime behavior.

Benefits at a glance:

• 🚀 Startup speed: Native image avoids JVM warm-up
• 📦 Single file distribution: Easier for Homebrew, archives, Docker slim images
• 🧠 Lower memory: Only reachable code is compiled in; smaller RSS for short-lived commands
• 🔒 Security: Fewer moving parts (no runtime bytecode loading)

Build steps:

# Ensure you have a GraalVM distribution compatible with the Gradle build.
# (If using SDKMAN or Homebrew, set JAVA_HOME accordingly.)
./gradlew :cli:nativeCompile

The resulting executable will appear here:

ls cli/build/native/nativeCompile/askimo
./cli/build/native/nativeCompile/askimo --help

Distribute it by copying cli/build/native/nativeCompile/askimo into a release archive or a package manager formula. End users can run it directly without installing Java.

Troubleshooting:

• If the native build fails due to missing resources, check cli/src/main/resources and reflection config.
• Increase memory for the build if needed:

export JAVA_TOOL_OPTIONS="-Xmx4G"
./gradlew :cli:nativeCompile

• On Linux distributions without glibc, consider building inside a container matching target libc.

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 CLI Commands

# Start the CLI
./gradlew :cli:run

# Test commands
askimo> :yourcommand
askimo> :set-provider YOUR_PROVIDER
askimo> :set-param api_key sk-***
askimo> :models
askimo> :set-param model my-model
askimo> Explain vector embeddings in 2 sentences.

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! 🚀