DeepSeek-native Coding Agent — Java implementation

_{🌐 中文 | 한국어 | 日本語}

Features · Architecture · Getting Started · Modules · Development · License

---

Features

• Multi-provider LLM support — 80+ built-in models across 20+ providers (DeepSeek, Anthropic, OpenAI, NVIDIA, OpenRouter, and more)
• Terminal UI (TamboUI) — Ratatui-inspired declarative TUI with sidebar, transcript, composer, footer, modal view stack, command palette, slash commands, SSE streaming, and markdown rendering
• Context compression pipeline — CompactionPlanner/Executor for smart context window management, SeamManager for truncation-aware session continuity
• 9-step config loading pipeline — layered TOML config with env var overrides, validation, and provider resolution (CodeWhale-compatible)
• Layered execution policy engine — deny-always-wins, arity-aware command matching, typed ask rules, session approval cache
• MCP (Model Context Protocol) — full JSON-RPC 2.0 stdio server with 14 methods for tool/resource lifecycle management
• Workflow engine (WhaleFlow) — IR compilation, validation, mock/replay execution, teacher/promotion system
• Spring Boot HTTP server — REST API with bearer-token auth, CORS, OpenAI-compatible chat completions proxy
• Hook event system — pluggable sinks (stdout, JSONL) for lifecycle observability
• Next.js web frontend — bilingual (EN/ZH) community site with live GitHub feed, curated dispatch, and admin panel
• Virtual threads — Project Loom (Java 21+) for lightweight concurrency throughout
• Sealed class + Record types — exhaustive pattern matching matching Rust's enum semantics

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     CLI (picocli)                            │
├─────────────────────────────────────────────────────────────┤
│                  Terminal UI (TamboUI)                       │
│  sidebar │ transcript │ composer │ footer │ modals          │
├─────────────────────────────────────────────────────────────┤
│                     HTTP Server (Spring Boot)                │
│  /healthz  /thread  /app  /prompt  /tool  /jobs  /mcp/*    │
│  /v1/chat/completions                                       │
├──────────┬──────────┬──────────┬──────────┬─────────────────┤
│   Agent  │   Core   │  Tools   │  State   │   WhaleFlow     │
│  (models)│(runtime) │(dispatch)│(SQLite)  │   (workflow)    │
├──────────┼──────────┼──────────┼──────────┼─────────────────┤
│ ExecPolicy│   MCP   │  Hooks   │  Config  │    Secrets      │
│ (security)│(protocol)│(events) │  (YAML)  │  (KeyStore)     │
├──────────┴──────────┴──────────┴──────────┴─────────────────┤
│                       Protocol (shared types)                │
└─────────────────────────────────────────────────────────────┘

Jay is a Java port of the CodeWhale Rust coding agent, maintaining protocol compatibility with the existing Next.js web frontend and Tauri desktop shell. It uses Spring Boot's mature ecosystem to reduce boilerplate while preserving the original's multi-layered architecture.

---

Getting Started

Prerequisites

• Java 21+ — Adoptium or Oracle JDK
• Gradle 9.6+ — included via wrapper (./gradlew); no global Gradle install needed
• Node.js 20+ — for the web frontend (optional)

Build

# Compile all modules (Gradle Wrapper included — no Gradle install needed)
./gradlew compileJava

# Run all tests
./gradlew test

# Build the HTTP server
./gradlew :server:bootJar

Run the server

# Start the HTTP server on port 8080
java -jar server/build/libs/server-0.1.0.jar

# With custom port
java -jar server/build/libs/server-0.1.0.jar --server.port=3000

Quick health check

curl http://localhost:8080/healthz
# {"status":"ok","protocol":"v2","service":"jay-app-server"}

Run the TUI

./gradlew :tui:bootRun

Run the web frontend

cd web
npm install
npm run dev         # http://localhost:3000

---

Modules

Module	Description	Key Types
protocol	Shared data types, JSON serialization records	ThreadRequest, AppRequest, EventFrame, ToolPayload
agent	Model registry, provider resolution	ModelRegistry, ModelInfo, ModelResolution
core	Central runtime, thread/job management	AgentRuntime, ThreadManager, JobManager
tools	Tool registration, dispatch, concurrency control	ToolRegistry, ToolHandler, InputExtractors
execpolicy	Layered security policy engine	ExecPolicyEngine, BashArityDict, Ruleset
mcp	MCP JSON-RPC 2.0 protocol stack	McpManager, StdioMcpServer, JsonRpcDispatcher
hooks	Lifecycle event dispatch system	HookEvent, HookDispatcher, HookSink
state	SQLite persistence with Flyway migrations	StateStore, ThreadRepository, MessageRepository
config	9-step config loading pipeline, TOML parsing, env overrides, validation	ConfigLoader, ConfigValidator, EnvOverrideApplier, JayConfig
secrets	KeyStore-based credential management	SecretsManager
server	Spring Boot HTTP/WebSocket server	AppController, ChatCompletionsController
cli	Picocli command-line interface	JayCli
jayflow	Workflow engine (IR, compiler, executor)	WorkflowConfig, WhaleFlowEngine
tui	Terminal UI — TamboUI, SSE streaming, context compaction, seam management, markdown rendering	TuiEngine, TuiView, CompactionPlanner, CompactionExecutor, SeamManager, StreamingSseClient, MarkdownParser
web	Next.js bilingual community site	Pages, components, API routes, cron jobs
ide-plugin	IntelliJ IDE plugin	JayPlugin
release	Release metadata and update checking	ReleaseChecker, ReleaseFetcher

---

Development

Code quality

The project uses Checkstyle with a configuration based on Apache SkyWalking's code standards. Configuration lives at config/checkstyle/checkstyle.xml.

# Run checkstyle across all modules
./gradlew checkstyleMain

# Checkstyle + compile in one pass
./gradlew checkstyleMain compileJava

Running tests

# All modules
./gradlew test

# Specific module
./gradlew :execpolicy:test
./gradlew :mcp:test
./gradlew :server:test
./gradlew :hooks:test
./gradlew :tui:test

Code coverage

Coverage is measured with JaCoCo. Every ./gradlew test run produces per-module reports at build/reports/jacoco/test/. To generate an aggregated report across all modules:

# Run tests + aggregated coverage report (XML, HTML, CSV)
./gradlew test jacocoAggregateReport

# Open the HTML report
open build/reports/jacoco/jacocoAggregateReport/html/index.html

Aggregate report output goes to build/reports/jacoco/jacocoAggregateReport/.

Key conventions

• Java 21 sealed interfaces + records for algebraic data types
• Jackson @JsonTypeInfo / @JsonSubTypes for polymorphic JSON serialization
• Spring Boot auto-configuration with @ConfigurationProperties
• Virtual threads via Executors.newVirtualThreadPerTaskExecutor()
• TamboUI declarative TUI framework (Ratatui-inspired) for terminal rendering
• Constructor injection — no @Autowired on fields
• JUnit Jupiter 5.11 with standalone MockMvc for controller tests
• Checkstyle 10.21.1 with SkyWalking-style rules for consistent code style

Module dependency graph

protocol         (no internal deps)
execpolicy       → protocol, tools
config           → (no internal deps)
secrets          → config
agent            → protocol
state            → protocol
tools            → protocol
mcp              → protocol, tools
hooks            → protocol
jayflow          → core, protocol
tui              → core, protocol, agent, tools, state, hooks, config
cli              → core, protocol
server           → core, protocol, execpolicy, tools, agent
core             → protocol, agent, tools, execpolicy, config, state
web              (standalone — Next.js frontend, depends on server REST API)

---

Technology Stack

Layer	Technology
Language	Java 21 LTS (Virtual Threads)
Build	Gradle 9.6 (Kotlin DSL)
Framework	Spring Boot 3.4.7
Terminal UI	TamboUI 0.3.0 (Panama backend)
Web Frontend	Next.js 15 + Tailwind CSS + Cloudflare Workers
HTTP Server	Tomcat (embedded)
JSON	Jackson 2.18
Database	SQLite via JDBC + Flyway
CLI	Picocli
Testing	JUnit Jupiter 5.11 + MockMvc + JaCoCo
Security	JDK KeyStore + AES-GCM
Code Quality	Checkstyle 10.21 (SkyWalking rules)

---

License

MIT © 2026 Jay Contributors

---

_{Built with ❤️ by the Jay team. Protocol-compatible with the CodeWhale ecosystem.}