diff --git a/AGENTS.md b/AGENTS.md index 5a01cf4..610eae6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,8 @@ writes and local read-only inspection. - Use `things-cloud-cli` in new docs, examples, and agent integrations. - Keep `things-cli` only as a backward-compatible alias. - Prefer `things-mcp` for MCP-based agents. +- Use `skills/things-cloud/SKILL.md` as the public OpenClaw/ClawHub/Codex/ + Claude Code wrapper for agent-facing Things Cloud workflows. - Prefer `sync.Open(...).Sync()` or `QuickSync()` for long-running services that need persisted state and semantic change events. - Use `local.OpenDefault()` only for read-only macOS SQLite inspection. @@ -63,6 +65,10 @@ If the non-ASCII scan prints intentional content, document why in the PR. - `llms.txt` - short LLM crawler/agent index. - `docs/agent-cookbook.md` - task-oriented agent recipes. - `docs/contracts.md` - JSON contracts for CLI and MCP outputs. +- `skills/things-cloud/SKILL.md` - publishable agent skill wrapper for + OpenClaw, ClawHub, Codex, and Claude Code. +- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw + integration/showcase submission material. - `cmd/things-cloud-cli/` - preferred CLI entrypoint. - `cmd/things-mcp/` - MCP stdio server. - `internal/thingscli/` - shared CLI implementation and tests. diff --git a/CLAUDE.md b/CLAUDE.md index 7cd7aa5..a614737 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Go SDK for the Things 3 cloud API (Cultured Code). This is a reverse-engineered, unofficial SDK — there is no official API documentation. The client mimics `ThingsMac/32209501` and sends a base64-encoded `things-client-info` device metadata header. +## Agent Integration Surface + +Use `skills/things-cloud/SKILL.md` as the canonical Things Cloud agent skill +wrapper for Claude Code, Codex, OpenClaw, and ClawHub. It describes safe task +reads/writes through `things-cloud-cli` and `things-mcp`. + +Default agent behavior: + +- Prefer `things-mcp` when MCP is available. +- Use `things-cloud-cli --simple` for compact task-list JSON. +- Use `--dry-run` before generated writes, then ask for confirmation. +- Use `completed`/`logbook` for completion evidence. +- Never write to the local Things SQLite database. + +ClawHub/OpenClaw publishing material lives in +`docs/integrations/openclaw-publishing.md`. + ## Build & Test Commands ```bash @@ -66,8 +83,10 @@ The `syncutil` package provides shared utilities for sync-based CLI tools: ### CLI Tools (`cmd/`) See `cmd/README.md` for detailed documentation. Key tools: -- **`things-cli`** — Full CRUD operations (create, edit, complete, trash tasks) - - Supports `batch` command for multiple operations in one HTTP request +- **`things-cloud-cli`** — Preferred CLI for reads, safe dry-run writes, CRUD, + recurring tasks, completed/logbook evidence, and batch operations +- **`things-cli`** — Backward-compatible alias for older integrations +- **`things-mcp`** — Stdio MCP server for agent hosts - **`thingsync`** — JSON-based sync with workflow views (today, inbox, review, patterns) - **`synctest`** — Human-readable sync output for testing @@ -97,4 +116,5 @@ See `docs/client-side-bugs.md` for the full investigation. The example app and real usage require: - `THINGS_USERNAME` — Things account email -- `THINGS_PASSWORD` — Things account password +- `THINGS_TOKEN` — Preferred automation password/token alias +- `THINGS_PASSWORD` — Things account password, used when `THINGS_TOKEN` is not set diff --git a/README.md b/README.md index 1a7209e..0b0f0c6 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,10 @@ LLM-assisted automation: - `docs/agent-cookbook.md` - copy-paste recipes for common agent workflows. - `docs/contracts.md` - stable JSON contracts for CLI and MCP integrations. - `examples/agent/` - MCP config, OpenClaw notes, smoke test, and sample JSON. +- `skills/things-cloud/SKILL.md` - publishable OpenClaw/ClawHub skill wrapper, + also useful for Codex and Claude Code operating instructions. +- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw + integration/showcase submission material. ## Install @@ -334,6 +338,27 @@ Tools exposed by `things-mcp`: For destructive or user-visible changes, hosts should confirm the action before calling a non-dry-run write tool. +## OpenClaw, Codex, and Claude Code + +This repo includes a publishable agent skill wrapper: + +```text +skills/things-cloud/SKILL.md +``` + +Use it when wiring Things Cloud into OpenClaw, ClawHub, Codex, Claude Code, or +another agent runtime that understands `SKILL.md` style instructions. The skill +wraps `things-cloud-cli` and `things-mcp`; it does not duplicate runtime code. + +Local OpenClaw test install from this checkout: + +```bash +openclaw skills install ./skills/things-cloud --as things-cloud +``` + +See `docs/integrations/openclaw-publishing.md` for ClawHub publishing commands +and OpenClaw integration request copy. + ## Go SDK Quick Start Use the SDK directly when you need Cloud API access from a Go service. @@ -581,8 +606,10 @@ state/memory/ In-memory state aggregation local/ Read-only local Things SQLite reader example/ Lower-level SDK examples examples/agent/ Agent configs, smoke tests, and sample JSON +skills/things-cloud/ Publishable OpenClaw/ClawHub/Codex/Claude Code skill docs/agent-cookbook.md Agent workflow recipes docs/contracts.md CLI and MCP JSON contracts +docs/integrations/ ClawHub and OpenClaw publishing material docs/client-side-bugs.md Wire-format and crash analysis docs/ Investigation notes and protocol details ``` diff --git a/docs/integrations/openclaw-publishing.md b/docs/integrations/openclaw-publishing.md new file mode 100644 index 0000000..d5e7871 --- /dev/null +++ b/docs/integrations/openclaw-publishing.md @@ -0,0 +1,126 @@ +# OpenClaw and ClawHub Publishing + +This repository includes a publishable Things Cloud agent skill at: + +```text +skills/things-cloud/SKILL.md +``` + +The skill is designed for OpenClaw, ClawHub, Codex, Claude Code, and other +agent runtimes that can consume `SKILL.md` style instructions. It wraps the +maintained `things-cloud-cli` and `things-mcp` tools instead of duplicating +runtime code. + +## Install from This Repository + +After the skill is merged to `main`, OpenClaw users can install from the raw +skill URL if their OpenClaw version supports URL installs: + +```bash +openclaw skills install https://raw.githubusercontent.com/pdurlej/things-cloud-sdk/main/skills/things-cloud/SKILL.md --as things-cloud +``` + +For local testing from a checkout: + +```bash +openclaw skills install ./skills/things-cloud --as things-cloud +``` + +## Publish to ClawHub + +Prerequisites: + +```bash +npm i -g clawhub +clawhub login +``` + +Recommended dry-run/sync check: + +```bash +clawhub sync --all --dry-run +``` + +Publish the skill: + +```bash +clawhub skill publish ./skills/things-cloud \ + --slug things-cloud \ + --name "Things Cloud" \ + --version 0.1.0 \ + --tags latest \ + --changelog "Initial Things Cloud skill for safe OpenClaw, Codex, and Claude Code task automation." \ + --clawscan-note "This skill installs and calls the maintained things-cloud-cli and things-mcp Go binaries. It requires Things Cloud credentials through THINGS_USERNAME plus THINGS_TOKEN or THINGS_PASSWORD. Agent writes should use dry-run before execution." +``` + +Expected listing copy: + +```text +Things Cloud + +Manage Things 3 tasks through Things Cloud with a maintained Go CLI and MCP +server. Supports safe dry-run writes, compact JSON task reads, completed/logbook +evidence, recurring tasks, and agent-friendly credentials. +``` + +Suggested search terms: + +```text +things, things3, things-cloud, task-management, productivity, mcp, cli, agents, openclaw +``` + +## OpenClaw Integration Request + +The OpenClaw integrations page links "Request Integration" to the +`openclaw/openclaw` issue tracker. Submit an issue after the skill is merged and +published or at least installable from `main`. + +Suggested title: + +```text +Add Things Cloud / Things 3 as a Productivity integration +``` + +Suggested body: + +~~~markdown +## Integration + +Things Cloud / Things 3 task management + +## What it does + +Adds an agent-friendly way to read and safely update Things 3 tasks through +Things Cloud. + +## Links + +- SDK/CLI/MCP: https://github.com/pdurlej/things-cloud-sdk +- Release: https://github.com/pdurlej/things-cloud-sdk/releases/tag/v0.2.3 +- Skill: https://github.com/pdurlej/things-cloud-sdk/tree/main/skills/things-cloud + +## Capabilities + +- list Today, Inbox, Anytime, Someday, Upcoming +- search tasks +- create/edit/complete/trash/move tasks +- dry-run writes before user confirmation +- completed/logbook evidence for feedback loops +- recurring task creation via CLI +- stdio MCP server for agent hosts + +## Setup + +```bash +go install github.com/pdurlej/things-cloud-sdk/cmd/things-cloud-cli@v0.2.3 +go install github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.3 +export THINGS_USERNAME="you@example.com" +export THINGS_TOKEN="your-things-cloud-password-or-token-alias" +``` + +## Safety + +The local Things SQLite adapter is read-only. Agent writes go through Things +Cloud and should use dry-run before executing user-visible changes. +``` +~~~ diff --git a/llms.txt b/llms.txt index 1b5296a..0373ab9 100644 --- a/llms.txt +++ b/llms.txt @@ -27,6 +27,10 @@ Best entry points for LLMs: - `docs/agent-cookbook.md` - copy-paste recipes for common agent workflows. - `docs/contracts.md` - JSON output contracts for CLI and MCP integrations. - `examples/agent/` - MCP config, OpenClaw notes, smoke test, sample outputs. +- `skills/things-cloud/SKILL.md` - publishable OpenClaw/ClawHub skill wrapper + and reusable Codex/Claude Code operating policy. +- `docs/integrations/openclaw-publishing.md` - ClawHub listing and OpenClaw + integration/showcase submission copy. - `docs/client-side-bugs.md` - Things wire-format and crash-safety notes. Recommended interface by task: diff --git a/skills/things-cloud/SKILL.md b/skills/things-cloud/SKILL.md new file mode 100644 index 0000000..5c7f024 --- /dev/null +++ b/skills/things-cloud/SKILL.md @@ -0,0 +1,160 @@ +--- +name: things-cloud +description: Manage Things 3 tasks through Things Cloud using the maintained things-cloud-sdk CLI and MCP server, with dry-run safety for agent writes. +version: 0.1.0 +metadata: + openclaw: + requires: + bins: + - things-cloud-cli + - things-mcp + primaryEnv: THINGS_TOKEN + envVars: + - name: THINGS_USERNAME + required: true + description: Things Cloud account email. + - name: THINGS_TOKEN + required: false + description: Things Cloud password or automation token alias. Use this instead of THINGS_PASSWORD when possible. + - name: THINGS_PASSWORD + required: false + description: Things Cloud password. Required only when THINGS_TOKEN is not set. + - name: THINGS_CONFIG + required: false + description: Optional path to a JSON config file with credentials and cache settings. + - name: THINGS_CLI_CACHE + required: false + description: Optional path to the CLI read-state cache. + install: + - kind: go + package: github.com/pdurlej/things-cloud-sdk/cmd/things-cloud-cli@v0.2.3 + bins: + - things-cloud-cli + - kind: go + package: github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.3 + bins: + - things-mcp + homepage: https://github.com/pdurlej/things-cloud-sdk +--- + +# Things Cloud + +Use this skill when the user wants an agent to inspect or safely update Things 3 +tasks through Things Cloud. + +Prefer the MCP server when the host supports MCP. Use the CLI as the fallback or +when the user asks for explicit shell commands. + +## Setup + +Install the maintained CLI and MCP server: + +```bash +go install github.com/pdurlej/things-cloud-sdk/cmd/things-cloud-cli@v0.2.3 +go install github.com/pdurlej/things-cloud-sdk/cmd/things-mcp@v0.2.3 +``` + +Set credentials: + +```bash +export THINGS_USERNAME="you@example.com" +export THINGS_TOKEN="your-things-cloud-password-or-token-alias" +``` + +`THINGS_PASSWORD` also works when `THINGS_TOKEN` is not set. Do not store +credentials in the repository or in skill files. + +## MCP Configuration + +Use this stdio MCP server config for OpenClaw, Claude Code, Codex hosts, or any +MCP-compatible agent runtime: + +```json +{ + "mcpServers": { + "things": { + "command": "things-mcp", + "env": { + "THINGS_USERNAME": "you@example.com", + "THINGS_TOKEN": "your-things-cloud-password-or-token-alias" + } + } + } +} +``` + +## Agent Policy + +- Read before writing. +- Prefer MCP tools for task operations. +- Use CLI `--simple` output for compact task lists. +- Use `--dry-run` before any user-visible write generated by an agent. +- Summarize the planned change and get confirmation before non-dry-run writes. +- Never write to the local Things SQLite database. +- Do not infer completion from absence in active views; use + `completed`/`logbook`. +- Use task UUIDs returned by Things Cloud output. Do not invent UUIDs. + +## Common Reads + +With MCP: + +- `list_tasks` with `view` set to `today`, `inbox`, `anytime`, `someday`, or + `upcoming` +- `search_tasks` for title/note search +- `list_projects`, `list_areas`, and `list_tags` for metadata + +With CLI: + +```bash +things-cloud-cli today --simple +things-cloud-cli inbox --simple +things-cloud-cli anytime --simple +things-cloud-cli someday --simple +things-cloud-cli upcoming --simple +things-cloud-cli search "invoice" --simple +``` + +## Completion Evidence + +Use completed/logbook commands when the user asks whether something was done: + +```bash +things-cloud-cli completed --since 2026-05-20T00:00:00Z --format full +things-cloud-cli logbook --since 2026-05-20 --limit 50 --format full +``` + +## Safe Writes + +Preview first: + +```bash +things-cloud-cli create "Follow up with Marta" --when today --dry-run +things-cloud-cli edit --title "New title" --dry-run +things-cloud-cli complete --dry-run +``` + +After user confirmation, run the same command without `--dry-run`. + +Recurring tasks: + +```bash +things-cloud-cli create "Check car listings" --repeat every-day --dry-run +things-cloud-cli create "Weekly review" --repeat weekly:mon --dry-run +things-cloud-cli create "Follow up after reply" --repeat after-completion:every-day --dry-run +``` + +Clear recurrence: + +```bash +things-cloud-cli edit --repeat none --dry-run +``` + +## Output Rules + +- Keep raw command output as JSON. +- Summaries should mention the task title, UUID, view/status, and whether the + write was dry-run or executed. +- If a task reference is ambiguous, search first and ask the user to choose. +- If credentials are missing, ask the user to set `THINGS_USERNAME` and either + `THINGS_TOKEN` or `THINGS_PASSWORD`.