Chat4J

Lightweight desktop AI chat client built with Java 21, Swing, and Maven. Polished with FlatLaf and bundled IntelliJ themes. Chat transcripts can use native system WebViews via SwingWebView, Chromium through jcefmaven / JCEF, or a Swing fallback.

Quick start

mvn clean compile
mvn exec:java

First run from release artifacts

Chat4J release artifacts are currently unsigned and not notarized. macOS Gatekeeper and Windows SmartScreen may warn or block the first launch. Only run artifacts you downloaded from the official GitHub Releases page, and verify checksums before bypassing operating-system warnings.

Download SHA256SUMS.txt alongside the artifact you plan to run, then verify it from the download directory:

# macOS / Linux; replace the filename with the artifact you downloaded
artifact="Chat4J-<version>.dmg"
awk -v artifact="$artifact" '$2 == artifact { print }' SHA256SUMS.txt | shasum -a 256 -c -

# Windows PowerShell; replace the filename with the artifact you downloaded
$artifact = "Chat4J-<version>.msi"
$parts = (Get-Content SHA256SUMS.txt | Where-Object { $_ -match "\s$([regex]::Escape($artifact))$" }) -split '\s+', 2
$actual = (Get-FileHash -Algorithm SHA256 $artifact).Hash.ToLowerInvariant()
if ($actual -ne $parts[0]) { throw "Checksum mismatch: $artifact" }

macOS

If macOS says Chat4J “cannot be opened” or is from an unidentified developer:

1. Open Finder and locate Chat4J.app.
2. Control-click / right-click the app and choose Open.
3. Click Open again in the confirmation dialog.

If the app is still blocked, open System Settings → Privacy & Security, scroll to the Gatekeeper message for Chat4J, and click Open Anyway.

Advanced Terminal alternative:

xattr -dr com.apple.quarantine /Applications/Chat4J.app
open /Applications/Chat4J.app

Adjust the path if you installed Chat4J somewhere else.

Windows

If Windows SmartScreen appears:

1. Click More info.
2. Click Run anyway.

If Windows marks the downloaded file as blocked:

1. Right-click the .msi or .exe and choose Properties.
2. On the General tab, check Unblock if present.
3. Click Apply, then run the installer again.

Build & test

mvn clean package
mvn test

Run packaged jar:

java --enable-preview -jar target/chat4j-<version>.jar

Dependency and security audits

# Generate JaCoCo coverage report and enforce core non-UI coverage gates
mvn -Pcoverage verify

# Generate CycloneDX SBOM files in target/bom.xml and target/bom.json
mvn -Psbom verify

# Run OWASP Dependency-Check; fails on CVSS 7+
NVD_API_KEY=your-nvd-api-key mvn -Pdependency-audit verify

# Check available dependency/plugin updates
mvn versions:display-dependency-updates versions:display-plugin-updates

Dependabot is configured in .github/dependabot.yml for Maven and GitHub Actions updates. The scheduled Security Audit workflow runs OWASP Dependency-Check weekly and uploads HTML/JSON reports. Configure a repository secret named NVD_API_KEY to avoid public NVD API rate limits during vulnerability data updates.

What it does

• Desktop chat UI (Swing + FlatLaf)
• Multi-provider model selection
• Streaming assistant responses
• Local history/settings persistence (SQLite by default, optional H2, Flyway migrations)
• Agent Mode with local workspace tools
• Speech to Text with cloud providers plus local Whisper.cpp/Vosk model management

Supported providers

API-key providers (Settings token vault or env vars)

• ANTHROPIC_API_KEY
• GEMINI_API_KEY (alias: GOOGLEAI_API_KEY)
• OPENAI_API_KEY
• PERPLEXITY_API_KEY
• OPENROUTER_API_KEY
• GROQ_API_KEY
• ELEVENLABS_API_KEY (speech-to-text/text-to-speech)
• DEEPGRAM_API_KEY (speech-to-text/text-to-speech)
• ASSEMBLYAI_API_KEY (speech-to-text)
• DEEPSEEK_API_KEY
• MISTRAL_API_KEY
• XAI_API_KEY

Whisper.cpp local speech-to-text does not require an API key after downloading a local model.

API tokens

API-key providers can use tokens saved in Settings or environment variables. A token saved in Settings is stored in Chat4J's app-local encrypted token vault and takes precedence over environment variables. This local encryption protects against casual file browsing, but it is not OS keychain storage; anyone who can read both Chat4J secret files can decrypt saved tokens.

Environment variables remain supported. Replace sk-... with your real API key. Restart Chat4J after changing environment variables.

macOS / Linux (bash or zsh)

For the current terminal session:

export OPENAI_API_KEY="sk-..."
mvn exec:java

To make it persistent, add the export line to your shell profile:

# zsh, default on modern macOS
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

# bash
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc

Reload the profile or open a new terminal:

source ~/.zshrc   # or: source ~/.bashrc

On macOS, apps launched from Finder/Dock may not inherit terminal variables. Chat4J tries to load your login shell environment, but if keys are still missing, either launch Chat4J from Terminal or set the variable for GUI apps:

launchctl setenv OPENAI_API_KEY "sk-..."

Windows PowerShell

For the current PowerShell session:

$env:OPENAI_API_KEY = "sk-..."
mvn exec:java

To make it persistent for your Windows user account:

setx OPENAI_API_KEY "sk-..."

Close and reopen PowerShell, Command Prompt, or Chat4J after running setx.

Windows Command Prompt

For the current Command Prompt session:

set OPENAI_API_KEY=sk-...
mvn exec:java

To make it persistent:

setx OPENAI_API_KEY "sk-..."

OAuth providers

• OpenAI Codex
• GitHub Copilot

Local providers

• LM Studio — OpenAI-compatible server at http://localhost:1234/v1 (no API key required)
• Ollama — OpenAI-compatible endpoint at http://localhost:11434/v1 (no API key required)

Documentation

• docs/README.md — full documentation index

Packaging

Native installers are built with jpackage via Maven profiles. Each profile must run on the target OS (cross-packaging is not supported).

Use OS-specific profiles:

# macOS (.dmg)
mvn -Pjpackage-mac verify

# Windows (.msi) — requires WiX Toolset 3.x
mvn -Pjpackage-win verify

# Linux (.deb) — requires dpkg
mvn -Pjpackage-linux verify

Output artifacts are written to target/dist/.

Release automation

GitHub Actions builds unsigned release artifacts for version tags and manual reruns:

git tag v26.6.13
git push origin v26.6.13

The release workflow publishes the shaded jar, macOS .dmg, Windows .msi, Linux .deb, SBOM files, and SHA-256 checksums.

License

Apache License 2.0 — see LICENSE.