Buffy Agent

Free habit & todo in chat. Track up to 25 habits, 100 tasks, and 15 routines with reminders and daily briefings — completely free, no paid tiers. Ask in plain language; Buffy creates and tracks for you.

What you can do (habit, todo, routines)

Buffy understands natural language — no forms or menus. One message creates or updates habits, todo items, and routines.

Overview

Buffy is a free personal behavior agent for habits, todo/tasks, and routines. It tracks activities, schedules reminders, and sends daily briefings across multiple channels (ChatGPT, Telegram, Slack, OpenClaw), all powered by a single unified behavior engine. Buffy is completely free with generous limits: 25 habits, 100 tasks, 15 routines, 200 reminders/day, and 365 days of memory.

This skill is only the HTTP client for the Buffy API and requires only BUFFY_API_KEY. Buffy runs as an external HTTP API; all behavior logic lives in the Buffy backend.

Buffy also exposes a hook-based observability system:

• Backend hooks in the Go service emit events like message:received, message:replied, and reminder:sent so logs, metrics, and long-term memory can be updated without changing core behavior logic. See backend/internal/hooks/ for details.
• OpenClaw hooks can be installed alongside this skill (see the hooks/ docs in this repo) to log Buffy conversations to markdown logs, record Buffy-related errors for observability, and track Buffy behavior over time. These hooks are optional and separately installed by the integrator; they are not part of this skill’s declared requirements. If the integrator installs them, they may write user content to disk or call other APIs and have their own credential and privacy implications.

For low-level HTTP details and the full API surface, treat the repository README.md and openapi-buffy.yaml as canonical. This SKILL.md file is the canonical guide for how agents and tools should invoke Buffy.

Base URL and authentication

• Base URL: default https://api.buffyai.org (can be overridden via config, see below).
• Auth header: always send
  • Authorization: Bearer <BUFFY_API_KEY>
• Optional user header (when using a system key):
  • X-Buffy-User-ID: <stable-user-id>

BUFFY_API_KEY is injected from the environment for the agent run. Do not include the key in prompts, logs, or user-visible text.

For registries and gateways:

• Treat BUFFY_API_KEY as the primary credential for this skill (declared in this file’s frontmatter and in the root skill.md for registry compatibility).
• Do not enable the skill unless BUFFY_API_KEY has been configured (for example, via requires.env metadata).

Core endpoint: POST /v1/message

For most use cases, always prefer POST /v1/message. Buffy’s behavior core understands natural language instructions and orchestrates activities, reminders, and daily briefings.

• Method: POST

• Path: /v1/message

• Headers:

  • Authorization: Bearer <BUFFY_API_KEY>
  • Content-Type: application/json
  • Optionally X-Buffy-User-ID: <stable-user-id> if acting on behalf of a specific user via a system key.

• Body:

{
  "user_id": "user-123",
  "platform": "openclaw",
  "message": "Remind me to drink water every 2 hours"
}

• Response (simplified):

{
  "reply": "Created a routine activity for you: \"Remind me to drink water every 2 hours\"."
}

For users who have a clan (any user gets one on first use), the backend may append clan context to the reply (e.g. clan name, shared energy, and active boss progress). The skill does not need to change how it calls the API; just surface the full reply to the user.

Usage notes for the agent

When calling POST /v1/message:

• Choose a stable user_id for the end-user:
  • Prefer a consistent external ID from the calling system (for example, an OpenClaw user ID) when available.
  • Otherwise, use the chat/session’s stable user identifier if provided in context.
• Always set "platform": "openclaw" unless the environment explicitly configures another platform.
• Put the user’s natural-language request in "message" in a clear, concise form.
• Reuse the same user_id across the conversation so Buffy can maintain context.

Examples of when to call Buffy (habit, todo, routines):

• Habit: "Create a habit to stretch every hour during workdays." / "What habits have I completed today?"
• Todo: "Add to my todo: review the report." / "What's on my todo?" / "Mark 'send email' as done."
• Routines: "Pause my evening exercise routine this week." / "Set a reminder tomorrow at 8am to plan my day."

Use via Buffy CLI

You can call the same Buffy API from the terminal or scripts using the official Buffy CLI. The same BUFFY_API_KEY used by this skill works for the CLI.

• Install: Download a binary from Releases for your OS/arch, or run go install github.com/phantue2002/buffy-cli@latest (Go 1.21+).
• Authenticate: Set export BUFFY_API_KEY=your_key or pass --api-key KEY (or --api-base URL for a different endpoint).
• Send a message (creates habits, tasks, routines, reminders in natural language):
  • buffy message --text "remind me to drink water every day"
• Manage settings and keys: buffy user-settings get, buffy user-settings set, buffy api-key list, buffy api-key create, buffy api-key revoke.

Repo: github.com/phantue2002/buffy-cli. Use the CLI when the user prefers the command line or wants to automate Buffy from scripts; use this skill (HTTP) when invoking Buffy from an agent or chat surface.

Supporting endpoints

You usually do not need these, but they are available for more advanced flows.

Clan / team

Any user can use clans (shared energy, boss fights). A personal clan is created on first use; no team plan required. The reply from POST /v1/message already includes clan name, energy, and active boss progress when the user has a clan; you do not need to call these unless building a custom flow.

• GET /v1/clans/me — Current user's clan (creates team and clan on first access if needed; 404 only if user not found).
• GET /v1/clans/{clan_id}/energy — Clan energy (members only).
• POST /v1/clans/{clan_id}/bosses — Create a boss (owner/admin).
• GET /v1/clans/{clan_id}/bosses — List bosses; GET /v1/clans/{clan_id}/bosses/{boss_id} — Boss detail.

All require the same Authorization: Bearer <BUFFY_API_KEY> and (for system keys) X-Buffy-User-ID when acting on behalf of a user. Prefer POST /v1/message for normal chat; use these only for dedicated clan/team UI or automation.

User settings

These endpoints control personalization (name, timezone, language, reminder preferences, etc.).

• GET /v1/users/{id}/settings

  • Fetch current settings for a user.

• PUT /v1/users/{id}/settings

  • Update one or more settings for a user.
  • Body fields are all optional:
    • name: string
    • language: "en" | "vi" | ...
    • timezone: string (IANA TZ, e.g. "Asia/Ho_Chi_Minh")
    • preferred_reminder_hour: number (0–23)
    • preferred_channels: string (comma-separated, e.g. "clawbot,telegram")
    • morning_person: boolean
    • night_owl: boolean

Only use these endpoints when the user is explicitly changing preferences (for example: “Change my preferred reminder time to 8am.”). For general “help me with my habits” queries, prefer POST /v1/message.

API key provisioning (advanced)

Buffy can create API keys for other tools and integrations:

• POST /v1/users/{id}/api-keys

Body:

{
  "label": "clawbot",
  "type": "system"
}

This returns a one-time api_key string that can be used in the Authorization header.

Important: this is an advanced operation. Do not automatically create keys unless the user explicitly wants to manage Buffy API keys or set up additional integrations.

Invocation pattern and best practices

When deciding whether and how to call Buffy:

• Use Buffy when the request clearly relates to habits, tasks, routines, reminders, daily briefings, or clan/team status (e.g. "What's our clan energy?" — reply includes clan name, energy, and active boss when the user has a clan).
• Default to POST /v1/message rather than manually composing lower-level operations.
• Preserve a consistent user_id so Buffy’s behavior core and memory can work effectively.
• Keep message short, clear, and close to what the user asked for, but you may add clarifying details that the user has already given in the conversation.

Avoid:

• Creating or exposing raw internal IDs to the user when not necessary.
• Making redundant calls to Buffy if you already have the needed information from a recent response.
• Using Buffy for requests that are not about habits, todo, routines, reminders, or clan/team (e.g. "how do I do X", "find a skill for X", testing, deployment, design). For those, use or suggest the find-skills workflow (e.g. npx skills find [query]) so the user can discover and install the right skill.