JavaClaw

JavaClaw is a Java-based personal AI assistant that runs on your own devices. It acts as a control plane (gateway) for an AI agent that can interact across multiple communication channels, manage tasks, execute shell commands, browse the web, and more — all while keeping your data local.

NOTE: this project is meant as a demo to show the use of JobRunr to the Java community ☕.

Features

• Multi-Channel Support — Telegram (built-in), Chat UI (WebSocket), and an extensible channel architecture for adding more platforms
• Task Management — Create, schedule (one-off, delayed, or recurring via cron), and track tasks as human-readable Markdown files
• Extensible Skills — Drop a SKILL.md into workspace/skills/ and the agent picks it up at runtime
• LLM Provider Choice — Plug in OpenAI, Anthropic, or Ollama (local); switchable during onboarding
• MCP Support — Model Context Protocol client for connecting external tool servers
• Shell & File Access — Agent can read/write files and run bash commands on your machine
• Smart Web Tools — Brave web search and intelligent web scraping
• Background Jobs — Powered by JobRunr with a built-in dashboard at :8081
• Privacy-First — Runs entirely on your own hardware; no data leaves unless you configure an external LLM

Technology Stack

Layer	Technology
Language	Java 25
Framework	Spring Boot 4.0.3, Spring Modulith 2.0.3
LLM	Spring AI 2.0.0-SNAPSHOT (OpenAI, Anthropic, Ollama)
Agent	Spring AI Agent Utils
MCP	Spring AI MCP Client
Jobs	JobRunr 8.5.0
Database	H2 (embedded, file-backed)
Templating	Pebble 4.1.1
Frontend	htmx 2.0.8 + Bulma 1.0.4
Telegram	Telegrambots 9.4.0

Project Structure

JavaClaw/
├── base/           # Core: agent, tasks, tools, channels, config
├── app/            # Spring Boot entry point, onboarding UI, web routes, chat channel
└── plugins/
    └── telegram/   # Telegram long-poll channel plugin

Getting Started

Prerequisites

• Java 25
• Gradle (or use the included ./gradlew wrapper)
• An LLM API key (OpenAI / Anthropic) or a running Ollama instance

Run

./gradlew :app:bootRun

Then open http://localhost:8080/onboarding to complete the guided onboarding.

Onboarding (7 Steps)

1. Welcome — Introduction screen
2. Provider — Choose Ollama, OpenAI, or Anthropic
3. Credentials — Enter your API key and model name
4. Agent Prompt — Customize workspace/AGENT.md with your personal info (name, email, role, etc.)
5. MCP Servers — Optionally configure Model Context Protocol servers
6. Telegram — Optionally connect a Telegram bot (bot token + allowed username)
7. Complete — Review and save your configuration

Configuration is persisted to app/src/main/resources/application.yaml and takes effect immediately.

Workspace

The workspace/ directory is the agent's home:

Path	Purpose
workspace/AGENT.md	System prompt — edit during onboarding or at any time
workspace/INFO.md	Environment context injected into every prompt
workspace/context/	Agent memory and long-term context files
workspace/skills/	Drop a SKILL.md here to add new capabilities
workspace/tasks/	Task files, date-bucketed (yyyy-MM-dd/HHmmss-<state>-<name>.md)
workspace/tasks/recurring/	Cron-scheduled recurring task templates

Task States

todo → in_progress → completed / awaiting_human_input

Channels

Chat (built-in)

Available at http://localhost:8080/chat. Uses WebSocket for real-time delivery and falls back to REST polling when no WebSocket session is active.

Telegram

Configure during onboarding or by setting:

telegram:
  bot-token: <your-bot-token>
  allowed-username: <your-telegram-username>

Skills

Skills extend the agent's capabilities at runtime without code changes. Create a directory under workspace/skills/<skill-name>/ containing a SKILL.md file and the agent will load it automatically via SkillsTool.

Dashboard

JobRunr's job dashboard is available at http://localhost:8081 for monitoring background task execution.

Configuration

Key properties in application.yaml:

Property	Description
agent.workspace	Path to the workspace root (default: file:./workspace/)
agent.onboarding.completed	Set to true after onboarding is done
spring.ai.model.chat	Active LLM provider/model
jobrunr.dashboard.port	JobRunr dashboard port (default: 8081)
jobrunr.background-job-server.worker-count	Concurrent job workers (default: 1)

Running Tests

./gradlew test

Tests cover task management (file naming, JobRunr integration), Telegram channel authorization, and the full Spring context.

License

This project is open-source. See LICENSE for details.