@mrsekut/ccron 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrsekut
+
+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,75 @@
+# ccron
+
+Schedule `claude -p` execution on macOS with launchd.
+
+Register scheduled `claude -p` tasks with a single command. Handles all the tricky launchd setup automatically.
+
+## Usage
+
+Run directly with `bunx`:
+
+```bash
+bunx @mrsekut/ccron <command> [options]
+```
+
+## Claude Code Skill
+
+Install the ccron skill so Claude Code can register tasks from natural language:
+
+```bash
+bunx skills add mrsekut/ccron
+```
+
+Then tell Claude: "Schedule a daily summary to Slack at 5pm on weekdays" and it will handle the rest.
+
+## Quick Start
+
+```bash
+# Register a task
+ccron add \
+  --name daily-summary \
+  --schedule "15 17 * * 1-5" \
+  --prompt-file ./prompts/daily-summary.txt \
+  --mcp slack
+
+# Verify setup
+ccron test daily-summary
+
+# List all tasks
+ccron list
+```
+
+## Commands
+
+| Command               | Description                        |
+| --------------------- | ---------------------------------- |
+| `ccron add`           | Register a new scheduled task      |
+| `ccron list`          | List tasks with launchd status     |
+| `ccron show <name>`   | Show detailed task info            |
+| `ccron run <name>`    | Manually trigger and tail log      |
+| `ccron test <name>`   | Run environment checks             |
+| `ccron log <name>`    | Show logs (`--follow` for tail)    |
+| `ccron edit <name>`   | Edit config, regenerate and reload |
+| `ccron auth <name>`   | Re-authenticate MCP servers        |
+| `ccron remove <name>` | Remove task (`--purge` for logs)   |
+
+## Schedule Format
+
+Standard cron expression: `"minute hour * * day-of-week"`
+
+```
+15 17 * * *     Every day at 17:15
+15 17 * * 1-5   Weekdays at 17:15
+0 22 * * 5      Every Friday at 22:00
+0 9 * * 1,3,5   Mon/Wed/Fri at 9:00
+```
+
+Step values (`*/5`) and minute/hour ranges are not supported (launchd limitation).
+
+## MCP Presets
+
+`slack`, `linear` are available as built-in presets.
+
+```bash
+ccron add --name my-task --schedule "0 9 * * *" --prompt "hello" --mcp slack,linear
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mrsekut/ccron",
+  "version": "0.1.0",
+  "description": "Schedule claude -p execution on macOS with launchd",
+  "type": "module",
+  "license": "MIT",
+  "author": "mrsekut",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrsekut/ccron.git"
+  },
+  "keywords": [
+    "claude",
+    "launchd",
+    "cron",
+    "schedule",
+    "macos",
+    "claude-code"
+  ],
+  "bin": {
+    "ccron": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "skills"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/ccron/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ccron
+description: >
+  Schedule claude -p execution on macOS with launchd. Use when the user wants to
+  set up recurring claude tasks, manage scheduled prompts, or automate claude CLI runs.
+allowed-tools: 'Read,Write,Bash(ccron:*)'
+version: '0.1.0'
+author: 'mrsekut'
+---
+
+# ccron - Schedule claude -p on macOS with launchd
+
+Schedule `claude -p` on macOS via launchd. Handles all the tricky launchd setup automatically.
+
+## Workflow
+
+When a user asks to run something on a schedule:
+
+1. Create a prompt file (`./prompts/<name>.txt` or similar, git-manageable location)
+2. Register with `ccron add`
+3. Verify with `ccron test <name>`
+
+**Always run `ccron <command> --help` to check the latest options.**
+
+## Commands
+
+| Command               | Purpose                              |
+| --------------------- | ------------------------------------ |
+| `ccron add`           | Register a scheduled task            |
+| `ccron list`          | List tasks with launchd status       |
+| `ccron show <name>`   | Show detailed task info              |
+| `ccron run <name>`    | Manually trigger and tail log        |
+| `ccron test <name>`   | Run environment checks               |
+| `ccron log <name>`    | Show logs (`--follow` for tail)      |
+| `ccron auth <name>`   | Re-authenticate MCP servers          |
+| `ccron edit <name>`   | Edit config, regenerate and reload   |
+| `ccron remove <name>` | Remove task (`--purge` for logs too) |
+
+## ccron add Options
+
+```
+--name <name>           Task name (lowercase, numbers, hyphens)
+--schedule "<cron>"     Cron expression: "minute hour * * day-of-week"
+--prompt "<text>"       Prompt string (mutually exclusive with --prompt-file)
+--prompt-file <path>    Prompt file path (mutually exclusive with --prompt)
+--mcp <names>           MCP presets, comma-separated (slack, linear)
+--allowed-tools <tools> Allowed tools (Bash,Read,Write,Edit,Glob,Grep)
+--max-turns <n>         Maximum turns
+```
+
+## Schedule (cron)
+
+Format: `"minute hour * * day-of-week"` (5 fields)
+
+| Goal                  | Cron              |
+| --------------------- | ----------------- |
+| Daily at 17:15        | `"15 17 * * *"`   |
+| Weekdays at 17:15     | `"15 17 * * 1-5"` |
+| Every Friday at 22:00 | `"0 22 * * 5"`    |
+| Mon/Wed/Fri at 9:00   | `"0 9 * * 1,3,5"` |
+
+**Constraint**: Step values (`*/5`) and minute/hour ranges are not supported (launchd limitation).
+
+## Example
+
+User: "Post a daily summary to Slack at 5pm on weekdays"
+
+```bash
+# 1. Create prompt file
+cat > ./prompts/daily-summary.txt << 'EOF'
+Create a daily summary and post it to #daily-summary channel.
+Include: completed tasks, tomorrow's plan, blockers.
+EOF
+
+# 2. Register
+ccron add \
+  --name daily-summary \
+  --schedule "0 17 * * 1-5" \
+  --prompt-file ./prompts/daily-summary.txt \
+  --mcp slack
+
+# 3. Verify
+ccron test daily-summary
+```
+
+## Troubleshooting
+
+- `ccron test` fails: follow the suggested fix commands in the output
+- MCP auth expired: `ccron auth <name>`
+- Prompt change: just edit the file if using `--prompt-file` (no re-registration needed)
+- Schedule change: `ccron edit <name> --schedule "<cron>"`

package/src/cli.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`ccron - Schedule claude -p execution on macOS with launchd
+
+Schedule claude -p execution on macOS via launchd.
+Handles all the tricky launchd setup automatically.
+
+Usage: ccron <command> [options]
+
+Commands:
+  add       Register a new scheduled task
+  list      List all registered tasks with launchd status
+  show      Show detailed information about a task
+  run       Manually trigger a task and tail its log
+  test      Run environment checks (CLI, auth, ulimit, TCC, plist)
+  log       Show task execution logs
+  auth      Re-authenticate MCP servers for a task
+  edit      Edit a task's configuration (regenerates script/plist)
+  remove    Remove a task and all generated files
+
+Schedule format (cron expression):
+  "minute hour * * day-of-week"
+
+  15 17 * * *     Every day at 17:15
+  15 17 * * 1-5   Weekdays at 17:15
+  0 22 * * 5      Every Friday at 22:00
+  0 9 * * 1,3,5   Mon/Wed/Fri at 9:00
+
+  Note: Step values (*/5) and minute/hour ranges are not supported (launchd limitation).
+
+MCP presets: slack, linear
+
+File locations:
+  Task configs:  ~/.config/ccron/tasks/<name>.json
+  MCP configs:   ~/.config/ccron/mcp/<name>.json
+  Scripts:       ~/.local/bin/ccron-<name>.sh
+  Plists:        ~/Library/LaunchAgents/com.ccron.<name>.plist
+  Logs:          ~/.local/share/ccron/logs/<name>.log
+
+Examples:
+  ccron add --name daily-summary --schedule "15 17 * * 1-5" --prompt-file ./prompts/daily.txt
+  ccron add --name weekly-review --schedule "0 22 * * 5" --prompt "週次レビュー" --mcp slack
+  ccron list
+  ccron show daily-summary
+  ccron test daily-summary
+  ccron edit daily-summary --schedule "0 18 * * 1-5"
+  ccron run daily-summary
+  ccron log daily-summary --follow
+  ccron remove daily-summary
+
+Run "ccron <command> --help" for detailed help on each command.`);
+}
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+import { addCommand } from './commands/add';
+import { listCommand } from './commands/list';
+import { runCommand } from './commands/run';
+import { logCommand } from './commands/log';
+import { testCommand } from './commands/test';
+import { removeCommand } from './commands/remove';
+import { editCommand } from './commands/edit';
+import { authCommand } from './commands/auth';
+import { showCommand } from './commands/show';
+
+const commands: Record<string, (args: string[]) => Promise<void>> = {
+  add: addCommand,
+  list: listCommand,
+  show: showCommand,
+  run: runCommand,
+  log: logCommand,
+  test: testCommand,
+  remove: removeCommand,
+  edit: editCommand,
+  auth: authCommand,
+};
+
+const handler = commands[command];
+if (!handler) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "ccron --help" for usage.');
+  process.exit(1);
+}
+
+await handler(args.slice(1));

package/src/commands/add.ts

@@ -0,0 +1,251 @@
+import {
+  type TaskConfig,
+  type GlobalConfig,
+  validateTaskName,
+  readTaskConfig,
+  writeTaskConfig,
+  readGlobalConfig,
+  writeGlobalConfig,
+  ensureDirectories,
+  mcpConfigPath,
+  scriptPath,
+  plistPath,
+} from '../config';
+import { parseSchedule } from '../schedule';
+import { validateMcpPresets } from '../mcp';
+import {
+  generateScriptContent,
+  generatePlistContent,
+  generateMcpConfigContent,
+} from '../generator';
+import { bootstrap } from '../launchd';
+
+type AddOptions = {
+  name: string;
+  schedule: string;
+  prompt: string | null;
+  promptFile: string | null;
+  mcp: string[];
+  allowedTools: string[];
+  maxTurns: number | null;
+};
+
+export async function addCommand(args: string[]): Promise<void> {
+  const opts = parseAddArgs(args);
+  await validateOptions(opts);
+
+  await ensureDirectories();
+
+  // Detect claude CLI path if not configured
+  const globalConfig = await ensureGlobalConfig();
+
+  // Parse schedule to validate it early
+  const intervals = parseSchedule(opts.schedule);
+
+  const now = new Date().toISOString();
+  const task: TaskConfig = {
+    name: opts.name,
+    schedule: opts.schedule,
+    prompt: opts.prompt,
+    promptFile: opts.promptFile,
+    mcp: opts.mcp,
+    allowedTools: opts.allowedTools,
+    maxTurns: opts.maxTurns,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  // Save task config
+  await writeTaskConfig(task);
+  console.log(`✓ Task config saved: ~/.config/ccron/tasks/${task.name}.json`);
+
+  // Generate MCP config if needed
+  if (task.mcp.length > 0) {
+    const mcpContent = generateMcpConfigContent(task.mcp);
+    await Bun.write(mcpConfigPath(task.name), mcpContent);
+    console.log(`✓ MCP config saved: ~/.config/ccron/mcp/${task.name}.json`);
+  }
+
+  // Generate script
+  const scriptContent = generateScriptContent(task, globalConfig);
+  const scriptFile = scriptPath(task.name);
+  await Bun.write(scriptFile, scriptContent);
+  const { chmod } = await import('fs/promises');
+  await chmod(scriptFile, 0o755);
+  console.log(`✓ Script generated: ~/.local/bin/ccron-${task.name}.sh`);
+
+  // Generate plist
+  const plistContent = generatePlistContent(task, globalConfig, intervals);
+  const plistFile = plistPath(task.name);
+  await Bun.write(plistFile, plistContent);
+  console.log(
+    `✓ Plist generated: ~/Library/LaunchAgents/com.ccron.${task.name}.plist`,
+  );
+
+  // Register with launchd
+  await bootstrap(plistFile);
+  console.log(`✓ Registered with launchd`);
+
+  console.log(
+    `\n${task.name} scheduled (${task.schedule}). Run "ccron test ${task.name}" to verify setup.`,
+  );
+}
+
+function parseAddArgs(args: string[]): AddOptions {
+  const { parseArgs } = require('util');
+  const { values } = parseArgs({
+    args,
+    options: {
+      name: { type: 'string' },
+      schedule: { type: 'string' },
+      prompt: { type: 'string' },
+      'prompt-file': { type: 'string' },
+      mcp: { type: 'string' },
+      'allowed-tools': { type: 'string' },
+      'max-turns': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: true,
+  });
+
+  if (values.help) {
+    printAddHelp();
+    process.exit(0);
+  }
+
+  return {
+    name: values.name ?? '',
+    schedule: values.schedule ?? '',
+    prompt: values.prompt ?? null,
+    promptFile: values['prompt-file'] ?? null,
+    mcp: values.mcp ? values.mcp.split(',').filter(Boolean) : [],
+    allowedTools: values['allowed-tools']
+      ? values['allowed-tools'].split(',').filter(Boolean)
+      : [],
+    maxTurns: values['max-turns'] ? Number(values['max-turns']) : null,
+  };
+}
+
+async function validateOptions(opts: AddOptions): Promise<void> {
+  const errors: string[] = [];
+
+  // Name
+  if (!opts.name) {
+    errors.push('--name is required');
+  } else {
+    const nameError = validateTaskName(opts.name);
+    if (nameError) errors.push(nameError);
+    else {
+      const existing = await readTaskConfig(opts.name);
+      if (existing) {
+        errors.push(
+          `Task "${opts.name}" already exists. Use "ccron edit ${opts.name}" to modify.`,
+        );
+      }
+    }
+  }
+
+  // Schedule
+  if (!opts.schedule) {
+    errors.push('--schedule is required');
+  }
+
+  // Prompt
+  if (!opts.prompt && !opts.promptFile) {
+    errors.push('Either --prompt or --prompt-file is required');
+  }
+  if (opts.prompt && opts.promptFile) {
+    errors.push('Cannot specify both --prompt and --prompt-file');
+  }
+  if (opts.promptFile) {
+    const file = Bun.file(opts.promptFile);
+    if (!(await file.exists())) {
+      errors.push(`Prompt file not found: ${opts.promptFile}`);
+    }
+  }
+
+  // MCP
+  if (opts.mcp.length > 0) {
+    const mcpError = validateMcpPresets(opts.mcp);
+    if (mcpError) errors.push(mcpError);
+  }
+
+  // Max turns
+  if (
+    opts.maxTurns !== null &&
+    (!Number.isInteger(opts.maxTurns) || opts.maxTurns < 1)
+  ) {
+    errors.push('--max-turns must be a positive integer');
+  }
+
+  if (errors.length > 0) {
+    for (const e of errors) console.error(`Error: ${e}`);
+    process.exit(1);
+  }
+}
+
+async function ensureGlobalConfig(): Promise<GlobalConfig> {
+  const config = await readGlobalConfig();
+
+  if (!config.claudePath) {
+    const detected = await detectClaudePath();
+    if (detected) {
+      config.claudePath = detected;
+      await writeGlobalConfig(config);
+      console.log(`✓ claude CLI detected: ${detected}`);
+    } else {
+      console.error(
+        'Warning: Could not detect claude CLI path. Set it manually with ccron config --claude-path',
+      );
+    }
+  }
+
+  return config;
+}
+
+async function detectClaudePath(): Promise<string | null> {
+  try {
+    const result = await Bun.$`which claude`.quiet();
+    if (result.exitCode === 0) {
+      const fullPath = result.stdout.toString().trim();
+      // Return the directory containing claude
+      const { dirname } = await import('path');
+      return dirname(fullPath);
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function printAddHelp() {
+  console.log(`ccron add - Register a new scheduled task
+
+Usage: ccron add [options]
+
+Required:
+  --name <name>           Task name (lowercase letters, numbers, hyphens)
+  --schedule <cron>       Cron expression: "minute hour * * day-of-week"
+  --prompt <text>         Prompt string (mutually exclusive with --prompt-file)
+  --prompt-file <path>    Path to prompt file (mutually exclusive with --prompt)
+
+Optional:
+  --mcp <names>           MCP server presets, comma-separated (slack, linear)
+  --allowed-tools <tools> Allowed tools, comma-separated (Bash,Read,Write,Edit,Glob,Grep)
+  --max-turns <n>         Maximum number of turns
+
+Schedule format (cron):
+  "minute hour * * day-of-week"
+
+  minute:       0-59
+  hour:         0-23
+  day-of-week:  0-6 (0=Sun), ranges (1-5), comma-separated (1,3,5)
+  day-of-month and month: must be "*" (launchd limitation)
+
+Examples:
+  ccron add --name daily-summary --schedule "15 17 * * 1-5" --prompt-file ./prompts/daily.txt
+  ccron add --name weekly-review --schedule "0 22 * * 5" --prompt "週次レビューを作成して" --mcp slack
+  ccron add --name hourly-check --schedule "0 9 * * *" --prompt "ステータスチェック" --allowed-tools "Bash,Read"
+
+Note: Step values (*/5) and ranges in minute/hour are not supported by launchd.`);
+}

package/src/commands/auth.ts

@@ -0,0 +1,67 @@
+import { readTaskConfig, mcpConfigPath } from '../config';
+import { spawn } from 'child_process';
+
+export async function authCommand(args: string[]): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`ccron auth - Re-authenticate MCP servers for a task
+
+Usage: ccron auth <name>
+
+Opens an interactive claude session with the task's MCP config, allowing
+you to complete OAuth flows for MCP servers (Slack, Linear, etc.).
+The session runs from /tmp to avoid git repo issues.
+
+Exit claude after authentication is complete.
+
+Example:
+  ccron auth daily-summary`);
+    return;
+  }
+
+  const name = args[0];
+  if (!name) {
+    console.error('Usage: ccron auth <name>');
+    process.exit(1);
+  }
+
+  const task = await readTaskConfig(name);
+  if (!task) {
+    console.error(`Task "${name}" not found.`);
+    process.exit(1);
+  }
+
+  if (task.mcp.length === 0) {
+    console.log(`Task "${name}" has no MCP servers configured.`);
+    return;
+  }
+
+  const mcpConfig = mcpConfigPath(name);
+  if (!(await Bun.file(mcpConfig).exists())) {
+    console.error(`MCP config not found: ${mcpConfig}`);
+    console.error(
+      `Re-register with: ccron add --name ${name} --mcp ${task.mcp.join(',')}`,
+    );
+    process.exit(1);
+  }
+
+  console.log(`Opening claude with MCP config for "${name}"...`);
+  console.log(`MCP servers: ${task.mcp.join(', ')}`);
+  console.log(`Complete the authentication flow, then exit claude.\n`);
+
+  const child = spawn('claude', ['--mcp-config', mcpConfig], {
+    cwd: '/tmp',
+    stdio: 'inherit',
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    child.on('close', code => {
+      if (code === 0) {
+        console.log(`\nAuthentication complete for "${name}".`);
+        resolve();
+      } else {
+        reject(new Error(`claude exited with code ${code}`));
+      }
+    });
+    child.on('error', reject);
+  });
+}