# JavaClaw **Repository Path**: japp/JavaClaw ## Basic Information - **Project Name**: JavaClaw - **Description**: No description available - **Primary Language**: Unknown - **License**: LGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-14 - **Last Updated**: 2026-04-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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 was originally created as a demo to show the use of JobRunr, JavaClaw is now an open invitation to the Java community, let’s build the future of Java-based AI agents together ☕. ## Features - **Multi-Channel Support** — Chat UI (WebSocket), Telegram, Discord, and an extensible plugin-based channel architecture - **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 | | Discord | JDA 6.1.1 | | 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/ ├── brave/ # Brave web search integration ├── discord/ # Discord Gateway channel plugin ├── playwright/ # Browser automation tools └── 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](https://ollama.com) instance ### Run ```bash ./gradlew :app:bootRun ``` You can also build a docker image and use it as follows (from the cloned repo): ```bash ./gradlew app:jibDockerBuild docker run -it -p 8080:8080 -p:8081:8081 -v "$(pwd)/workspace:/workspace" jobrunr.io/javaclaw ``` Then open [http://localhost:8080/onboarding](http://localhost:8080/onboarding) to complete the guided onboarding. ### Onboarding 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. **Channel/Tool Plugins** — Optional steps such as Telegram, Discord, and other plugin-provided setup 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--.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](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: ```yaml agent: channels: telegram: token: username: ``` ### Discord Configure during onboarding or by setting: ```yaml agent: channels: discord: token: allowed-user: ``` ## Skills Skills extend the agent's capabilities at runtime without code changes. Create a directory under `workspace/skills//` 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](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 ```bash ./gradlew test ``` Tests cover task management, Telegram and Discord channel authorization/flow, onboarding steps, and the full Spring context. ## More info? [Release Demo Video](https://www.youtube.com/watch?v=_n9PcR9SceQ) [Website](https://clawrunr.io/) [Release Blog post](https://www.jobrunr.io/en/blog/clawrunr/) ## License This project is open-source. See [LICENSE](license.md) for details.