Documentation

Everything you need to set up and use dorabot: your 24/7 self-learning AI agent with persistent memory, autonomous goals, and multi-channel messaging.

Getting Started

Installation

Download the latest release from GitHub Releases or click "Download for macOS" on the homepage. Open the DMG and drag dorabot to your Applications folder.

dorabot is a signed and notarized macOS app. It runs entirely on your machine with no cloud relay.

First launch

On first launch, the onboarding flow will walk you through:

Setting your AI provider API key (Claude, OpenAI, or MiniMax)
Telling the agent who you are (saved to USER.md)
Defining the agent's personality (saved to SOUL.md)

All configuration is stored locally in ~/.dorabot/.

Requirements

macOS (Apple Silicon or Intel)
An API key for Claude (Anthropic) or OpenAI Codex
Node.js 22+ (for CLI / development mode)

Workspace

The workspace is a set of markdown files the agent loads every session. They live in ~/.dorabot/workspace/ and are fully user-editable.

SOUL.md

The agent's persona and tone. Keep it short (5-10 lines). This shapes how the agent communicates.

USER.md

Who you are: your name, goals, context, communication style. The agent reads this to understand you.

MEMORY.md

Persistent facts and preferences. The agent updates this as it learns about you. Capped at 500 lines.

AGENTS.md

Optional agent-specific instructions. Use this for specialized behavior overrides.

Edit these files from the desktop app's Soul tab, or directly in your editor. Changes take effect on the next session.

Memory

dorabot has two layers of memory: curated working memory and detailed daily journals.

Working memory (MEMORY.md)

The agent maintains MEMORY.md with stable facts: your preferences, active projects, decisions, and context. This is loaded every session and kept under 500 lines.

Daily journals

Detailed logs of what the agent did, learned, and found each day. Stored at ~/.dorabot/workspace/memories/YYYY-MM-DD/MEMORY.md with timestamped entries. The 3 most recent journals are loaded into context automatically.

Memory search

Full-text search (SQLite FTS5) across all past conversations. The agent can search by query, channel, origin (pulse, scheduled task, desktop, telegram, whatsapp), and date range.

// Example: search for past conversations about a topic
memory_search({ query: "deployment pipeline", after: "2026-03-01" })

Goals & Tasks

The planning pipeline lets the agent propose, plan, and execute work autonomously with human approval gates.

Goals

High-level outcomes with short, durable titles. Goals track status: active, paused, or done. The agent can propose goals based on context, or you can create them directly.

Tasks

Concrete work items linked to goals. Every task follows a status flow:

planning→planned→approved→in_progress→done

The agent writes a detailed plan (PLAN.md) for each task before submitting it for approval. You review and approve from the desktop app or Telegram.

Plan format

Each task plan includes:

Objective: what the task achieves
Context: background and dependencies
Execution plan: step-by-step approach
Risks: what could go wrong
Validation: how to verify success

Research

The agent creates and maintains structured research items on topics you're investigating. Each item is a markdown file with YAML frontmatter stored in ~/.dorabot/research/.

How it works

Research items have a title, topic, content, tags, and sources. They can be active, completed, or archived. The agent creates research items when exploring a topic and updates them as it learns more.

All research is full-text indexed via SQLite, so the agent can search across all items.

Messaging

Connect dorabot to your messaging channels. Same agent, same memory, same context, any channel.

Connect via bot token. DM and group support. Inline keyboard for task approvals. Markdown rendering.

Connect via QR code. DM and group support. Send text, photos, voice, documents.

Slack

Connect via bot token. Channels and DMs. Thread-aware responses.

Session keys

Each conversation is identified by a session key: channel:chatType:chatId. For example, telegram:dm:123456 or whatsapp:group:xyz@g.us. The agent maintains full context across all channels.

Tool approval

When the agent wants to take an action on a messaging channel, it goes through a 3-tier approval system:

Auto-allow: trusted tools run immediately
Notify: you're told before execution
Require approval: you must confirm (5-minute timeout)

Browser Automation

dorabot includes full browser automation via Playwright and Chrome DevTools Protocol. It uses a persistent Chrome profile, so it's already logged into your accounts.

Capabilities

37+ browser actions including:

Navigate, reload, go back/forward

Click, double-click, hover, drag

Type, fill forms, select dropdowns

Take screenshots and DOM snapshots

Execute JavaScript in page context

Upload files, handle dialogs

Inspect console logs and network

Export pages as PDF

Persistent profile

The browser profile lives at ~/.dorabot/browser/profile/. Since it's your real Chrome profile, the agent can access any site you're already logged into: dashboards, admin panels, internal tools.

Scheduling

dorabot uses RFC 5545 iCal RRULE scheduling for recurring tasks, reminders, and the autonomy pulse.

Autonomy pulse

The autonomy pulse is a recurring background task (configurable: 15m, 30m, 1h, 2h) where the agent wakes up and runs through its priority loop:

Advance in-progress tasks
Monitor things (deployments, PRs, prices)
Follow up with you
Handle blockers
Research and prepare
Propose goals and tasks
Create momentum

Scheduled items

Create events, todos, and reminders with full RRULE support. Timezone-aware with automatic DST handling. Syncs with Apple Calendar so items show up on your Watch and iPhone.

// Daily standup reminder at 9am PST
schedule({
  summary: "Daily standup",
  message: "Time for standup. Check goals and tasks.",
  dtstart: "2026-03-01T09:00:00",
  rrule: "FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0",
  timezone: "America/Los_Angeles"
})

Skills

Skills are markdown files with instructions that get injected into the agent's context when relevant. They give the agent specialized knowledge for specific tasks.

Built-in skills

githubPR creation, issue management, repo operations

review-prCode review with structured feedback

macosSystem automation and app control

himalayaEmail via CLI (read, send, search)

agent-swarmOrchestrate multiple parallel agents

onboardNew user setup and personality calibration

Custom skills

Drop a markdown file in ~/.dorabot/skills/ with YAML frontmatter:

~/.dorabot/skills/deploy.md

---
name: deploy
description: "Deploy the app to production"
user-invocable: true
metadata:
  requires:
    bins: [git, ssh]
    env: [DEPLOY_KEY]
---

# Deploy

Steps to deploy the application...

Skills are matched to prompts via keyword matching on the name and description. Eligibility checks verify required binaries, environment variables, and config keys.

MCP servers

Connect 7,300+ community MCP servers via Smithery. Browse and install from the Skills tab in the desktop app.

Configuration

Configuration is loaded from ~/.dorabot/config.json (or ./dorabot.config.json in a project, or --config flag).

Key settings

Setting	Default	Description
`model`	claude-sonnet-4-5	Default model for conversations
`provider`	claude	AI provider: claude or codex
`autonomy`	supervised	supervised or autonomous
`permissionMode`	default	default, acceptEdits, bypassPermissions, plan
`sandbox.enabled`	false	Enable sandboxed execution
`channels.telegram.enabled`	false	Enable Telegram channel
`channels.whatsapp.enabled`	false	Enable WhatsApp channel

Autonomy modes

Supervised (default): the agent asks before sending messages, taking destructive actions, or making public posts.
Autonomous: the agent acts on its own, confirming only before irreversible operations (force-push, deleting data) or spending money.

CLI

Running modes

# Production gateway (daemon mode)
dorabot -g

# Interactive terminal REPL
dorabot -i

# One-off question
dorabot -m "What's on my calendar today?"

# Development mode (gateway + desktop with HMR)
npm run dev

# CLI dev mode with auto-reload
npm run dev:cli

Interactive commands

/newStart a new session

/resume <id>Resume a previous session

/sessionsList all sessions

/skillsList eligible skills

/agentsList available agents

/scheduleShow scheduled items

/channelsShow channel status

/exitQuit the REPL

Security

dorabot is local-first with no cloud relay. Your data stays on your machine.

Always-denied paths

The agent can never read or write these paths, regardless of configuration:

~/.ssh
~/.gnupg
~/.aws
~/.dorabot/whatsapp/auth
~/.dorabot/gateway-token

Gateway authentication

The desktop app communicates with the agent via a Unix domain socket at ~/.dorabot/gateway.sock. Authentication uses a 64-character hex token stored locally. No network ports are opened.