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, and slash commands
• 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 (run gradle wrapper first) or install via Homebrew (brew install gradle)
• Node.js 20+ — for the web frontend (optional)

Build

# Compile all modules
gradle compileJava

# Run all tests
gradle test

# Build the HTTP server
gradle :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

gradle :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	Spring @ConfigurationProperties	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, modals, command palette	TuiEngine, TuiView, AppState, CommandPalette
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
gradle checkstyleMain

# Checkstyle + compile in one pass
gradle checkstyleMain compileJava

Running tests

# All modules
gradle test

# Specific module
gradle :execpolicy:test
gradle :mcp:test
gradle :server:test
gradle :hooks:test
gradle :tui:test

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