FocusSpaceFocusSpace
Home

FocusSpace for agents

Last updated August 17, 2026

FocusSpace is fully open source

Every line of code — including exactly how your data is stored and handled — is public. Read it, audit it, self-host it, or contribute on GitHub.

View on GitHub

FocusSpace is a Pomodoro timer, task board, and focus analytics app. Agents can do everything a human can — board CRUD, timer control, music, settings, and rich analytics — over MCP.

If you are a human talking to an agent, paste this exact line:

read this and setup focusspace for me https://focusspace.live/for-agents

Agents should fetch the machine-readable guide at /for-agents.md. The skill lives in the GitHub repo under skills/focusspace/.

Supported agents

Today: Hermes and OpenClaw only. iOS and Android apps are planned. Other agents are not supported yet.

Local-only setup

Agent setup is individual self-host: a SQLite file at ~/.focusspace/focusspace.db, no login, one implicit user. Per-user auth for this mode is coming later.

Run the app with npm run dev / npm start or with Docker — both are the same local SQLite mode. Prefer npm when Node 20+ is installed; otherwise use Docker. There is nothing to configure beyond local mode.

  1. Create ~/.focusspace (the app also creates the database on first boot).
  2. Clone EntangledQuantum/focusspace or reuse an existing checkout.
  3. Set FOCUSSPACE_MODE=local and NEXT_PUBLIC_FOCUSSPACE_MODE=local in .env.local.
  4. Start the app and open http://127.0.0.1:3000 — click Open FocusSpace.
  5. Register MCP: HTTP http://127.0.0.1:3000/api/mcp or stdio npx tsx scripts/mcp-stdio.ts.
  6. Call get_workspace_state before any other tool.

How agents should behave

  • Always call get_workspace_state first.
  • After creating a task, ask if you want the timer started. Never auto-start.
  • Auto-decompose large tasks into subtasks when you did not give any.
  • Tools: get_workspace_state, board, timer, music, settings, analytics_*, confirm_action, reset_task_progress.

Coming soon

  • Per-user auth for this local mode
  • iOS and Android apps
  • Support for more agents

Links