claude-triggers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minzique
+
+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.

package/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# claude-triggers
+
+**Manage Claude Code scheduled agents from any harness.**
+
+[![npm](https://img.shields.io/npm/v/claude-triggers?color=blue)](https://www.npmjs.com/package/claude-triggers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![GitHub](https://img.shields.io/github/stars/minzique/claude-triggers?style=social)](https://github.com/minzique/claude-triggers)
+
+Create, run, and manage remote Claude agents on cron schedules — from [pi](https://github.com/mariozechner/pi-coding-agent), [opencode](https://github.com/opencode-ai/opencode), your own tools, or the command line.
+
+[Install](#install) · [Quick Start](#quick-start) · [CLI](#cli) · [Library](#library) · [Docs](./docs/ARCHITECTURE.md)
+
+</div>
+
+---
+
+> **⚠️ This package uses [reverse-engineered, undocumented Anthropic APIs](#disclaimer).** It may break at any time and may violate Anthropic's Terms of Service. Use at your own risk.
+
+## What It Does
+
+Each trigger fires on a UTC cron schedule, spawning an **isolated cloud session** with its own git clone, tools, and optional MCP connections. The agent runs in Anthropic's infrastructure — it cannot access your local machine.
+
+```
+Your Tool ──▶ claude-triggers ──▶ Anthropic API ──▶ Sandboxed Cloud Agent
+(pi, opencode,                     /v1/code/triggers     (git clone, Bash,
+ CLI, scripts)                     /v1/sessions            Read, Write, Edit,
+                                                           GitHub MCP, ...)
+```
+
+Beyond what Claude Code's `/schedule` exposes, this package also lets you:
+- **Create sessions directly** (no cron needed)
+- **Read conversation history** from remote sessions
+- **Send follow-up messages** to idle sessions
+- **Upload seed bundles** for session initialization
+- **Check GitHub integration** status programmatically
+
+## Install
+
+```bash
+npm install -g claude-triggers
+```
+
+**Prerequisites:** Claude Code installed & logged in (`claude` run once), Claude Max/Pro subscription, Node 20+.
+
+## Quick Start
+
+```bash
+# Verify everything works
+claude-triggers test
+
+# Create a scheduled agent
+claude-triggers create \
+  --name "daily-review" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Review open PRs and post summary comments" \
+  --repo "https://github.com/org/repo"
+
+# Run it now (don't wait for cron)
+claude-triggers run <trigger_id>
+
+# See what it did
+claude-triggers sessions
+```
+
+## CLI
+
+```bash
+# ── Triggers ──
+claude-triggers list [-v]                    # List (verbose: prompts, models)
+claude-triggers create --name --cron --prompt [--repo] [--model] [--tools]
+claude-triggers get <id>
+claude-triggers update <id> [--name] [--cron] [--prompt] [--model] [--enabled]
+claude-triggers enable <id>
+claude-triggers disable <id>
+claude-triggers run <id>                     # Run immediately
+claude-triggers delete <id>                  # Opens browser (no API delete)
+
+# ── Sessions ──
+claude-triggers sessions                     # List remote sessions
+claude-triggers session <id>                 # Session details
+claude-triggers session-create --env <id> --prompt "..." [--repo] [--title]
+
+# ── Infrastructure ──
+claude-triggers envs                         # List environments
+claude-triggers env-create [name]            # Create environment
+claude-triggers profile                      # Account & org info
+claude-triggers github-check owner/repo      # GitHub App + token sync
+claude-triggers test                         # Full connectivity test
+
+# All commands support --json for scripting
+claude-triggers list --json | jq '.data[].name'
+```
+
+## Library
+
+```typescript
+import { ClaudeTriggersClient, buildTriggerBody } from "claude-triggers";
+
+const client = await ClaudeTriggersClient.create();
+
+// Schedule an agent
+const env = await client.ensureEnvironment();
+const trigger = await client.createTrigger(
+  buildTriggerBody({
+    name: "nightly-tests",
+    cron: "0 3 * * *",
+    prompt: "Run the test suite and report failures",
+    environmentId: env.environment_id,
+    repoUrl: "https://github.com/org/repo",
+  })
+);
+
+// Run immediately
+await client.runTrigger(trigger.id);
+
+// Or create a one-off session (no cron)
+const session = await client.createSession({
+  environmentId: env.environment_id,
+  prompt: "Refactor the auth module and open a PR",
+  repoUrl: "https://github.com/org/repo",
+});
+
+// Read the conversation
+const events = await client.getSessionEvents(session.id);
+
+// Send a follow-up
+await client.sendSessionEvent(session.id, "Also update the tests");
+```
+
+See the full [API reference →](./docs/API.md)
+
+## Cron
+
+Standard 5-field UTC cron. **Minimum interval: 1 hour.**
+
+| Expression | Meaning |
+|:-----------|:--------|
+| `0 9 * * 1-5` | Weekdays at 9am UTC |
+| `0 */2 * * *` | Every 2 hours |
+| `0 0 * * *` | Daily at midnight UTC |
+| `30 14 * * 1` | Every Monday 2:30pm UTC |
+
+```typescript
+import { validateCron, describeCron } from "claude-triggers";
+
+validateCron("*/5 * * * *");  // "Minimum trigger interval is 1 hour..."
+describeCron("0 9 * * 1-5", { utc: true });  // "Weekdays at 9:00am UTC"
+```
+
+## Docs
+
+| Document | Contents |
+|:---------|:---------|
+| **[Architecture](./docs/ARCHITECTURE.md)** | How it works, API surface, session lifecycle, RE findings |
+| **[API Reference](./docs/API.md)** | Full library API with types and examples |
+| **[SKILL.md](./SKILL.md)** | Agent skill definition for pi and other harnesses |
+
+## Disclaimer
+
+**This software is provided as-is, without warranty of any kind.**
+
+This package interacts with **undocumented, internal Anthropic APIs** discovered through reverse engineering of Claude Code v2.1.81. These APIs use beta headers (`ccr-triggers-2026-01-30`, `ccr-byoc-2025-07-29`) that may be revoked without notice.
+
+Anthropic's [Terms of Service](https://www.anthropic.com/terms) state that Claude Pro/Max subscription tokens should only be used with official clients. Using these credentials with third-party tools **may violate those terms** and could result in **account suspension**.
+
+- **Use at your own risk.** The authors are not liable for any consequences — account suspension, charges, data loss, or service interruption.
+- This project is **not affiliated with, endorsed by, or sponsored by Anthropic.**
+- "Claude", "Claude Code", and "Anthropic" are trademarks of Anthropic, PBC.
+
+## License
+
+[MIT](./LICENSE)

package/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: claude-triggers
+description: Create, manage, and run Claude Code scheduled remote agents (triggers). Use when the user wants to schedule recurring AI tasks, set up cron-based automation, manage remote Claude sessions, or interact with the Anthropic trigger API. Works with any Claude Max/Pro account.
+---
+
+# Claude Triggers Skill
+
+Manage Claude Code's scheduled remote agents (triggers) from any agent harness. Each trigger runs on a cron schedule, spawning an isolated cloud session with its own git checkout, tools, and optional MCP connections.
+
+## Prerequisites
+
+- Claude Code installed and authenticated (`claude` run at least once)
+- Claude Max or Pro account (OAuth-based, not API key)
+- Node.js 20+
+
+## Setup
+
+```bash
+npm install -g claude-triggers
+```
+
+Or use directly via npx:
+```bash
+npx claude-triggers test
+```
+
+## Available Commands
+
+### Trigger Management
+
+```bash
+# List all triggers
+claude-triggers list
+claude-triggers list -v              # verbose: show prompts, models, repos
+
+# Create a trigger
+claude-triggers create \
+  --name "daily-pr-review" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Review all open PRs. Post a summary comment on each." \
+  --repo "https://github.com/org/repo" \
+  --model "claude-sonnet-4-6"
+
+# Get details
+claude-triggers get <trigger_id>
+
+# Update
+claude-triggers update <trigger_id> --name "new-name"
+claude-triggers update <trigger_id> --cron "0 */2 * * *"
+claude-triggers update <trigger_id> --prompt "New instructions"
+claude-triggers update <trigger_id> --enabled false
+
+# Enable/disable
+claude-triggers enable <trigger_id>
+claude-triggers disable <trigger_id>
+
+# Run immediately (without waiting for cron)
+claude-triggers run <trigger_id>
+
+# Delete (opens browser — API doesn't support delete)
+claude-triggers delete <trigger_id>
+```
+
+### Session Management
+
+```bash
+# List remote sessions
+claude-triggers sessions
+
+# Get session details
+claude-triggers session <session_id>
+
+# Create a session directly (without a trigger)
+claude-triggers session-create \
+  --env <environment_id> \
+  --prompt "Run the test suite" \
+  --repo "https://github.com/org/repo"
+```
+
+### Infrastructure
+
+```bash
+# List environments
+claude-triggers envs
+
+# Create an environment
+claude-triggers env-create "my-env"
+
+# Account info
+claude-triggers profile
+
+# Check GitHub integration
+claude-triggers github-check owner/repo
+
+# Test connectivity
+claude-triggers test
+```
+
+### Output Formats
+
+All commands support `--json` for raw JSON output, useful for scripting:
+```bash
+claude-triggers list --json | jq '.data[].name'
+```
+
+## Library Usage
+
+For integration into other tools, agents, or harnesses:
+
+```typescript
+import { ClaudeTriggersClient, buildTriggerBody } from "claude-triggers";
+
+// Auto-reads credentials from Claude Code
+const client = await ClaudeTriggersClient.create();
+
+// Create a trigger
+const env = await client.ensureEnvironment();
+const trigger = await client.createTrigger(
+  buildTriggerBody({
+    name: "nightly-tests",
+    cron: "0 3 * * *",
+    prompt: "Run the full test suite and report failures",
+    environmentId: env.environment_id,
+    repoUrl: "https://github.com/org/repo",
+  })
+);
+
+// Run it now
+await client.runTrigger(trigger.id);
+
+// Create a one-off session (no cron needed)
+const session = await client.createSession({
+  environmentId: env.environment_id,
+  prompt: "Refactor the auth module",
+  repoUrl: "https://github.com/org/repo",
+});
+```
+
+## Cron Expressions
+
+Standard 5-field UTC cron: `minute hour day-of-month month day-of-week`
+
+| Expression | Meaning |
+|------------|---------|
+| `0 9 * * 1-5` | Weekdays at 9am UTC |
+| `0 */2 * * *` | Every 2 hours |
+| `0 0 * * *` | Daily at midnight UTC |
+| `30 14 * * 1` | Every Monday at 2:30pm UTC |
+| `0 8 1 * *` | First of every month at 8am UTC |
+
+**Minimum interval is 1 hour.** Sub-hour expressions like `*/30 * * * *` are rejected.
+
+Cron expressions are always in **UTC**. Convert local times before creating triggers.
+
+## Important Notes
+
+- Triggers run **remotely** in Anthropic's cloud — they can't access local files or services
+- The agent prompt must be self-contained (the remote agent starts with zero context)
+- Cannot delete triggers via API — use https://claude.ai/code/scheduled
+- The trigger feature requires the `tengu_surreal_dali` feature flag (rolling out)
+- Sessions are created with `events: []`, then the prompt is sent via `sendSessionEvent()` — this is how Claude Code does it internally
+- When a GitHub repo is attached, the backend auto-provisions a scoped GitHub MCP server
+- Cron is always **UTC** — convert local times before creating triggers
+
+## Session Lifecycle
+
+1. **Create** → status `pending` (environment provisioning)
+2. **Running** → agent is executing (tool calls, thinking)
+3. **Idle** → agent finished, waiting for follow-up input
+4. Use `getSessionEvents()` to read the conversation history
+5. Use `sendSessionEvent()` to send follow-up prompts to idle sessions
+
+## Disclaimer
+
+This tool uses **reverse-engineered, undocumented Anthropic APIs** with beta headers that may change or break at any time. It uses your Claude Code OAuth credentials — Anthropic's ToS state that subscription tokens should only be used with official clients. **Use at your own risk.** The authors are not liable for account suspension, charges, or any other consequences. See the full [README disclaimer](https://github.com/minzique/claude-triggers#disclaimer) for details.

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * claude-triggers CLI — manage Claude Code scheduled agents.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;GAEG"}