diff --git a/README.md b/README.md index f27de08..aba0db8 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,26 @@ Switch profiles: goclaw auth use-context staging ``` +## Claude Code Skill + +A Claude Code skill wrapping this CLI lives in [`claude-skill/`](./claude-skill/). +It lets Claude Code autonomously invoke `goclaw` to manage your GoClaw server — +list agents, run `exec`-style shell commands on the server, inspect traces, etc. + +Install (once the binary is in `PATH`): + +```bash +RELEASE_URL="https://github.com/nextlevelbuilder/goclaw-cli/releases/download/skill-v0.1.0" +curl -fsSL "$RELEASE_URL/goclaw-skill.tar.gz" -o /tmp/goclaw-skill.tar.gz +curl -fsSL "$RELEASE_URL/goclaw-skill.sha256" -o /tmp/goclaw-skill.sha256 +(cd /tmp && shasum -a 256 -c goclaw-skill.sha256) +tar xzf /tmp/goclaw-skill.tar.gz -C /tmp +/tmp/claude-skill/install.sh +``` + +See [`claude-skill/README.md`](./claude-skill/README.md) for permission modes, +example prompts, and uninstall instructions. + ## Development ```bash diff --git a/claude-skill/.verified-commands.txt b/claude-skill/.verified-commands.txt new file mode 100644 index 0000000..1167b3c --- /dev/null +++ b/claude-skill/.verified-commands.txt @@ -0,0 +1,60 @@ +A production-ready CLI for managing GoClaw AI agent gateway servers. +Supports interactive (human) and automation (AI agent / CI) modes. + +Usage: + goclaw [command] + +Available Commands: + activity View audit log + agents Manage agents + api-docs View API documentation + api-keys Manage API keys for scoped access + approvals Manage execution approvals + auth Manage authentication + channels Manage messaging channels + chat Chat with an agent + completion Generate the autocompletion script for the specified shell + config Manage server configuration + contacts Manage contacts + credentials Manage CLI credentials store + cron Manage scheduled jobs + delegations View delegation history + devices Manage paired devices + export Export resources (agents, teams, skills, mcp) + health Check server health + heartbeat Manage heartbeat configuration and monitoring + help Help about any command + import Import resources (agents, teams, skills, mcp) + knowledge-graph Knowledge graph operations + logs View server logs + mcp Manage MCP servers and grants + media Upload and download media + memory Manage agent memory + packages Manage runtime packages + pending-messages Manage pending messages + providers Manage LLM providers + sessions Manage chat sessions + skills Manage skills + status Show server status and metadata + storage Browse workspace files + system-config Per-tenant key-value configuration + teams Manage agent teams + tenants Manage tenants (admin) + tools Manage built-in tools + traces View LLM traces + tts Text-to-speech operations + usage View usage and cost analytics + version Print CLI version information + +Flags: + -h, --help help for goclaw + --insecure Skip TLS certificate verification + -o, --output string Output format: table, json, yaml (default "table") + --profile string Config profile to use (default: active profile) + --server string GoClaw server URL (env: GOCLAW_SERVER) + --tenant-id string Tenant ID for multi-tenant operations (env: GOCLAW_TENANT_ID) + --token string Auth token or API key (env: GOCLAW_TOKEN) + -v, --verbose Enable verbose/debug output + -y, --yes Skip confirmation prompts (automation mode) + +Use "goclaw [command] --help" for more information about a command. diff --git a/claude-skill/LICENSE b/claude-skill/LICENSE new file mode 100644 index 0000000..9f62748 --- /dev/null +++ b/claude-skill/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 NextLevelBuilder + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/claude-skill/README.md b/claude-skill/README.md new file mode 100644 index 0000000..b5f7dde --- /dev/null +++ b/claude-skill/README.md @@ -0,0 +1,74 @@ +# GoClaw CLI Skill for Claude Code + +Lets the Claude Code agent drive [goclaw](https://github.com/nextlevelbuilder/goclaw-cli) — the CLI for GoClaw AI agent gateway servers — via natural-language prompts. Execute shell commands on remote servers, manage AI agents, approve execution requests, inspect chat sessions, and administer multi-tenant infrastructure, all without leaving Claude Code. + +## Requirements + +- `goclaw` binary ≥ 0.3.0 in `$PATH` ([install](https://github.com/nextlevelbuilder/goclaw-cli/releases)) +- Claude Code CLI installed (`~/.claude/` directory) +- Authenticated: run `goclaw auth login` before using the skill +- macOS or Linux (Windows via WSL) + +## Install + +### Recommended: release tarball + SHA256 + +```bash +RELEASE_URL="https://github.com/nextlevelbuilder/goclaw-cli/releases/download/skill-v0.1.0" +curl -fsSL "$RELEASE_URL/goclaw-skill.tar.gz" -o /tmp/goclaw-skill.tar.gz +curl -fsSL "$RELEASE_URL/goclaw-skill.sha256" -o /tmp/goclaw-skill.sha256 +(cd /tmp && sha256sum -c goclaw-skill.sha256) # aborts on mismatch +tar xzf /tmp/goclaw-skill.tar.gz -C /tmp +/tmp/claude-skill/install.sh +``` + +### From git clone + +```bash +git clone https://github.com/nextlevelbuilder/goclaw-cli.git +cd goclaw-cli/claude-skill +./install.sh +``` + +## Usage examples + +Once installed, just ask Claude: + +- *"list agents on goclaw"* → runs `goclaw agents list --output json` +- *"run `uname -a` on goclaw server"* → runs `goclaw tools invoke exec --param command="uname -a"` +- *"what's my usage this week"* → runs `goclaw usage summary --output json` + +Destructive operations always prompt you first. Claude will ask *"Confirm delete agent xyz?"* before running `goclaw agents delete xyz --yes`. + +## Permission modes + +The installer offers three modes: + +| Mode | Rule | When to use | +|------|------|-------------| +| 1 | `Bash(goclaw:*)` | Trusted personal machine, full-auto | +| 2 | ~20 readonly rules | Shared / production machine (default) | +| 3 | Manual JSON snippet | You want to edit settings.json yourself | + +Default in pipe mode (`curl | bash`): Mode 3 (safest). + +## What's NOT supported + +- Interactive chat REPL (`goclaw chat` without `-m`) — use single-shot +- `logs tail` streaming — Claude will suggest polling instead +- `auth pair` device pairing — run manually, skill refuses + +## Uninstall + +```bash +rm -rf ~/.claude/skills/goclaw +# Then manually remove goclaw permissions from ~/.claude/settings.json +``` + +## Compatibility + +Tested against `goclaw` CLI ≥ 0.3.0. `check-drift.sh` catches flag drift between skill and CLI. + +## License + +MIT — see [LICENSE](LICENSE). diff --git a/claude-skill/SKILL.md b/claude-skill/SKILL.md new file mode 100644 index 0000000..258aed6 --- /dev/null +++ b/claude-skill/SKILL.md @@ -0,0 +1,73 @@ +--- +name: goclaw +description: Manage GoClaw AI agent gateway servers from Claude Code. Use this skill when the user mentions "goclaw", "gateway server", "AI agent platform", or wants to execute shell commands remotely on a server, manage AI agents, approve agent actions, inspect chat sessions, or administer multi-tenant AI infrastructure. Wraps the `goclaw` CLI to call REST + WebSocket APIs of GoClaw Gateway. +when_to_use: goclaw CLI operations, remote shell execution via exec tool, AI agent lifecycle, chat session inspection, tenant administration, skill/provider/MCP management, execution approvals +allowed-tools: Bash(goclaw:*) +disable-model-invocation: false +user-invocable: true +argument-hint: +--- + +# GoClaw CLI Skill + +Lets Claude invoke the `goclaw` binary via Bash to interact with a GoClaw Gateway server. Single source of truth = the CLI; this skill teaches Claude the ergonomics. + +## Conventions (always apply) + +1. **Always append `--output json`** to every goclaw call. Rely on JSON parsing, not table output. +2. **Read auth from `~/.goclaw/config.yaml`** — do NOT accept token via prompt; user must have run `goclaw auth login` beforehand. +3. **Destructive ops require user confirm.** Any command with `--yes` flag or verbs `delete`, `reset`, `revoke`, `unpublish`, `clear`, `rotate`, `deny`, `execute-merge` → ask user to confirm *before* adding `--yes`. +4. **Streaming commands are NOT Bash-friendly.** Refuse to run: `chat` interactive mode, `logs tail`, `auth pair`, `approvals watch`. Suggest polling or user-run-manually alternative. +5. **Exit code 1 after auth error** → suggest `goclaw auth login`, do not retry-loop. +6. **Never hardcode** server URL, tenant ID, agent ID, user ID — use placeholders in examples, actual values from user context. + +## Hero use case — execute shell on server + +Tool `exec` registered as builtin on GoClaw Gateway. Claude invokes via: + +```bash +goclaw tools invoke exec --param command="ls -la /workspace" --output json +# with working directory: +goclaw tools invoke exec --param command="npm test" --param working_dir="/workspace/app" --output json +``` + +Approval flow when server deems command sensitive (package installs, deny-patterns): call hits `approvals` queue. Handle via `references/exec-workflow.md`. + +## Navigation — load relevant reference on demand + +Claude: when user's intent matches, `Read` the listed reference file before constructing commands. + +| Intent signal | Reference | +|---------------|-----------| +| exec / run shell / remote command / approvals | [references/exec-workflow.md](references/exec-workflow.md) | +| login / token / profile / tenant switch / credentials / api-keys | [references/auth-and-config.md](references/auth-and-config.md) | +| agent list/get/create/delete, agent files, instances, wake | [references/agents-core.md](references/agents-core.md) | +| agent share, link, delegate, regenerate | [references/agents-advanced.md](references/agents-advanced.md) | +| chat with agent, session list/preview/delete | [references/chat-sessions.md](references/chat-sessions.md) | +| health, status, logs, traces, usage, metrics | [references/monitoring-ops.md](references/monitoring-ops.md) | +| knowledge graph, entity dedup, memory | [references/knowledge-memory.md](references/knowledge-memory.md) | +| teams, members, team tasks, workspace files | [references/teams-collaboration.md](references/teams-collaboration.md) | +| channels, contacts, pending messages, writers | [references/channels-messaging.md](references/channels-messaging.md) | +| export / import / storage (workspace files) | [references/data-movement.md](references/data-movement.md) | +| providers, skills, built-in tools list/config, packages | [references/providers-skills-tools.md](references/providers-skills-tools.md) | +| cron, heartbeat, device pairing | [references/automation-scheduling.md](references/automation-scheduling.md) | +| MCP servers, grants, requests | [references/mcp-integration.md](references/mcp-integration.md) | +| tenants, system-config, audit activity, TTS | [references/admin-system.md](references/admin-system.md) | +| media upload/download | [references/media.md](references/media.md) | +| API documentation browsing | [references/docs-api.md](references/docs-api.md) | + +## Compatibility + +Tested against `goclaw` CLI ≥ 0.3.0. Run `goclaw version` to check. Schema drift caught by `check-drift.sh` in CI. + +## Prerequisites + +- `goclaw` binary in PATH (download from https://github.com/nextlevelbuilder/goclaw-cli/releases) +- Authenticated: `goclaw auth login` or paired via `goclaw auth pair` +- Permissions granted in `~/.claude/settings.json` (see install.sh) + +## Troubleshooting + +- Command returns 401 → token expired, run `goclaw auth login` +- Command returns 403 → user lacks role for resource; check `goclaw whoami --output json` +- Command hangs → likely streaming op — Claude should refuse, see convention #4 diff --git a/claude-skill/check-drift.sh b/claude-skill/check-drift.sh new file mode 100644 index 0000000..d37f6b0 --- /dev/null +++ b/claude-skill/check-drift.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# check-drift.sh — validate that every --flag mentioned in references/*.md +# exists in goclaw-cli/cmd/*.go source. Exit non-zero on mismatch. +# Intended for CI: catches skill documentation going stale relative to CLI. +set -euo pipefail + +SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)" +CMD_DIR="${REPO_ROOT}/cmd" + +if [[ ! -d "$CMD_DIR" ]]; then + echo "ERROR: cmd/ not found at $CMD_DIR. Run from goclaw-cli repo or mount it." + exit 1 +fi + +# Cobra built-ins we never expect to find in goclaw cmd/*.go +ALLOWLIST=(help verbose output server token insecure yes profile tenant-id version) + +is_allowed() { + local f="$1" + for a in "${ALLOWLIST[@]}"; do + [[ "$f" == "$a" ]] && return 0 + done + return 1 +} + +TOTAL=0 +MISSING=0 +declare -a MISSING_FLAGS=() + +# Extract flag names (--foo, --foo-bar) from reference md files. +# Match --flag-name (letters/digits/hyphens), excluding trailing punctuation. +while IFS= read -r line; do + [[ -z "$line" ]] && continue + flag="$(echo "$line" | sed -E 's/^.*--([a-zA-Z][a-zA-Z0-9-]*).*$/\1/')" + [[ -z "$flag" ]] && continue + TOTAL=$((TOTAL + 1)) + if is_allowed "$flag"; then + continue + fi + # Grep the cmd/*.go source for Flags().("$flag" ...). + if ! grep -rEq "Flags\(\)\.(String|Int|Bool|StringSlice|StringP|IntP|BoolP)\([^)]*\"$flag\"" "$CMD_DIR" 2>/dev/null; then + MISSING=$((MISSING + 1)) + MISSING_FLAGS+=("$flag") + fi +done < <(grep -hoE -- '--[a-zA-Z][a-zA-Z0-9-]*' "$SKILL_DIR/references/"*.md 2>/dev/null | sort -u) + +echo "Checked $(grep -hoE -- '--[a-zA-Z][a-zA-Z0-9-]*' "$SKILL_DIR/references/"*.md 2>/dev/null | sort -u | wc -l | tr -d ' ') unique flag mentions across references/." +echo "Unresolved: $MISSING" + +if (( MISSING > 0 )); then + printf '%s\n' "Missing from cmd/*.go (possible drift or false positive):" + for f in "${MISSING_FLAGS[@]}"; do + printf ' --%s\n' "$f" + done + exit 1 +fi + +echo "OK — no drift detected." +exit 0 diff --git a/claude-skill/install.sh b/claude-skill/install.sh new file mode 100644 index 0000000..f3cdbac --- /dev/null +++ b/claude-skill/install.sh @@ -0,0 +1,272 @@ +#!/usr/bin/env bash +# install.sh — GoClaw Claude Code Skill installer. +# Copies skill files to ~/.claude/skills/goclaw/ and merges permissions +# into ~/.claude/settings.json. Idempotent. Safe under `curl | bash`. +set -euo pipefail + +# ------------- Windows abort ------------- +case "$(uname -s)" in + MINGW*|MSYS*|CYGWIN*) + echo "ERROR: Windows not supported in v1. Use WSL or install manually." >&2 + exit 1 ;; +esac + +# ------------- helpers ------------- +# has_tty: succeed iff /dev/tty is actually usable (not just readable as path). +# `-r /dev/tty` can be true even when the TTY is detached (e.g. `< /dev/null`). +# Probe by trying to open /dev/tty for read; suppress any error. +has_tty() { + { true < /dev/tty; } 2>/dev/null +} + +# ------------- args ------------- +MODE="" +DRY_RUN=0 +FORCE=0 + +usage() { + cat <<'EOF' +GoClaw Claude Code Skill installer + +Usage: install.sh [options] + +Options: + --mode 1|2|3 Permission mode (skips interactive prompt): + 1 = full wildcard Bash(goclaw:*) (trust this machine) + 2 = readonly verbs (~20 rules, SAFEST default) + 3 = no patching (print JSON snippet only) + --dry-run Print actions, do not modify files + --force Overwrite existing skill dir without prompt + -h, --help Show this help + +Without --mode: interactive via /dev/tty. Under `curl|bash` (no TTY): auto-picks Mode 3. + +Env vars: + CLAUDE_HOME Override ~/.claude location (default: $HOME/.claude) +EOF +} + +while [[ $# -gt 0 ]]; do + case $1 in + --mode) MODE="${2:-}"; shift 2 ;; + --dry-run) DRY_RUN=1; shift ;; + --force) FORCE=1; shift ;; + -h|--help) usage; exit 0 ;; + *) echo "Unknown arg: $1" >&2; usage >&2; exit 1 ;; + esac +done + +# ------------- locations ------------- +CLAUDE_HOME="${CLAUDE_HOME:-$HOME/.claude}" +SETTINGS="$CLAUDE_HOME/settings.json" +SKILL_DIR="$CLAUDE_HOME/skills/goclaw" +SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# ------------- prereqs ------------- +if ! command -v goclaw >/dev/null 2>&1; then + echo "WARNING: 'goclaw' not in PATH. Skill will be installed, but commands will fail until you install the binary." >&2 + echo " Download: https://github.com/nextlevelbuilder/goclaw-cli/releases" >&2 +fi + +if [[ ! -d "$CLAUDE_HOME" ]]; then + echo "ERROR: $CLAUDE_HOME not found. Install Claude Code first." >&2 + exit 1 +fi + +# ------------- python3 detect ------------- +PY="" +if [[ -x "$CLAUDE_HOME/skills/.venv/bin/python3" ]]; then + PY="$CLAUDE_HOME/skills/.venv/bin/python3" +elif command -v python3 >/dev/null 2>&1; then + PY="$(command -v python3)" +fi +if [[ -n "$PY" ]]; then + if ! "$PY" -c 'import sys; sys.exit(0 if sys.version_info[0]==3 else 1)' 2>/dev/null; then + echo "WARNING: python3 at $PY is not Python 3.x — permission patching will be skipped." >&2 + PY="" + fi +fi + +# ------------- interactive mode selection ------------- +if [[ -z "$MODE" ]]; then + if has_tty; then + # We have a TTY to read from. + echo "Choose permission mode:" + echo " 1) Full wildcard Bash(goclaw:*) — trust this machine fully" + echo " 2) Readonly verbs only (~20 rules, SAFEST)" + echo " 3) No patching — print JSON snippet" + read -r -p "Select [3]: " MODE < /dev/tty 2>/dev/null || MODE="3" + MODE="${MODE:-3}" + else + # Piped (curl|bash) — default Mode 3. + echo "No TTY detected (piped install). Defaulting to Mode 3 (no patching)." + MODE="3" + fi +fi + +case "$MODE" in + 1|2|3) ;; + *) echo "ERROR: invalid --mode $MODE. Use 1, 2, or 3." >&2; exit 1 ;; +esac + +# ------------- confirm Mode 1 ------------- +if [[ "$MODE" == "1" ]]; then + if has_tty; then + echo "" + echo "WARNING: Mode 1 grants Claude Code permission to run ANY goclaw command," + echo " including destructive operations (delete, revoke, clear)." + read -r -p "Continue? [y/N] " CONFIRM < /dev/tty 2>/dev/null || CONFIRM="" + case "$CONFIRM" in y|Y|yes|YES) ;; *) echo "Aborted."; exit 0 ;; esac + else + echo "ERROR: Mode 1 requires TTY confirmation. Re-run in terminal or pass --mode 2|3." >&2 + exit 1 + fi +fi + +# ------------- skill overwrite gate ------------- +if [[ -d "$SKILL_DIR" && "$FORCE" != "1" ]]; then + if has_tty; then + read -r -p "Existing skill at $SKILL_DIR. Overwrite? [y/N] " OW < /dev/tty 2>/dev/null || OW="" + case "$OW" in y|Y|yes|YES) ;; *) echo "Aborted."; exit 0 ;; esac + else + echo "ERROR: $SKILL_DIR exists. Re-run with --force to overwrite." >&2 + exit 1 + fi +fi + +echo "" +echo "Installing GoClaw skill to: $SKILL_DIR" +echo "Permission mode: $MODE | dry-run: $DRY_RUN" + +# ------------- copy skill files ------------- +if [[ "$DRY_RUN" == "1" ]]; then + echo "[dry-run] mkdir -p $SKILL_DIR/references" + echo "[dry-run] cp SKILL.md, README.md, LICENSE, check-drift.sh, references/*.md, .verified-commands.txt" +else + mkdir -p "$SKILL_DIR/references" + cp "$SRC_DIR/SKILL.md" "$SKILL_DIR/" + cp "$SRC_DIR/README.md" "$SKILL_DIR/" + cp "$SRC_DIR/LICENSE" "$SKILL_DIR/" + cp "$SRC_DIR/check-drift.sh" "$SKILL_DIR/" + [[ -f "$SRC_DIR/.verified-commands.txt" ]] && cp "$SRC_DIR/.verified-commands.txt" "$SKILL_DIR/" + cp "$SRC_DIR/references/"*.md "$SKILL_DIR/references/" + chmod +x "$SKILL_DIR/check-drift.sh" +fi + +# ------------- prepare permission rules ------------- +if [[ "$MODE" == "1" ]]; then + RULES_JSON='["Bash(goclaw:*)"]' +elif [[ "$MODE" == "2" ]]; then + # Read-only verbs enumerated per known resource group. + RULES_JSON='[ + "Bash(goclaw agents list:*)", + "Bash(goclaw agents get:*)", + "Bash(goclaw sessions list:*)", + "Bash(goclaw sessions preview:*)", + "Bash(goclaw traces list:*)", + "Bash(goclaw traces get:*)", + "Bash(goclaw usage summary:*)", + "Bash(goclaw usage detail:*)", + "Bash(goclaw status:*)", + "Bash(goclaw health:*)", + "Bash(goclaw whoami:*)", + "Bash(goclaw version:*)", + "Bash(goclaw auth whoami:*)", + "Bash(goclaw auth list-contexts:*)", + "Bash(goclaw tools builtin list:*)", + "Bash(goclaw tools builtin get:*)", + "Bash(goclaw skills list:*)", + "Bash(goclaw skills get:*)", + "Bash(goclaw providers list:*)", + "Bash(goclaw memory list:*)", + "Bash(goclaw memory get:*)", + "Bash(goclaw knowledge-graph entities list:*)", + "Bash(goclaw kg entities list:*)", + "Bash(goclaw storage list:*)", + "Bash(goclaw tenants list:*)", + "Bash(goclaw system-config list:*)", + "Bash(goclaw activity list:*)", + "Bash(goclaw approvals list:*)", + "Bash(goclaw delegations list:*)", + "Bash(goclaw packages list:*)" + ]' +else + RULES_JSON='[]' +fi + +# ------------- Mode 3 snippet output ------------- +if [[ "$MODE" == "3" ]]; then + cat <" + else + if ! cp "$SETTINGS" "$SETTINGS.bak.$(date +%s)"; then + echo "ERROR: failed to back up $SETTINGS — aborting to avoid destructive change." >&2 + exit 1 + fi + fi +fi + +# ------------- patch settings.json via python3 ------------- +if [[ -z "$PY" ]]; then + echo "No Python 3 available. Permissions NOT patched — see Mode 3 snippet above." >&2 + exit 0 +fi + +if [[ "$DRY_RUN" == "1" ]]; then + echo "[dry-run] would merge into $SETTINGS permissions.allow: $RULES_JSON" + exit 0 +fi + +SETTINGS_PATH="$SETTINGS" RULES="$RULES_JSON" "$PY" <<'PYEOF' +import json, os, sys +p = os.environ["SETTINGS_PATH"] +rules = json.loads(os.environ["RULES"]) +data = {} +if os.path.exists(p): + try: + with open(p) as f: + data = json.load(f) or {} + except Exception as e: + sys.exit(f"ERROR: {p} is not valid JSON ({e}); aborting to protect existing config.") +perms = data.setdefault("permissions", {}) +allow = perms.setdefault("allow", []) +added = 0 +for r in rules: + if r not in allow: + allow.append(r) + added += 1 +with open(p, "w") as f: + json.dump(data, f, indent=2) +print(f"Merged {added} new permission rule(s) into {p} (already had {len(allow)-added} matching).") +PYEOF + +echo "" +echo "Install complete." +echo " Skill: $SKILL_DIR" +echo " Settings: $SETTINGS (backup kept as .bak.)" +echo "" +echo "Next: restart Claude Code if running, then ask it \"list agents on goclaw\"." diff --git a/claude-skill/references/admin-system.md b/claude-skill/references/admin-system.md new file mode 100644 index 0000000..15b0072 --- /dev/null +++ b/claude-skill/references/admin-system.md @@ -0,0 +1,94 @@ +# Admin & system + +## When to use + +User wants admin-only operations: multi-tenant management, per-tenant config KV store, view audit log, check TTS status. **Requires admin role** — check `goclaw whoami` first. + +## Commands in scope + +- `goclaw tenants list/get/create/update/delete/users` — tenant CRUD (source: `cmd/tenants.go`) +- `goclaw system-config list/get/set/delete` — per-tenant KV config (source: `system_config.go`) +- `goclaw activity list` — audit log (source: `admin_activity.go`) +- `goclaw tts status` — TTS service status (source: `admin_tts.go`, WS call) + +## Verified flags + +### `tenants create/update/users` (verify with --help) +Run `goclaw tenants create --help` / `goclaw tenants users --help` for current flag names. +Common fields: tenant `name`, user-management `action` (add/remove), user ID. + +### `system-config set` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--key ` | string | Config key | +| `--value ` | string | New value | + +### `system-config get/delete` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--key ` | string | Config key | + +### `activity list` (verify with --help) +- `--limit ` — max results (typical) +- additional filter flags vary; run `goclaw activity list --help` + +## JSON output + +- ✅ `tenants list/get/users`, `system-config list/get`, `activity list`, `tts status` — JSON +- ⚠️ `tenants create/update/delete`, `system-config set/delete` — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `tenants delete` | **YES — CRITICAL**; cascades ALL tenant data | +| `tenants users --action remove` | YES | +| `system-config delete` | YES | + +## Common patterns + +### Example 1: list all tenants (admin) +```bash +goclaw tenants list --output json +``` + +### Example 2 & 3: create tenant + add user (flag names vary) +```bash +goclaw tenants create --help # always check current flags +goclaw tenants users --help +``` + +### Example 4: per-tenant config override +```bash +# Read current +goclaw --tenant-id acme system-config list --output json +# Set feature flag +goclaw --tenant-id acme system-config set --key "feature.streaming" --value "true" +``` + +### Example 5: audit trail +```bash +goclaw activity list --limit 50 --output json +# for filters, check --help for current flag names +``` + +### Example 6: check TTS service +```bash +goclaw tts status --output json +# → {"enabled": true, "provider": "elevenlabs", "voices_count": 42} +``` + +## Edge cases & gotchas + +- **Admin-only:** commands here require `admin` role in the active tenant. Check `goclaw whoami --output json` — if `role` ≠ `admin`, commands will 403. +- **`tenants delete` blast radius:** deletes ALL agents, sessions, memory, channels for that tenant. Triple-confirm. No undo. +- **`--tenant-id` global flag** (source: root.go) scopes `system-config` and most other commands to a specific tenant even if you're a cross-tenant admin. +- **System-config keys** are free-form strings; conventions (e.g. `feature.*`, `limit.*`) are app-level, not enforced. +- **Activity log retention:** server-dependent. Check with `system-config get --key "activity.retention_days"`. +- **TTS** is read-only here; actual TTS generation is a builtin tool (`tools invoke tts --param text="..."`). + +## Cross-refs + +- TTS invoked as tool: [exec-workflow.md](exec-workflow.md) — `tools invoke tts` +- User auth/profile (non-admin): [auth-and-config.md](auth-and-config.md) +- Per-config permissions: [auth-and-config.md](auth-and-config.md) — `config permissions` diff --git a/claude-skill/references/agents-advanced.md b/claude-skill/references/agents-advanced.md new file mode 100644 index 0000000..2d5c2a5 --- /dev/null +++ b/claude-skill/references/agents-advanced.md @@ -0,0 +1,106 @@ +# Agents — advanced (links, ops, delegations) + +## When to use + +User wants to share agents across users, create delegation links between agents, regenerate/resummon an agent, or wait for an agent to finish. + +## Commands in scope + +- `goclaw agents links list/create/update/delete` — delegation links (source: `cmd/agents_links.go`) +- `goclaw agents share/unshare ` — user sharing (source: `cmd/agents_ops.go:11-49`) +- `goclaw agents regenerate/resummon ` — reset agent setup +- `goclaw agents wait ` — **WS-based blocking wait** (source: `cmd/agents_ops.go:87`) +- `goclaw delegations list/get` — delegation history (source: `cmd/admin.go:86-129`) + +## Verified flags + +### `agents links create` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--source ` | string | — | Source agent | +| `--target ` | string | — | Target agent | +| `--direction ` | string | `outbound` | `outbound`/`inbound`/`bidirectional` | +| `--max-concurrent ` | int | 3 | Concurrent delegation cap | + +### `agents share` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--user ` | string (REQUIRED) | — | User to share with | +| `--role ` | string | `operator` | `admin`/`operator`/`viewer` | + +### `agents unshare` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--user ` | string (REQUIRED) | User to revoke | + +### `agents wait` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--session ` | string | Session to wait on | +| `--timeout ` | int (0 = no timeout) | Bash-safe max ~100 | + +### `delegations list` +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--agent ` | string | — | Filter by agent | +| `--limit ` | int | 20 | Max results | + +## JSON output + +- ✅ `agents links list` — JSON +- ✅ `delegations list/get` — JSON +- ✅ `agents wait` — JSON final state (blocks until complete or timeout) +- ⚠️ `share/unshare/regenerate/resummon/links create|update|delete` — success text only + +## Destructive ops + +| Command | Source | Confirm | +| --- | --- | --- | +| `agents links delete` | `agents_links.go:99` tui.Confirm | YES | +| `agents unshare` | removes user access | YES | + +## Common patterns + +### Example 1: share agent with user as operator +```bash +goclaw agents share --user user-42 --role operator +``` + +### Example 2: create bidirectional delegation link +```bash +goclaw agents links create \ + --source agent-alpha --target agent-beta \ + --direction bidirectional --max-concurrent 5 \ + --output json +``` + +### Example 3: wait for agent to finish (with timeout) +```bash +# Bash tool default timeout = 120s, set --timeout lower +goclaw agents wait --session --timeout 90 --output json +``` + +### Example 4: delegation audit +```bash +goclaw delegations list --agent --limit 50 --output json +goclaw delegations get --output json +``` + +### Example 5: regenerate after model swap +```bash +goclaw agents update --model claude-opus-4-7 +goclaw agents regenerate +``` + +## Edge cases & gotchas + +- **`agents wait` WS subscribe:** blocks until agent idle OR timeout. With `--timeout 0` it blocks indefinitely → Bash tool kills at 120s. Always set a `--timeout < 110`. +- **Direction `inbound`:** target receives delegations from source, not the other way. Mental model: "direction of the data flow". +- **Role hierarchy:** `admin` > `operator` > `viewer`. Downgrade requires `unshare` + `share` with new role. +- **`regenerate` vs `resummon`:** regenerate rebuilds agent config from current settings; resummon reruns initial setup wizard (may prompt on server side). +- **Delegations view is read-only:** no create/delete — links drive the delegation; history is automatic. + +## Cross-refs + +- Agent base CRUD: [agents-core.md](agents-core.md) +- Team tasks (different concept): [teams-collaboration.md](teams-collaboration.md) diff --git a/claude-skill/references/agents-core.md b/claude-skill/references/agents-core.md new file mode 100644 index 0000000..d4df909 --- /dev/null +++ b/claude-skill/references/agents-core.md @@ -0,0 +1,110 @@ +# Agents — core lifecycle + +## When to use + +User wants to list/inspect/create/update/delete agents, manage agent context files, or control per-user agent instances. + +## Commands in scope + +- `goclaw agents list` / `get ` / `create` / `update ` / `delete ` — base CRUD (source: `cmd/agents.go`) +- `goclaw agents files list/get/create/delete` — agent context files (source: `agents_files.go`, WS-backed) +- `goclaw agents instances list/get/create/delete/trigger/reset` — per-user instances (source: `agents_instances.go`) +- `goclaw agents wake ` — wake sleeping agent (source: `agents_wake.go`) + +## Verified flags + +### `agents create` / `agents update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Display name | +| `--provider

` | string | LLM provider | +| `--model ` | string | Model identifier | +| `--type ` | string | `open` or `predefined` (default `open`) | +| `--context-window ` | int | Context window size | +| `--workspace ` | string | Workspace dir | +| `--budget ` | int | Monthly budget in cents | + +### `agents files create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--data ` | string | File metadata/content | + +### `agents instances list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--user-id ` | string | Filter by user | + +## JSON output + +- ✅ `agents list/get` — JSON (cmd/agents.go:30, :57) +- ✅ `agents instances list/get` — JSON +- ⚠️ `agents create/update/delete/wake` — `printer.Success` text; parse exit code + stdout ID message +- ⚠️ `agents files create/delete` — success text only +- ⚠️ `agents instances create/delete/trigger/reset` — success text + +## Destructive ops + +| Command | Source | Confirm | +| --- | --- | --- | +| `agents delete` | `agents.go:140` tui.Confirm | YES | +| `agents files delete` | `agents_files.go` tui.Confirm | YES | +| `agents instances delete` | `agents_instances.go` tui.Confirm | YES | +| `agents instances reset` | clears instance state | YES | + +## Common patterns + +### Example 1: list + get details +```bash +goclaw agents list --output json +goclaw agents get --output json +``` + +### Example 2: create agent +```bash +goclaw agents create \ + --name "Support Bot" \ + --provider anthropic \ + --model claude-sonnet-4-6 \ + --type open \ + --context-window 200000 \ + --workspace /workspaces/support \ + --budget 5000 \ + --output json +``` + +### Example 3: update model + budget +```bash +goclaw agents update --model claude-opus-4-7 --budget 10000 --output json +``` + +### Example 4: full lifecycle — create → upload file → instance → wake +```bash +goclaw agents create --name "DocBot" --provider openai --model gpt-4o --type open --output json +# → AGENT_ID + +goclaw agents files create --data '{"path":"guide.md","content":"..."}' --output json + +goclaw agents instances create --user-id user-42 --output json +goclaw agents wake +``` + +### Example 5: delete agent (always confirm) +```bash +# Claude: echo back "Delete agent ? This is permanent." before running: +goclaw agents delete --yes +``` + +## Edge cases & gotchas + +- **`--name` sets `display_name`** on create, but update maps flag `--name` to `display_name` field (source: `agents.go:107`). Both work. +- **Agent vs instance:** agent = template, instance = per-user runtime. Delete agent ⇒ cascades instances. List carefully. +- **Files WS-backed:** `agents files` subcommands use WebSocket, not HTTP — same as `teams`. Latency slightly higher but same JSON shape. +- **Budget is cents, not dollars.** $50 = `--budget 5000`. +- **Agent type:** `open` (user-designed prompt) vs `predefined` (built-in role). Check server docs for full list. +- **Wake:** idempotent — waking awake agent is no-op. + +## Cross-refs + +- Sharing, linking, delegation: [agents-advanced.md](agents-advanced.md) +- Chat with agent: [chat-sessions.md](chat-sessions.md) +- Run tools as agent: [exec-workflow.md](exec-workflow.md) diff --git a/claude-skill/references/auth-and-config.md b/claude-skill/references/auth-and-config.md new file mode 100644 index 0000000..a835a4e --- /dev/null +++ b/claude-skill/references/auth-and-config.md @@ -0,0 +1,112 @@ +# Auth & config + +## When to use + +User wants to log in, switch profile/tenant, manage credentials, or configure the server. **Required prerequisite** for any other skill operation. + +## Commands in scope + +- `goclaw auth login [--pair] [--token ...]` — authenticate (source: `cmd/auth.go:20-31`) +- `goclaw auth logout` — remove stored token for active profile +- `goclaw auth whoami` — confirm auth + server reachability +- `goclaw auth use-context ` — switch active profile +- `goclaw auth list-contexts` — list all profiles +- `goclaw auth login --pair` — device pairing (**streaming — skill REFUSES**) +- `goclaw config get/set` — server configuration KV +- `goclaw config permissions list/update/grant/revoke` — per-config ACL (WS) +- `goclaw credentials list/create/delete/rotate` — CLI credential store +- `goclaw api-keys list/create/reveal/revoke/extend` — scoped API keys + +## Global flags (from `cmd/root.go`) + +| Flag | Env var | Purpose | +| --- | --- | --- | +| `--server ` | `GOCLAW_SERVER` | Gateway URL | +| `--token ` | `GOCLAW_TOKEN` | Bearer token (prefer login flow) | +| `--output json\|yaml\|table` | — | Always `json` in skill | +| `--yes` | — | Bypass destructive confirm | +| `--insecure` | — | Skip TLS verify (dev only) | +| `--profile ` | — | Select profile (default: `default`) | +| `--tenant-id ` | — | Multi-tenant scope | +| `--verbose` | — | Debug logs | + +## Verified flags (per subcommand) + +### `auth login` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--pair` | bool | Device pairing (streaming — refuse) | +| `--token` | global | Pass token directly | +| `--profile` | global | Name for profile | + +### `config set` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--key ` | string | Config key | +| `--value ` | string | New value | + +### `api-keys create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Label | +| `--scopes ` | CSV | Permitted scopes | +| `--expires-in ` | duration | TTL e.g. `30d` | + +## JSON output + +- ✅ `auth list-contexts` — JSON list with `--output json` +- ⚠️ `auth login/logout` — `printer.Success` text only; check exit code +- ⚠️ `auth whoami` — table-focused, JSON may be limited +- ✅ `config get` — JSON map +- ⚠️ `config set/permissions grant|revoke` — success text only +- ✅ `credentials list` — JSON list +- ✅ `api-keys list/create` — JSON (create shows raw key ONCE) + +## Destructive ops + +| Command | Why destructive | +| --- | --- | +| `auth logout` | removes credential | +| `config set` | modifies server state | +| `credentials delete` | permanent | +| `credentials rotate` | old key invalidated | +| `api-keys revoke` | permanent | +| `config permissions revoke` | revokes access | + +## Common patterns + +### Example 1: check auth before operations +```bash +goclaw auth whoami --output json +# non-zero exit → tell user to run `goclaw auth login` manually +``` + +### Example 2: one-shot tenant override +```bash +goclaw --tenant-id acme-corp agents list --output json +``` + +### Example 3: switch profile +```bash +goclaw auth list-contexts --output json +goclaw auth use-context staging +``` + +### Example 4: scoped API key for CI +```bash +goclaw api-keys create --name "ci-runner" --scopes "agents:read,sessions:read" --expires-in 90d --output json +# output includes raw key ONCE — user must save it immediately +``` + +## Edge cases & gotchas + +- **Token expiry:** commands exit non-zero — suggest `goclaw auth login`, do NOT retry-loop. +- **`auth pair`:** polls 60× × 2s (120s total) = hits Bash timeout. Skill REFUSES; user runs in own shell. +- **Credentials:** stored in `~/.goclaw/config.yaml` + OS keychain. Never suggest pasting token in chat. +- **Raw API key:** `api-keys create` reveals key ONCE. `api-keys reveal` may only show prefix. +- **Profile precedence:** flags > env > active profile > `default`. + +## Cross-refs + +- After auth: [agents-core.md](agents-core.md), [exec-workflow.md](exec-workflow.md) +- Multi-tenant admin: [admin-system.md](admin-system.md) diff --git a/claude-skill/references/automation-scheduling.md b/claude-skill/references/automation-scheduling.md new file mode 100644 index 0000000..ceb42ca --- /dev/null +++ b/claude-skill/references/automation-scheduling.md @@ -0,0 +1,125 @@ +# Automation & scheduling (cron, heartbeat, devices) + +## When to use + +User wants to schedule recurring agent runs (cron), configure agent heartbeats/health-checks, or manage paired devices. + +## Commands in scope + +### Cron (source: `cmd/cron.go`) — WS-backed +- `goclaw cron list/get/create/update/delete/toggle/status` +- `goclaw cron run ` — manual trigger +- `goclaw cron runs ` — run history + +### Heartbeat (source: `heartbeat.go`, `heartbeat_checklist_targets.go`) +- `goclaw heartbeat get/set` +- `goclaw heartbeat checklist get/set` +- `goclaw heartbeat targets list/add/remove` + +### Devices (source: `devices.go`) +- `goclaw devices list/delete/approve/reject` + +## Verified flags + +### `cron create` (all REQUIRED except `message`, `timezone`) +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | REQUIRED | Agent to trigger | +| `--name ` | REQUIRED | Job name | +| `--schedule ` | REQUIRED | Cron expression (e.g. `"0 9 * * 1"`) | +| `--message ` | string | Payload message | +| `--timezone ` | string | IANA TZ (e.g. `Asia/Saigon`) | + +### `cron update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Rename | +| `--schedule ` | string | Change schedule | + +### `cron runs` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--limit ` | int | Default 20 | + +### `heartbeat set` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Target agent | +| `--interval ` | int | Heartbeat interval | +| `--enabled ` | bool | Turn on/off | + +### `heartbeat targets add/remove` (verify with --help) +Exact flag names depend on CLI version. Run `goclaw heartbeat targets add --help`. + +### `devices approve/reject` (verify with --help) +Exact args (positional vs flag) depend on CLI version. Run `goclaw devices approve --help`. + +## JSON output + +- ✅ `cron list/get/status/runs`, `heartbeat get`, `heartbeat checklist get`, `heartbeat targets list`, `devices list` — JSON +- ⚠️ All `create/update/delete/toggle/run/set/add/remove/approve/reject` — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `cron delete` | YES (loses schedule) | +| `cron toggle` (if disabling) | YES | +| `heartbeat set --enabled=false` | YES (health checks stop) | +| `heartbeat targets remove` | YES | +| `devices delete` | YES (unpairs) | +| `devices reject` | YES (rejects pairing) | + +## Common patterns + +### Example 1: weekday morning agent run +```bash +goclaw cron create \ + --agent \ + --name "Daily triage" \ + --schedule "0 9 * * 1-5" \ + --message "Check overnight tickets" \ + --timezone "Asia/Saigon" \ + --output json +``` + +### Example 2: trigger cron manually + check status +```bash +goclaw cron run +goclaw cron status --output json +goclaw cron runs --limit 5 --output json +``` + +### Example 3: disable cron job temporarily +```bash +# Confirm intent, then: +goclaw cron toggle +``` + +### Example 4: heartbeat configuration +```bash +goclaw heartbeat get --help # always check current flag names +goclaw heartbeat checklist set --data '{"enabled":true,"items":[]}' +``` + +### Example 5: approve paired device +```bash +goclaw devices list --output json +# syntax varies — check help: +goclaw devices approve --help +``` + +## Edge cases & gotchas + +- **Cron is WS primary with HTTP fallback** (source: `cron.go:20-32`). If WS unavailable, some commands fall back to HTTP. +- **Cron expression format:** standard 5-field (min hour day month weekday) OR interval format. Check server parser for extensions. +- **Timezone** is server-interpreted. If omitted, defaults to server TZ (check `goclaw status`). +- **`cron run` is idempotent** but creates a run entry each time — avoid spam clicking. +- **Heartbeat interval minimum:** server-enforced (typically ≥ 30s). Very short intervals rejected. +- **Devices `approve`** requires interactive TUI (source: `devices.go`) — pass `--yes` for automation. +- **`devices delete` after approve** = fully unpair (user must re-pair with fresh code). + +## Cross-refs + +- Device pairing auth flow: [auth-and-config.md](auth-and-config.md) — `auth pair` +- Cron-triggered agent: [agents-core.md](agents-core.md) diff --git a/claude-skill/references/channels-messaging.md b/claude-skill/references/channels-messaging.md new file mode 100644 index 0000000..64351fd --- /dev/null +++ b/claude-skill/references/channels-messaging.md @@ -0,0 +1,110 @@ +# Channels & messaging + +## When to use + +User wants to connect an agent to a messaging platform (Telegram, Discord, Slack, Zalo, Feishu, WhatsApp), manage contacts/writers, or inspect pending messages. + +## Commands in scope + +- `goclaw channels instances list/get/create/update/delete` — channel instance CRUD (source: `channels.go`) +- `goclaw channels contacts list/get/create/delete` — contacts per channel (source: `channels_contacts.go`) +- `goclaw channels pending list` — pending messages on channel (source: `channels_pending.go`) +- `goclaw channels writers list/add/remove` — agent authors for a channel (source: `channels_writers.go`) +- `goclaw contacts list/get/create/update/delete/verify` — global contact book (source: `contacts.go`) +- `goclaw pending-messages list/create/send/delete` — pending message queue (source: `pending_messages.go`) + +## Verified flags + +### `channels instances list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--type ` | string | Filter: `telegram`/`discord`/`slack`/`zalo-oa`/`zalo-personal`/`feishu`/`whatsapp` | + +### `channels instances create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name` (REQUIRED) | string | Instance name | +| `--type` (REQUIRED) | string | Channel type | +| `--agent` (REQUIRED) | string | Agent ID | + +### `channels instances update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Rename | +| `--enabled ` | bool | Enable/disable | + +### `channels writers add/remove` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Writer agent ID | +| `--user ` | string | Or writer user ID | + +### `contacts` lookup helper +| Flag | Type | Purpose | +| --- | --- | --- | +| `--identifier ` | string | Phone number or email (for `contacts resolve`) | + +**Note:** contact create/update field names (name/email/phone) pass through `buildBody` — verify with `goclaw contacts create --help` for current flag names. + +## JSON output + +- ✅ `channels instances list/get`, `channels contacts list/get`, `channels pending list`, `channels writers list`, `contacts list/get`, `pending-messages list` — JSON +- ⚠️ Everything else — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `channels instances delete` | YES (disconnects platform) | +| `channels contacts delete` | YES | +| `channels writers remove` | YES | +| `contacts delete` | YES | +| `pending-messages delete` | YES | +| `pending-messages send` | YES (IRREVERSIBLE user-facing message send) | + +## Common patterns + +### Example 1: list all Telegram channels +```bash +goclaw channels instances list --type telegram --output json +``` + +### Example 2: connect agent to Discord +```bash +goclaw channels instances create \ + --name "support-discord" \ + --type discord \ + --agent \ + --output json +``` + +### Example 3: add writer to channel +```bash +goclaw channels writers add --agent # add agent as writer +# or user: +goclaw channels writers add --user +``` + +### Example 4: send pending message (always confirm) +```bash +# Claude: echo message content back to user for confirmation +goclaw pending-messages send --yes +``` + +### Example 5: contact verify +```bash +goclaw contacts verify --output json +``` + +## Edge cases & gotchas + +- **Channel credentials** (bot tokens for Telegram/Discord) stored server-side, not in CLI. `create` may require follow-up `update` via dashboard to set API keys. +- **Channel instance vs contact:** instance = platform link (one per channel+tenant); contact = person on the platform. Writers = agents/users authorized to send from the instance. +- **`pending-messages send` is USER-facing** — the message is delivered to external user once sent. No undo. ALWAYS confirm content with user first. +- **Zalo variants:** `zalo-oa` = official account (business), `zalo-personal` = personal user flow. Different auth model. +- **`contacts verify`** triggers OTP/email flow — user must complete verification out-of-band. + +## Cross-refs + +- Configure TTS for channels: [admin-system.md](admin-system.md) — `tts status` +- Agent that owns the channel: [agents-core.md](agents-core.md) diff --git a/claude-skill/references/chat-sessions.md b/claude-skill/references/chat-sessions.md new file mode 100644 index 0000000..05608f0 --- /dev/null +++ b/claude-skill/references/chat-sessions.md @@ -0,0 +1,99 @@ +# Chat & sessions + +## When to use + +User wants to send a message to an agent, inject input mid-run, abort a running agent, or inspect/clean up chat sessions. + +## Commands in scope + +- `goclaw chat -m "" --no-stream` — single-shot (source: `cmd/chat.go:44-47`) +- `goclaw chat inject --text "..."` — inject into running session +- `goclaw chat status ` — session run status (WS call `chat.session.status`) +- `goclaw chat abort ` — abort running agent (WS call `chat.abort`) +- `goclaw sessions list` / `get` / `preview ` / `delete` / `reset` / `label` — session CRUD +- `goclaw chat ` *without* `-m` → **interactive REPL, skill REFUSES** + +## Verified flags + +### `chat ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-m, --message` | string | Single-shot message (source: `cmd/chat.go:280`) | +| `--session ` | string | Continue existing session | +| `--no-stream` | bool | Wait for full response instead of streaming | + +### `chat inject` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--text` | string (required) | Text to inject | +| `--session` | string | Session key | + +### `sessions list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent` | string | Filter by agent ID | +| `--user` | string | Filter by user ID | +| `--limit` | int | Max results | + +### `sessions label` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--label` | string (required) | New label | + +## JSON output + +- ✅ `chat -m ... --output json` — NDJSON event stream (`chat.go:92-98`) +- ✅ `chat -m ... --no-stream --output json` — single JSON map +- ✅ `sessions list/preview` — JSON +- ⚠️ `sessions delete/reset/label` — `printer.Success` text only + +## Destructive ops + +| Command | Why destructive | +| --- | --- | +| `sessions delete` | drops session + messages (tui.Confirm at `sessions.go:80`) | +| `sessions reset` | clears messages, keeps key (tui.Confirm at `sessions.go:101`) | +| `chat abort` | force-stops running agent mid-tool-call — **no `--yes` flag**, still warn user | + +## Common patterns + +### Example 1: single-shot question +```bash +goclaw chat my-agent -m "Summarize today's activity" --no-stream --output json +``` + +### Example 2: continue previous session +```bash +goclaw chat my-agent -m "Based on that, what next?" --session sess_abc --output json +``` + +### Example 3: pipe stdin +```bash +echo "Analyze this log" | goclaw chat my-agent --output json +``` + +### Example 4: list sessions for agent + preview one +```bash +goclaw sessions list --agent --limit 10 --output json +goclaw sessions preview --output json +``` + +### Example 5: abort runaway agent +```bash +# Always confirm with user first +goclaw chat abort my-agent --session +``` + +## Edge cases & gotchas + +- **Interactive mode detection:** `chat ` with no `-m` and no stdin → TUI REPL with `/exit`, `/abort`, `/sessions`, `/clear` slash commands (`chat.go:148`). Skill MUST always pass `-m` or pipe stdin. +- **Streaming NDJSON:** when `--output json` without `--no-stream`, each event is a JSON line: `{"event":"chunk|tool.call|tool.result|run.completed","data":{...}}`. Parse line-by-line, stop at `run.completed`. +- **`chat abort` is not streaming.** Safe to call. But recovers no work done before abort. +- **Session key vs session ID:** API uses `session_key` (human-readable, stable across resets); list shows both. +- **Token accounting:** `sessions list --output json` includes `input_tokens`/`output_tokens` per session — useful for cost tracing. + +## Cross-refs + +- Approvals from tool calls: [exec-workflow.md](exec-workflow.md) (canonical home) +- Agent lifecycle: [agents-core.md](agents-core.md) +- Traces per LLM call: [monitoring-ops.md](monitoring-ops.md) diff --git a/claude-skill/references/data-movement.md b/claude-skill/references/data-movement.md new file mode 100644 index 0000000..f3b9355 --- /dev/null +++ b/claude-skill/references/data-movement.md @@ -0,0 +1,110 @@ +# Data movement — export / import / storage + +## When to use + +User wants to export agents/teams/skills/mcp configs for backup or porting, import previously exported bundles, or manage workspace files (upload/download/move/delete). + +## Commands in scope + +### Export (source: `cmd/export_import.go`) +- `goclaw export -preview ` — preview export JSON (safe, no side-effects) +- `goclaw export [-f ]` — export to file +- `` ∈ `agent` / `team` / `skills` / `mcp` + +### Import (source: `cmd/export_import.go`) +- `goclaw import -preview ` — preview import (no writes) +- `goclaw import --yes` — apply import (OVERWRITES) + +### Storage (source: `cmd/storage.go`) +- `goclaw storage list [--path ]` — list files +- `goclaw storage get [-f ]` — download file (or stdout) +- `goclaw storage download [-f ]` — forced download with Content-Disposition +- `goclaw storage delete ` — remove file +- `goclaw storage move --from --to ` — rename/move +- `goclaw storage size` — usage stats + +## Verified flags + +### `storage list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--path ` | string | Sub-directory filter | + +### `storage get` / `storage download` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-f, --output ` | string | Write to file (default stdout) | + +### `storage move` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--from ` (REQUIRED) | string | Source path | +| `--to ` (REQUIRED) | string | Destination path | + +### `export agent` / `export ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-f, --output ` | string | Output file (defaults to `-.json`) | + +## JSON output + +- ✅ `storage list`, `storage size` — JSON +- ✅ All `export *-preview` and `import *-preview` — JSON +- ⚠️ `storage get/download` — raw file bytes (not JSON); Claude must avoid piping large binaries into context +- ⚠️ `storage delete/move/put`, `import *` — success text only +- ⚠️ `export ` (non-preview) — writes file; success text to stdout + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `storage delete` | YES (permanent) | +| `storage move` | YES (if overwriting destination) | +| `import ` with `--yes` | YES — OVERWRITES existing resource | + +## Common patterns + +### Example 1: preview + export agent +```bash +goclaw export agent-preview --output json +goclaw export agent -f /tmp/agent-backup.json +``` + +### Example 2: import with dry-run preview first +```bash +goclaw import agent-preview /tmp/agent-backup.json --output json +# review, then apply: +goclaw import agent /tmp/agent-backup.json --yes +``` + +### Example 3: list + download workspace file +```bash +goclaw storage list --path projects/ --output json +goclaw storage get projects/plan.md -f /tmp/plan.md +``` + +### Example 4: move file +```bash +goclaw storage move --from drafts/post.md --to published/post.md +``` + +### Example 5: check storage quota +```bash +goclaw storage size --output json +# → {"used_bytes": N, "quota_bytes": M, ...} +``` + +## Edge cases & gotchas + +- **Large exports/imports** may exceed Bash tool 120s timeout. For big agents (many files, long memory), recommend user run manually or use `--output` to file and process offline. +- **Storage paths** are NOT URL-escaped by CLI (source: `storage.go:25-27`, "Don't escape path separators"). Server expects raw. Spaces/unicode may fail — warn user. +- **`storage get` with no `-f`** writes to stdout. Binary files will corrupt Claude's context. Always use `-f` for non-text. +- **Import overwrites by default.** No diff view on apply. Always preview first. +- **Export bundles** include agent/team IDs — re-importing to same server creates duplicates unless server dedupes on key. Check server behavior. +- **Resource types:** only 4 supported — `agent`/`team`/`skills`/`mcp`. Others (channels, memory, sessions) can't be exported this way. + +## Cross-refs + +- Skills upload (different from export): [providers-skills-tools.md](providers-skills-tools.md) +- Media upload/download (separate from storage): [media.md](media.md) +- Memory docs (agent-scoped, not tenant-storage): [knowledge-memory.md](knowledge-memory.md) diff --git a/claude-skill/references/docs-api.md b/claude-skill/references/docs-api.md new file mode 100644 index 0000000..982a262 --- /dev/null +++ b/claude-skill/references/docs-api.md @@ -0,0 +1,52 @@ +# Docs & API + +## When to use + +User asks about server REST API endpoints, OpenAPI spec, or how to call the server directly. + +## Commands in scope + +- `goclaw api-docs spec` — fetch OpenAPI/JSON spec (source: `cmd/api_docs.go`) +- `goclaw api-docs open` — **launches system browser — skill REFUSES** (not useful from Claude) + +## Verified flags + +### `api-docs spec` +No specific flags beyond globals. Use `--output json` to get spec as parseable JSON. + +### `api-docs open` +No flags. Attempts to run `open` (macOS), `xdg-open` (Linux), or `rundll32` (Windows). + +## JSON output + +- ✅ `api-docs spec --output json` — full OpenAPI JSON spec +- ⚠️ `api-docs open` — no output, just spawns browser + +## Destructive ops + +None. + +## Common patterns + +### Example 1: fetch spec for analysis +```bash +goclaw api-docs spec --output json > /tmp/openapi.json +# then use jq/yq to explore endpoints +jq '.paths | keys' /tmp/openapi.json +``` + +### Example 2: user asks "what endpoints exist for agents?" +```bash +goclaw api-docs spec --output json | jq '.paths | to_entries[] | select(.key | contains("agents"))' +``` + +## Edge cases & gotchas + +- **`api-docs open`:** skill MUST refuse. Browser launch is useless in Claude Code context. Suggest `api-docs spec` instead. +- **Spec format:** OpenAPI 3.x JSON. Large (often >500KB). Don't dump whole spec into chat — pipe through jq with a filter. +- **Auth:** spec endpoint may require auth on some deployments. If 401, run `goclaw auth login`. + +## Cross-refs + +- Direct HTTP if spec doesn't cover: see server repo documentation +- CLI commands mirror most of API: [agents-core.md](agents-core.md), [chat-sessions.md](chat-sessions.md), etc. diff --git a/claude-skill/references/exec-workflow.md b/claude-skill/references/exec-workflow.md new file mode 100644 index 0000000..d114817 --- /dev/null +++ b/claude-skill/references/exec-workflow.md @@ -0,0 +1,133 @@ +# Exec workflow (hero use case) + +## When to use + +User wants to run a shell command on a GoClaw server, invoke any built-in tool directly, or approve/deny an agent's pending execution. This is the #1 reason to use the skill. + +## Commands in scope + +- `goclaw tools invoke --param =` — invoke any built-in tool (source: `cmd/tools.go:111-144`) +- `goclaw tools builtin list` — discover available tool names (source: `cmd/tools.go:18-32`) +- `goclaw approvals list` — pending execution approvals (WS call: `exec.approval.list`, source: `cmd/admin.go:15-41`) +- `goclaw approvals approve ` — approve pending exec (WS call: `exec.approval.approve`) +- `goclaw approvals deny --reason "..."` — deny (WS call: `exec.approval.deny`) + +## Verified tool: `exec` + +**Server registration** (source: `goclaw/cmd/gateway_builtin_tools.go:24`): +```go +{Name: "exec", DisplayName: "Execute Command", Category: "runtime", Enabled: true} +``` + +**Parameter schema** (source: `goclaw/internal/tools/shell.go:114-128`): + +| Param | Type | Required | Purpose | +| --- | --- | --- | --- | +| `command` | string | ✅ yes | Shell command to execute | +| `working_dir` | string | no (default workspace root) | CWD for the command | + +**Response:** stdout + stderr + exit_code in `*Result` struct. + +**Safety rails on server side:** +- NUL byte rejection (exits with "command contains invalid NUL byte") +- Unicode normalization (NFKC + zero-width strip) before deny-pattern matching +- Shell deny patterns (per-agent or default) block dangerous ops +- Package installs trigger approval gate (not auto-executed) + +## Verified flags + +### `goclaw tools invoke ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--param key=value` | repeatable string | One param per flag | +| `--params ''` | string | Alternative: all params as JSON | +| `--output json` | global | Mandatory per skill convention | + +### `goclaw approvals deny ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--reason "..."` | string | Denial reason (optional) | + +## JSON output + +- ✅ `tools invoke` — `printer.Print(unmarshalMap(data))` at `cmd/tools.go:141` +- ✅ `tools builtin list` — `printer.Print(unmarshalList(data))` at `cmd/tools.go:29` +- ⚠️ `approvals approve/deny` — returns `printer.Success("Execution approved/denied")` text; check exit code instead of parsing JSON +- ✅ `approvals list` — JSON via `unmarshalList` + +## Destructive ops + +| Command | Why destructive | Confirm required? | +| --- | --- | --- | +| `tools invoke exec --param command="rm ..."` | runs arbitrary shell | **YES** — always confirm the command string with user before invoking | +| `tools invoke exec` with package-install command | server triggers approval gate, but skill should still confirm | YES | +| `approvals deny ` | denies agent's pending action | YES if dense consequences | + +**Rule:** Always echo back the exact `command` param to user and ask *"run this command on the server? (y/N)"* before invoking. + +## Common patterns + +### Example 1: innocuous read-only command + +```bash +goclaw tools invoke exec --param command="uname -a" --output json +``` + +Expected shape: +```json +{"stdout": "Linux ...", "stderr": "", "exit_code": 0, "approval_required": false} +``` + +### Example 2: command with custom working directory + +```bash +goclaw tools invoke exec \ + --param command="npm test" \ + --param working_dir="/workspace/my-app" \ + --output json +``` + +### Example 3: command that triggers approval gate + +```bash +# First attempt — server may return approval_required=true or an approval_id +goclaw tools invoke exec --param command="apt-get install curl" --output json + +# Check pending approvals +goclaw approvals list --output json + +# Approve the specific request +goclaw approvals approve + +# Re-run if needed +goclaw tools invoke exec --param command="apt-get install curl" --output json +``` + +### Example 4: discover available tools before invoking + +```bash +goclaw tools builtin list --output json +# returns: exec, read_file, write_file, web_search, web_fetch, memory_search, ... +``` + +### Example 5: invoke non-exec builtin tool + +```bash +goclaw tools invoke memory_search --param query="Q3 roadmap" --output json +goclaw tools invoke web_fetch --param url="https://example.com" --output json +``` + +## Edge cases & gotchas + +- **Streaming approvals:** `approvals watch` (if present) uses WS subscribe — NOT Bash-friendly. Use `approvals list --output json` polling instead. +- **NUL bytes in command:** server rejects; Claude should reject `\x00` before calling. +- **Approval ID lifetime:** approvals expire; poll quickly after an exec returns `approval_required`. +- **Params format:** both `--param k=v` and `--params ''` work. For values with `=` or spaces, prefer `--params`. +- **Empty stdout:** `exit_code: 0` with empty `stdout` is success — don't retry. +- **No `exec` tool (404):** run `tools builtin list` first — admin may have disabled it. + +## Cross-refs + +- Tool mgmt (enable/disable/tenant-config): [providers-skills-tools.md](providers-skills-tools.md) +- Auth required first: [auth-and-config.md](auth-and-config.md) +- Session context: [chat-sessions.md](chat-sessions.md) diff --git a/claude-skill/references/knowledge-memory.md b/claude-skill/references/knowledge-memory.md new file mode 100644 index 0000000..7392cab --- /dev/null +++ b/claude-skill/references/knowledge-memory.md @@ -0,0 +1,121 @@ +# Knowledge graph & memory + +## When to use + +User wants to store/retrieve agent memory docs (key-value-ish, with semantic search), or manage the agent's knowledge graph (entities + relations), or run entity deduplication. + +## Commands in scope + +### Memory (source: `cmd/memory.go`) +- `goclaw memory list ` — list documents +- `goclaw memory get ` — fetch document +- `goclaw memory store --content ` — upsert +- `goclaw memory delete ` — delete document +- `goclaw memory search --query "..."` — semantic search + +### Knowledge Graph (source: `cmd/knowledge_graph.go`, alias `kg`) +- `goclaw kg entities list/get/create/delete ` +- `goclaw kg traverse --from ` +- `goclaw kg graph ` — full graph dump +- `goclaw kg stats ` — node/edge counts +- `goclaw kg query [--entity ]` — legacy query (source: `memory.go:121-141`) +- `goclaw kg extract --text "..."` — extract entities from text +- `goclaw kg link --from --to --relation ` — create link + +### Dedup (source: `cmd/knowledge_graph_dedup.go`) +- `goclaw kg dedup scan ` — scan for duplicates +- `goclaw kg dedup merge-candidates ` — list candidate pairs +- `goclaw kg dedup execute-merge --pair ` — **IRREVERSIBLE merge** + +## Verified flags + +### `memory list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--user ` | string | Filter by user | + +### `memory store` / `kg extract` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--content ` (memory store) | string (REQUIRED) | Value or `@filepath` | +| `--text ` (kg extract) | string (REQUIRED) | Text or `@filepath` | + +### `memory search` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--query ` | string (REQUIRED) | Search query | +| `--user ` | string | Filter by user | + +### `kg entities create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--data ` | string (REQUIRED) | Entity body JSON or `@filepath` | + +### `kg traverse` / `kg link` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--from ` | string (REQUIRED) | Start entity | +| `--to ` | string (link only, REQUIRED) | Target | +| `--relation ` | string (link only, REQUIRED) | Relation type | + +## JSON output + +- ✅ All `list/get/search/query/graph/stats/traverse` — JSON +- ✅ `kg entities create` — JSON +- ⚠️ `memory store/delete`, `kg link`, `kg dedup execute-merge` — success text + +## Destructive ops + +| Command | Source | Confirm | +| --- | --- | --- | +| `memory delete` | `memory.go:83` tui.Confirm | YES | +| `kg entities delete` | `knowledge_graph.go:85` tui.Confirm | YES | +| `kg dedup execute-merge` | **IRREVERSIBLE** | YES — always confirm pair | +| `memory clear` (if exists) | wipes all memory for agent | YES — high blast radius | + +## Common patterns + +### Example 1: store + retrieve memory doc +```bash +goclaw memory store projects/q3-roadmap --content "@./roadmap.md" +goclaw memory get projects/q3-roadmap --output json +``` + +### Example 2: semantic search memory +```bash +goclaw memory search --query "customer churn analysis" --output json +``` + +### Example 3: extract entities + link +```bash +goclaw kg extract --text "Alice works at Acme Corp" --output json +goclaw kg link --from "Alice" --to "Acme Corp" --relation "works_at" +``` + +### Example 4: dedup workflow +```bash +goclaw kg dedup scan --output json +goclaw kg dedup merge-candidates --output json +# review pairs, then explicit merge: +goclaw kg dedup execute-merge --pair # CONFIRM FIRST +``` + +### Example 5: graph overview +```bash +goclaw kg stats --output json +goclaw kg graph --output json | jq '.nodes | length' +``` + +## Edge cases & gotchas + +- **`--content` / `--text` with `@file`:** `readContent()` dereferences `@path` to file contents — write prompt handles both, no escaping needed. +- **`memory store` overwrites** silently at same path. No version history at CLI level. +- **`kg dedup execute-merge`** merges entities + their relations + their memory refs — cannot split back. Always list candidates first. +- **Memory path namespace:** paths are slash-separated (`projects/q3-roadmap`), can contain slashes but no leading `/`. URL-encoded on the wire. +- **`memory.clear` command:** check binary — may or may not be present. If invoked, clears ENTIRE agent memory — skill must force explicit double-confirm. +- **KG endpoints scoped per-agent:** all routes under `/v1/agents//kg/...`. No global-tenant graph. + +## Cross-refs + +- Built-in tools for agent-side memory access: [providers-skills-tools.md](providers-skills-tools.md) — `memory_search`, `knowledge_graph_search` tools +- Agent base: [agents-core.md](agents-core.md) diff --git a/claude-skill/references/mcp-integration.md b/claude-skill/references/mcp-integration.md new file mode 100644 index 0000000..c7025a0 --- /dev/null +++ b/claude-skill/references/mcp-integration.md @@ -0,0 +1,115 @@ +# MCP integration + +## When to use + +User wants to manage Model Context Protocol (MCP) servers the agents connect to — add/remove MCP servers, grant/revoke agent access, review incoming connection requests, or trigger reconnections. + +## Commands in scope + +- `goclaw mcp servers list/get/create/update/delete` — MCP server CRUD (source: `cmd/mcp.go`) +- `goclaw mcp servers test ` — sync test call +- `goclaw mcp grants list/grant/revoke` — per-agent access +- `goclaw mcp requests list/approve/deny` — inbound connection requests +- `goclaw mcp reconnect ` — **async** trigger reconnection (source: `mcp_reconnect.go`) + +## Verified flags + +### `mcp servers create` (verified from cmd/mcp.go) +| Flag | Type | Default | Purpose | +| --- | --- | --- | --- | +| `--name ` | string | — | Server name | +| `--transport ` | string | `stdio` | `stdio`/`sse`/`streamable-http` | +| `--command ` | string | — | Launch command (stdio) | +| `--args ` | string slice | — | Command args (repeatable) | +| `--url ` | string | — | Endpoint (sse/http) | +| `--prefix

` | string | — | Tool prefix | +| `--timeout ` | int | 60 | Timeout seconds | + +**Note:** env vars for stdio MCP set via server-side config, not CLI flag. + +### `mcp grants grant/revoke` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Agent to grant/revoke | +| `--server ` | string | MCP server | + +### `mcp requests approve/deny` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--reason ` | string | (deny only) reason | + +## JSON output + +- ✅ `mcp servers list/get/test`, `mcp grants list`, `mcp requests list` — JSON +- ⚠️ `mcp servers create/update/delete`, `grants grant/revoke`, `requests approve/deny`, `mcp reconnect` — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `mcp servers delete` | YES (agents lose tools) | +| `mcp grants revoke` | YES | +| `mcp requests deny` | YES | + +## Common patterns + +### Example 1: register stdio MCP server +```bash +goclaw mcp servers create \ + --name github \ + --transport stdio \ + --command "npx" \ + --args "@modelcontextprotocol/server-github" \ + --output json +# env vars (like GITHUB_TOKEN) configure via dashboard/server config after create +``` + +### Example 2: register HTTP MCP server +```bash +goclaw mcp servers create \ + --name remote-tools \ + --transport streamable-http \ + --url "https://mcp.example.com/sse" \ + --output json +``` + +### Example 3: test connectivity +```bash +goclaw mcp servers test --output json +# → {"ok": true, "tools_count": 12, ...} +``` + +### Example 4: grant MCP server to agent +```bash +goclaw mcp grants grant --agent --server +goclaw mcp grants list --agent --output json +``` + +### Example 5: approve inbound connection request +```bash +goclaw mcp requests list --output json +goclaw mcp requests approve +``` + +### Example 6: force reconnect +```bash +# After config change or server restart +goclaw mcp reconnect +# async — no return value; check with test +goclaw mcp servers test --output json +``` + +## Edge cases & gotchas + +- **`mcp reconnect` is async.** Fire-and-forget. Check health via `test`. +- **`mcp servers test` is sync.** Returns tool inventory snapshot. +- **Transport mix:** stdio runs subprocess on server, streamable-http/sse connects out to URL. Security implications differ. +- **Env vars for stdio MCP:** configured server-side (dashboard or `system-config`), NOT via CLI flag. +- **Request approval:** external MCP clients request to connect; admin approves via `mcp requests approve`. Check list regularly. +- **Grant scope:** MCP server grants are per-agent. No tenant-level grant. +- **Reconnect on network blip:** servers with transient failures auto-reconnect; manual reconnect for config changes. + +## Cross-refs + +- Built-in tools (different mechanism): [providers-skills-tools.md](providers-skills-tools.md) — `tools builtin` +- Invoke tools (built-in or MCP): [exec-workflow.md](exec-workflow.md) diff --git a/claude-skill/references/media.md b/claude-skill/references/media.md new file mode 100644 index 0000000..84ca250 --- /dev/null +++ b/claude-skill/references/media.md @@ -0,0 +1,65 @@ +# Media + +## When to use + +User wants to upload or download media files (images, audio, video, documents) to/from the GoClaw server. These are distinct from workspace `storage` (which is generic files) and from skill uploads. + +## Commands in scope + +- `goclaw media upload ` — upload local file (source: `cmd/admin_media.go`) +- `goclaw media download [-f ]` — download by media ID + +## Verified flags + +### `media upload` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--type ` | string | `image`/`audio`/`video`/`document` | +| `--description ` | string | Optional label | + +### `media download` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-f, --output ` | string | Output file (default stdout) | + +## JSON output + +- ⚠️ `media upload` — success text with ID; parse from stdout or rely on exit code +- ⚠️ `media download` — raw binary; always use `-f` + +## Destructive ops + +None — upload/download are non-destructive (though upload counts against storage quota). + +## Common patterns + +### Example 1: upload image +```bash +goclaw media upload ./screenshot.png --type image --description "Bug repro" --output json +# → returns media ID for later download +``` + +### Example 2: download by ID +```bash +goclaw media download -f /tmp/out.png +``` + +### Example 3: upload + immediately use as context +```bash +# Upload returns ID; feed into agent's context somehow (via memory store or chat message) +MEDIA_ID=$(goclaw media upload ./doc.pdf --type document --output json | jq -r '.id') +goclaw memory store attachments/doc.pdf --content "@./doc.pdf" +``` + +## Edge cases & gotchas + +- **Large files** hit Bash tool timeout (120s). For files > 10 MB, recommend user runs CLI directly in their terminal. +- **MIME type** inferred server-side from extension; `--type` is a semantic bucket (image/audio/etc.), not MIME. +- **Download binary → stdout corruption:** Claude MUST always pass `-f` to redirect. Never `goclaw media download` without output redirection. +- **Upload quota:** counts against tenant storage quota. Check `goclaw storage size --output json` for remaining. +- **Media vs storage:** media = semantic assets referenced by agents/chats; storage = generic file browser. Don't confuse paths. + +## Cross-refs + +- Workspace file management: [data-movement.md](data-movement.md) — `storage` +- Media tools for agents (read_image, read_document, etc.): [providers-skills-tools.md](providers-skills-tools.md) diff --git a/claude-skill/references/monitoring-ops.md b/claude-skill/references/monitoring-ops.md new file mode 100644 index 0000000..6d4066a --- /dev/null +++ b/claude-skill/references/monitoring-ops.md @@ -0,0 +1,105 @@ +# Monitoring & ops + +## When to use + +User wants to check server health, view metadata, inspect LLM traces, watch usage/cost, or tail logs. + +## Commands in scope + +- `goclaw health` — HTTP health check (source: `cmd/status.go:12-26`) +- `goclaw status` — server status + metadata (WS call `status`, source: `cmd/status.go:28-75`) +- `goclaw version` — CLI version info +- `goclaw traces list` / `get ` / `export ` — LLM traces +- `goclaw usage summary` / `detail` / `trends` / `export` — cost analytics +- `goclaw logs tail` — **STREAMING, skill REFUSES** (source: `cmd/logs.go`) + +## Verified flags + +### `traces list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Filter by agent | +| `--status ` | string | `running` / `success` / `error` | +| `--limit ` | int | Max results (default 20) | + +### `traces export` +| Flag | Type | Purpose | +| --- | --- | --- | +| `-f, --output ` | string | Output file (default `.json.gz`) | + +### `usage summary` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--from ` | string | Start date (ISO) | +| `--to ` | string | End date (ISO) | + +### `usage detail` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent ` | string | Filter by agent | +| `--provider

` | string | Filter by provider | + +### `logs tail` (refuse — streaming) +| Flag | Type | Purpose | +| --- | --- | --- | +| `--agent` | string | Filter by agent ID | +| `--level` | string | `info` / `warn` / `error` | +| `--follow` | bool | Follow (default true) | + +## JSON output + +- ⚠️ `health` — `printer.Success` text only; check exit code (0 = healthy) +- ✅ `status` — JSON map via WS `status` call +- ⚠️ `version` — plaintext multi-line (not JSON) +- ✅ `traces list/get` — JSON +- ⚠️ `traces export` — writes gzip file, success text +- ✅ `usage summary/detail` — JSON +- ⚠️ `logs tail` — streams NDJSON but long-running; skill refuses + +## Destructive ops + +None — this cluster is read-only. + +## Common patterns + +### Example 1: health + status combo +```bash +goclaw health # exit 0 = healthy (ignore stdout) +goclaw status --output json +``` + +### Example 2: look at recent LLM runs +```bash +goclaw traces list --limit 10 --status error --output json +goclaw traces get --output json +``` + +### Example 3: weekly cost breakdown +```bash +goclaw usage summary --from 2026-04-10 --to 2026-04-17 --output json +goclaw usage detail --agent --output json +``` + +### Example 4: export trace for offline review +```bash +goclaw traces export -f /tmp/t.json.gz +# file is gzipped JSON — user unzips locally +``` + +### Example 5: `logs tail` alternative +Skill refuses streaming. Suggest: +> *"`logs tail` is a real-time stream and I can't run it through Bash. Please run `goclaw logs tail --agent ` in your own terminal, or let me query recent errors via `traces list --status error`."* + +## Edge cases & gotchas + +- **`status` WS fallback:** if WS handshake returns metadata, CLI returns that instead of calling `status` method (source: `status.go:48-52`). Both shapes valid. +- **`traces export` writes gzipped JSON** — users opening in editor see binary garbage unless they `gunzip` first. +- **Usage date format:** ISO-8601 (`YYYY-MM-DD`). Invalid dates → server 400. +- **Health vs status:** `health` is unauthenticated (no token needed); `status` requires auth + WS. +- **Cost figures** in `usage.*` responses are in cents per line item; sum carefully. + +## Cross-refs + +- Audit log (who did what): [admin-system.md](admin-system.md) → `activity list` +- MCP connection health: [mcp-integration.md](mcp-integration.md) +- Session-level tokens: [chat-sessions.md](chat-sessions.md) diff --git a/claude-skill/references/providers-skills-tools.md b/claude-skill/references/providers-skills-tools.md new file mode 100644 index 0000000..de9268f --- /dev/null +++ b/claude-skill/references/providers-skills-tools.md @@ -0,0 +1,139 @@ +# Providers, skills & tools registry + +## When to use + +User wants to manage LLM providers (register API keys for OpenAI/Anthropic/Gemini/etc.), publish/install/grant skills, enable/disable built-in tools, or inspect runtime packages. For *invoking* tools (including `exec`), see [exec-workflow.md](exec-workflow.md). + +## Commands in scope + +### Providers (source: `cmd/providers.go`, `providers_crud.go`) +- `goclaw providers list/get/create/update/delete` — provider CRUD +- `goclaw providers models ` — list models for a provider +- `goclaw providers verify-embedding ` — test embedding endpoint + +### Skills (source: `cmd/skills.go`, `skills_*.go`) +- `goclaw skills list/get/update/delete/toggle` — skill CRUD +- `goclaw skills upload ` — upload skill bundle (multipart) +- `goclaw skills publish/unpublish ` — visibility toggle +- `goclaw skills versions ` — version history +- `goclaw skills grant/revoke` — per-agent skill access (source: `skills_grants.go`) +- `goclaw skills tenant-config set/delete` — tenant-level skill config +- `goclaw skills files list/get/create/delete` — skill content files + +### Tools registry (source: `cmd/tools.go`) +- `goclaw tools builtin list/get/update ` — list/configure builtins +- `goclaw tools builtin tenant-config set/delete ` — per-tenant tool enable +- `goclaw tools invoke ` — see [exec-workflow.md](exec-workflow.md) + +### Packages (source: `cmd/packages.go`) +- `goclaw packages list` — runtime packages (read-only) + +## Verified flags + +### `providers create/update` (verify with `goclaw providers create --help`) +Common fields passed via `buildBody` — names depend on CLI release. Typical: +- `--name ` — provider slug +- `--display-name ` — UI label +- `--api-key ` — API key +- `--type ` — provider type (openai/anthropic/gemini/...) + +Run `goclaw providers create --help` for current flag list; endpoint override flag name varies. + +### `skills list` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--search ` | string | Full-text search | + +### `skills upload` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Override skill name | +| `--visibility ` | string | `private`/`shared` (default `private`) | + +### `skills update` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Rename | +| `--visibility ` | string | Change visibility | + +### `tools builtin update ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--enabled ` | bool | Enable/disable tool globally | + +### `tools builtin tenant-config set ` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--enabled ` | bool | Per-tenant enable override | + +## JSON output + +- ✅ `providers list/get/models`, `skills list/get/versions`, `tools builtin list/get`, `packages list` — JSON +- ⚠️ `providers create/update/delete/verify-embedding`, `skills upload/update/delete/toggle/publish/unpublish/grant/revoke`, `tools builtin update/tenant-config *` — success text + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `providers delete` | YES (agents using provider break) | +| `skills delete` | YES (agents lose skill) | +| `skills unpublish` | YES (hides from catalog) | +| `skills revoke` | YES | +| `skills tenant-config delete` | YES | +| `tools builtin update --enabled=false` | YES (agents lose tool) | +| `tools builtin tenant-config delete` | YES | + +## Common patterns + +### Example 1: register OpenAI provider +```bash +# Always --help first for current flag names +goclaw providers create --help +goclaw providers create \ + --name openai \ + --display-name "OpenAI" \ + --type openai \ + --api-key sk-... \ + --output json +``` + +### Example 2: verify provider works +```bash +goclaw providers verify-embedding --output json +# → {"ok": true, "latency_ms": 120, ...} +``` + +### Example 3: list + grant skill to agent +```bash +goclaw skills list --search "docs" --output json +# verify exact grant flags (may be --skill-id/--agent or similar): +goclaw skills grant --help +``` + +### Example 4: disable dangerous builtin tool globally +```bash +# Claude: confirm with user first — disabling exec breaks agent workflows +goclaw tools builtin update exec --enabled=false +``` + +### Example 5: tenant-specific tool override +```bash +# Disable web_search for tenant "acme" only +goclaw --tenant-id acme tools builtin tenant-config set web_search --enabled=false +``` + +## Edge cases & gotchas + +- **Skills upload** is multipart form; path can be dir or .zip. Server unpacks. File size limits set server-side — check server docs. +- **`skills toggle`** flips enabled-state but doesn't distinguish from `update --enabled` — both work. +- **Providers `api-key`** stored encrypted server-side. `providers get` masks the key in response. +- **Tool `enabled=false` cascades:** agents using the tool get "tool not found" on invocation. Coordinate with agent owners before disabling. +- **Tenant-config vs global update:** `tools builtin update` affects all tenants; `tenant-config set` overrides for one tenant. Use tenant-config when possible. +- **Packages is read-only.** No install/uninstall via CLI — managed server-side. +- **Skills versioning:** `skills versions ` lists all published versions; agents pin a specific version. + +## Cross-refs + +- Invoke tools (exec, etc.): [exec-workflow.md](exec-workflow.md) +- Agent-scoped skill grants: [agents-core.md](agents-core.md) +- MCP tools (separate concept): [mcp-integration.md](mcp-integration.md) diff --git a/claude-skill/references/teams-collaboration.md b/claude-skill/references/teams-collaboration.md new file mode 100644 index 0000000..cfe07b7 --- /dev/null +++ b/claude-skill/references/teams-collaboration.md @@ -0,0 +1,92 @@ +# Teams — collaboration + +## When to use + +User wants to inspect/manage agent teams, add/remove members, create/approve team tasks, or access a team's shared workspace. **All teams ops are WebSocket-backed** (source: `cmd/teams*.go`); no HTTP fallback. + +## Commands in scope + +- `goclaw teams list/get/create/update/delete` — team CRUD (source: `teams.go`, `teams_extra.go`) +- `goclaw teams members list/add/remove/reassign` — membership (source: `teams_members.go`) +- `goclaw teams events ` — **STREAMING WS subscribe, skill REFUSES** +- `goclaw teams tasks list/get/create/delete/approve/reject/reassign` — task board (source: `teams_tasks*.go`) +- `goclaw teams workspace list/get/put/delete` — team file workspace (source: `teams_workspace.go`) + +## Verified flags (typical — verify per subcommand via `goclaw teams --help`) + +### `teams create` +| Flag | Type | Purpose | +| --- | --- | --- | +| `--name ` | string | Team name | +| `--agents ` | CSV | Initial agent list | + +### `teams members add` / `remove` +| Flag | Type | Purpose | +| --- | --- | --- | +| (team-id arg) | positional | Parent team (verify syntax with `--help`) | +| `--user ` | string | User to add/remove | +| `--role ` | string | Role (for add) | + +### `teams tasks create` (verify with --help) +Flag set varies. Run `goclaw teams tasks create --help` for current syntax. + +## JSON output + +- ✅ `teams list/get`, `teams members list`, `teams tasks list/get`, `teams workspace list/get` — JSON +- ⚠️ all `create/update/delete/add/remove/reassign/approve/reject/put` — WS call returns success-ish payload; parse `unmarshalMap` but most fields empty + +## Destructive ops + +| Command | Confirm | +| --- | --- | +| `teams delete` | YES — cascades members + tasks + workspace | +| `teams members remove` | YES | +| `teams tasks delete` | YES (`teams_tasks_delete.go`) | +| `teams tasks reject` | YES | +| `teams workspace delete` | YES | + +## Common patterns + +### Example 1: list teams + get one +```bash +goclaw teams list --output json +goclaw teams get --output json +``` + +### Example 2: create team with 2 agents +```bash +goclaw teams create --name "Support Squad" --agents "agent-a,agent-b" --output json +``` + +### Example 3: add member + create task +```bash +# Run --help first — team-id may be positional: +goclaw teams members add --help +goclaw teams tasks create --help +``` + +### Example 4: approve task +```bash +goclaw teams tasks approve --output json +``` + +### Example 5: workspace file upload (verify syntax first) +```bash +goclaw teams workspace --help +goclaw teams workspace list --output json +``` + +## Edge cases & gotchas + +- **All WS — no HTTP.** If WS connect fails, nothing works. Advise user to check `goclaw status` first. +- **`teams events`** = WS subscribe streaming live team activity. Skill REFUSES (same as `logs tail`). +- **Workspace path** slash-separated, no leading `/`. Same convention as `memory`. +- **Task state machine:** pending → assigned → in_progress → (approve|reject) → completed. `reassign` works in pending/assigned only. +- **`teams.tasks` vs `teams tasks`:** CLI uses space (subcommand). WS method is `teams.tasks.`. +- **Cascade delete warning:** `teams delete` removes members + tasks + workspace. Triple-confirm if team has active tasks. + +## Cross-refs + +- Delegation between agents (different from teams): [agents-advanced.md](agents-advanced.md) +- Chat sessions per user: [chat-sessions.md](chat-sessions.md) +- Individual agent files: [agents-core.md](agents-core.md)