Habit tracking, todo, and routines
by @phantue2002
Free habit tracking, todo, and routines — create and track up to 25 habits, 100 tasks, and 15 routines; schedule reminders and daily briefings across ChatGPT...
clawhub install buffy-agent📖 About This Skill
name: buffy-agent description: Free habit tracking, todo, and routines — create and track up to 25 habits, 100 tasks, and 15 routines; schedule reminders and daily briefings across ChatGPT, Telegram, Slack, and OpenClaw. Completely free, no paid tiers. Use when the user wants to manage habits, todo/tasks, or routines, get progress summaries, or set reminder timing. primaryEnv: BUFFY_API_KEY requires: env: - BUFFY_API_KEY metadata: {"openclaw":{"primaryEnv":"BUFFY_API_KEY","requires":{"env":["BUFFY_API_KEY"]},"keywords":["habit","todo","tasks","routines","reminders","daily briefing","free"],"summary":"Free habit & todo in chat — track up to 25 habits, 100 tasks, and 15 routines with reminders. No paid plans."}}
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)
| Search for… | You can say… | |-------------|--------------| | Habit | "Create a habit to drink water every 2 hours." / "What habits did I complete today?" | | Todo | "Add to my todo: buy groceries." / "What's on my todo?" / "Mark 'call mom' done." | | Routines | "Start my morning routine." / "Remind me at 8am to plan my day." |
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:
message:received, message:replied, andreminder:sent so logs, metrics, and long-term memory can be updated without changing core
behavior logic. See backend/internal/hooks/ for details.
hooks/ docs in this repo) toFor 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
https://api.buffyai.org (can be overridden via config, see below).Authorization: Bearer
X-Buffy-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:
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).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.
POST/v1/messageAuthorization: Bearer
- Content-Type: application/json
- Optionally X-Buffy-User-ID: if acting on behalf of a specific user via a system key.{
"user_id": "user-123",
"platform": "openclaw",
"message": "Remind me to drink water every 2 hours"
}
{
"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:
user_id for the end-user:"platform": "openclaw" unless the environment explicitly configures another platform."message" in a clear, concise form.user_id across the conversation so Buffy can maintain context.Examples of when to call Buffy (habit, todo, routines):
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.
go install github.com/phantue2002/buffy-cli@latest (Go 1.21+).export BUFFY_API_KEY=your_key or pass --api-key KEY (or --api-base URL for a different endpoint).buffy message --text "remind me to drink water every day"
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.
All require the same Authorization: Bearer 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.).
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: booleanOnly 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:
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:
POST /v1/message rather than manually composing lower-level operations.user_id so Buffy’s behavior core and memory can work effectively.message short, clear, and close to what the user asked for, but you may add clarifyingAvoid:
npx skills find [query]) so the user can discover and install the right skill.Extending capabilities (find-skills)
When the user asks for help that is outside Buffy’s scope (e.g. "how do I test my API?", "find a skill for React", "is there a skill that can review PRs?"):
1. Do not call Buffy for those requests.
2. If the find-skills skill is available, use it: run npx skills find [query] with a relevant query, then present install commands and links (e.g. npx skills add ).
3. If find-skills is not available, suggest the user run npx skills find or browse https://skills.sh/ to discover and install a skill for that capability.
This keeps Buffy focused on habit/todo/routines and lets the agent hand off capability discovery to find-skills for best performance.
Security, privacy, and sandboxing
BUFFY_API_KEY is provided via the agent environment (for this skill’s turn).
- Never log, echo, or include BUFFY_API_KEY in any user-facing message or tool arguments.
- Do not serialize or store the key in prompts, memory, or external logs.buffy-error-tracker) may append Buffy-related events to
repo-local markdown logs under a path you control (such as logs/).
- Decide explicitly whether you want such logs, where they live, and how they are rotated or pruned.
- Avoid storing highly sensitive user content in long-lived logs unless your compliance model allows it.https://api.buffyai.org).
- This skill does not require any local binaries inside the sandbox (requires.bins is not used).
- If the gateway uses sandboxed runs for untrusted tools, ensure that the sandbox image allows
HTTPS egress to the Buffy endpoint while still respecting whatever network and filesystem
restrictions are configured.buffy-reminder-dispatch hook), not by this core Buffy skill.
- This skill’s metadata does not declare those channel credentials, because they are not required
for the core Buffy API client.
- Those hooks will typically require their own channel credentials (Telegram bot tokens, Clawbot
API keys, etc.); they should be configured only for the dispatch implementation you control.
- Do not reuse BUFFY_API_KEY as a channel credential, and do not expose channel tokens to the
Buffy HTTP client unless absolutely necessary.Configuration via openclaw.json
This skill is configured through ~/.openclaw/openclaw.json using the skills.entries map.
Because the metadata sets primaryEnv to BUFFY_API_KEY, you can either provide an API key
directly or reference an existing environment variable.
Minimal config (using process env)
If BUFFY_API_KEY is already set in the process environment:
{
"skills": {
"entries": {
"buffy-agent": {
"enabled": true,
"apiKey": {
"source": "env",
"provider": "default",
"id": "BUFFY_API_KEY"
}
}
}
}
}
Config with explicit env injection and endpoint override
If you want OpenClaw to inject BUFFY_API_KEY only for this skill and/or override the API endpoint
for staging or local development:
{
"skills": {
"entries": {
"buffy-agent": {
"enabled": true,
"apiKey": "BUFFY_KEY_HERE",
"env": {
"BUFFY_API_KEY": "BUFFY_KEY_HERE"
},
"config": {
"endpoint": "https://api.buffyai.org",
"platform": "openclaw"
}
}
}
}
}
Notes:
env values are only injected if the variable is not already set in the process.config.endpoint can be changed to point to:https://api-dev.buffyai.org (staging), or
- http://localhost:8080 (local backend).
config.platform can be used by the tool implementation as the default "platform" fieldPOST /v1/message.Testing the Buffy AgentSkill
To validate that the skill works end-to-end:
1. Start Buffy:
- Either run the full stack with Docker (docker compose up) or start the backend locally
following the repository README.
2. Obtain an API key:
- Use POST /v1/users/{id}/api-keys to create a system key labeled for OpenClaw usage.
3. Configure OpenClaw:
- Add an entry for "buffy-agent" in ~/.openclaw/openclaw.json as shown above, pointing
config.endpoint at your running Buffy instance and wiring BUFFY_API_KEY.
4. Verify skill discovery:
- Use the OpenClaw UI or CLI to list skills and confirm:
- buffy-agent appears.
- The emoji, description, and website are correct.
5. Run a sample interaction:
- From OpenClaw, invoke the /buffy-agent command (or let the agent auto-select the skill) with
a request such as “Remind me to stretch every hour during workdays.”
- Confirm that Buffy:
- Receives a POST /v1/message with the expected user_id, platform, and message.
- Returns a sensible reply that the agent surfaces to the user.
6. Regression checks:
- Confirm the skill is filtered out when BUFFY_API_KEY is not configured (per requires.env).
- Confirm it still works when env injection is omitted but BUFFY_API_KEY is already present
in the process environment.
This completes the Buffy AgentSkill wiring: a thin, secure HTTP wrapper around the existing Buffy behavior core, suitable for both autonomous model use and direct user invocation.