Tools
FocusClaw
By Agent-native task management for humans and AI agents, built around a local-first API, SQLite storage, projects, calendar views, backups, and plugin-ready integrations.
Install
npm install
./start.shREADME
# FocusClaw
Task context for OpenClaw, Grok Build, Hermes, and humans.
FocusClaw is a local-first task app and REST API backed by SQLite. It gives humans a fast web interface while giving connected agents a structured task source of truth they can read, update, and coordinate through.
## Why FocusClaw Exists
Most task tools are built for humans first. Agents can sometimes use them, but usually through brittle UI scraping, ad hoc notes, or one-off integrations.
FocusClaw is the task layer for the OpenClaw workflow, with Hermes support through the same local API. The goal is simple: one durable place for projects, tasks, comments, attachments, due dates, and handoffs.
FocusClaw is built around a shared task model:
- Projects, tasks, subtasks, comments, tags, due dates, priorities, and owner labels
- A web app for normal human task management
- OpenClaw plugin tools, a portable MCP server, and a REST API for other agent stacks
- Local SQLite storage with snapshots and encrypted exports
Owner labels such as `user`, `agent`, and `unassigned` are coordination labels only. They do not trigger background execution, scheduled runs, permissions, or autonomous workflows.
## Status
FocusClaw is in early development. The self-hosted app is usable locally, and the private Tailscale access path works for devices inside the same tailnet. See [SPEC.md](./SPEC.md) for scope and roadmap.
## Stack
- Frontend: React 19, Vite, Tailwind CSS
- Backend: Fastify, SQLite, Drizzle ORM
- Storage: local SQLite database at `data/focusclaw.db`
- Agent access: OpenClaw plugin tools, a portable stdio MCP server, and the local REST API
- Deployment: local-first self-hosting, optional private Tailscale access
## Quick Start
Local development is the default path.
Requires Node.js `^20.19.0` or `>=22.12.0`.
```bash
git clone https://github.com/emiliojohann/FocusClaw.git
cd FocusClaw
npm install
./start.sh
```
The default local URLs are:
- Web app: `http://127.0.0.1:5173`
- API: `http://127.0.0.1:3001`
- API health check: `http://127.0.0.1:3001/health`
`./start.sh` creates the local `data/` directory and points the API at `data/focusclaw.db`.
FocusClaw includes a local Agent Automation API for trusted agents and scripts. It lets OpenClaw, Hermes, and other local tools read projects, create tasks, update work, and mark tasks complete without controlling the browser UI. See [Agent Automation API](./docs/agent-automation-api.md) for the technical contract. For Hermes-specific setup guidance, see [Hermes Integration](./docs/hermes-integration.md).
For Grok Build and other MCP clients, see [MCP Integration](./docs/mcp-integration.md). The MCP server is bundled in `packages/mcp` and connects to the same local REST API; it does not read SQLite directly or open another network port.
## Common Workflows
### Agent + Integration Usage
FocusClaw supports simple read-only plain-text status commands through OpenClaw, Hermes, or any connected messaging integration. Slash commands are not required for the MVP.
Use these plain-text triggers for quick status:
- `focusclaw help` - explain the available commands
- `focusclaw today` - open tasks due today
- `focusclaw overdue` - overdue open tasks
- `focusclaw week` - open tasks due this week
- `focusclaw project Launch Plan` - open tasks for one project
Status output is compact by default: tasks are grouped by project and show title plus due-date/status signal. Tags, descriptions, and task IDs stay hidden unless an agent/tool caller explicitly asks for detailed output.
Add, edit, delete, and complete actions stay as agent tool actions using natural language. Examples:
- `Add a task to Launch Plan: prepare screenshots, due Friday.`
- `Start the onboarding checklist.`
- `Move the onboarding checklist back to To Do.`
- `Mark the onboarding checklist complete.`
- `Delete the task about drafting the first content batch.`
OpenClaw and Hermes should find tasks by title/project before asking users for task IDs.
### Projects And Tasks
Create projects, add tasks, set priority, choose due dates, assign owner labels, move work between To Do and In Progress, and mark work complete from the web app.
Use **Select tasks → Reschedule** to apply Today, Tomorrow, seven days from today, or a custom calendar date to selected tasks, including across projects. Apply changes only due dates (and removes the Today highlight when scheduling off today); it does not move projects, complete/reopen tasks, or change recurrence settings or unselected subtasks. Cancel and failed requests retain the selection. The API is `POST /api/tasks/bulk-reschedule` with `{ "taskIds": ["<uuid>"], "dueDate": "YYYY-MM-DD" }`: 1–5000 IDs, deduplicated, real dates in years 1000–9999, saved at server-local end of day. Invalid input returns 400; unknown IDs return 404 with no changes. Success returns `rescheduledCount`, `clearedHighlightCount`, and the stored ISO `dueDate`.
OpenClaw and Hermes can work with the same records through the local Agent Automation API. This keeps human task planning and agent execution context in one structured place.
### Universal Tags
Tags are workspace-wide labels that can be used across every project. Add tags while editing a task, or manage saved tags from **Settings -> Tag Management**. If the project filter is set to **All**, filtering by a tag shows matching tasks from all projects.
### Views, Filters, And Calendar
The task dashboard supports list/grid views, priority-aware manual drag-and-drop ordering, priority/due-date/created-date sorting, tag filters, owner filters, and due-date filters such as due today, due this week, past due, no date, and completed. Drag the grip or move the desktop task card by at least 4px and the dashboard automatically switches to **Sort: Manual**; normal clicks still open Task Details. FocusClaw captures from mouse-down and adds a window-level fallback so one-step fast gestures cannot outrun activation or release. The final release position determines the drop, gaps snap to the nearest valid same-priority card, and list collision follows the dragged card's leading edge for earlier vertical snapping. Switching list/grid safely resets any unfinished gesture. Reorder saves run sequentially in the background without locking later drags. On mobile, a 0.5-second press anywhere on a task also enters Manual sort and starts a full-card drag; ordinary taps and scrolling remain unchanged. The GPU-accelerated whole-card preview follows the pointer smoothly on desktop and touch devices. Priority groups stay in priority order, while tasks can be placed anywhere inside their own priority group. Manual order persists across refreshes and works in single-project and **Project: All** views.
The calendar view shows tasks with due dates and can optionally include completed tasks. Default task and calendar view preferences can be changed from **Settings -> Default View Settings**.
### Comments And Subtasks
Open a task to edit details, add comments, and create subtasks. Comments keep discussion and handoff context attached to the task record so humans, OpenClaw, and Hermes can read the same history.
Subtasks can be viewed in Manual, Priority, Title A-Z, or Incomplete First order. Manual order is saved per parent task: drag the grip on desktop, use Up/Down while the grip is focused, or drag the 44px grip on mobile. A 0.5-second mobile long press on a subtask row also starts a floating drag preview; a normal swipe still scrolls. Editing a subtask gives its title a full-width input with priority and Save/Cancel below it.
### Descriptions And Attachments
Task descriptions use a simple Live/Code editor. Live is the default editable rendered view; Code shows the raw Markdown for agents and developers.
Task attachments are local references only. Use **Select a file** in task details to attach a local file; FocusClaw stores metadata and the local file path, infers file/image/PDF type, and opens the original file through the local API. FocusClaw does not upload, copy, host, or delete attached files. URL attachments are intentionally not supported.
### CSV Export
Use **Settings -> Tasks Export** to download a CSV of all tasks across all projects, including completed tasks and project names.
### Backups
Use **Settings -> Local Snapshots & Encrypted Exports** to create local snapshots, schedule automatic daily snapshots, restore a snapshot, or download an encrypted backup file.
Local snapshots are stored at `~/.focusclaw/backups`. Encrypted exports require a passphrase of at least 12 characters. Restores and imports create a safety backup before replacing the current workspace data.
## Advanced: Private Tailscale Access
FocusClaw can run on one host machine and be accessed from another device in the same private Tailscale tailnet without exposing FocusClaw to the public internet.
The recommended shape is:
```text
Laptop browser
-> Tailscale Serve HTTPS URL
-> host machine localhost web app
-> host machine localhost API
-> host machine SQLite database
```
FocusClaw stays bound to localhost:
- Web app: `http://127.0.0.1:5173`
- API: `http://127.0.0.1:3001`
Tailscale Serve publishes the web app privately on a dedicated HTTPS port:
```text
https://<HOST_TAILSCALE_DNS_NAME>:8443/
```
This keeps the root Tailscale hostname free for other apps while giving FocusClaw its own URL.
### Start With Tailscale
Install and sign in to Tailscale on the host machine and on each device that should access FocusClaw. Then run:
```bash
./start.sh --tailscale
```
By default, Tailscale mode:
- Keeps the API bound to `127.0.0.1:3001`
- Keeps the web app bound to `127.0.0.1:5173`
- Runs `tailscale serve --bg --yes --https 8443 5173`
- Prints the private FocusClaw URL
Example:
```text
https://your-host.your-tailnet.ts.net:8443/
```
The web app uses `/api`, so API calls stay on the same browser origin and are proxied back to the local API server.
### Custom Tailscale URL Or Port
To show a
... (truncated)
tools
Comments
Sign in to leave a comment