@cjvana/claude-auto 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+	"name": "claude-auto",
+	"version": "0.1.0",
+	"description": "Autonomous Claude Code cron jobs for continuous codebase improvement. Set up scheduled jobs where Claude autonomously works on your repos — you wake up to PRs.",
+	"author": {
+		"name": "claude-auto contributors"
+	},
+	"license": "MIT",
+	"keywords": ["autonomous", "cron", "scheduling", "coding-agent"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cjvana
+
+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,435 @@
+# claude-auto
+
+Autonomous Claude Code cron jobs for continuous codebase improvement. Set up a schedule, point it at a repo, and wake up to PRs.
+
+Claude researches your codebase, picks the highest-value work (open issues, bugs it discovers, or features it wants to add), creates a branch, does the work, updates docs, opens a PR, and notifies you. It learns from previous runs, iterates on reviewer feedback, and can run a multi-stage plan/implement/review pipeline for higher-quality output.
+
+## Install
+
+```bash
+npm install -g @cjvana/claude-auto
+```
+
+This registers `claude-auto` as a Claude Code plugin. The `/claude-auto:setup` slash command becomes available in Claude Code sessions.
+
+### Requirements
+
+- Node.js >= 22
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated
+- macOS, Linux, or Windows
+
+## Quick Start
+
+### Option A: Conversational Setup (Recommended)
+
+In a Claude Code session:
+
+```
+/claude-auto:setup
+```
+
+Claude walks you through everything — repo, branch, schedule, focus areas, system prompt, notifications, guardrails — and creates the job.
+
+### Option B: CLI
+
+```bash
+claude-auto create \
+  --name my-api \
+  --repo /path/to/my-api \
+  --branch main \
+  --schedule "0 */6 * * *" \
+  --system-prompt-file prompt.txt
+```
+
+## How It Works
+
+Each cron tick:
+
+1. **Budget check** — skip if daily/weekly/monthly cap exceeded
+2. **Load context** — prior runs from SQLite (avoids duplicate work)
+3. **Check PR feedback** — if reviewers left comments on a previous PR, address those first
+4. **Acquire lock** — prevents overlapping runs
+5. **Pull latest** from configured branch
+6. **Pick work** following priority chain:
+   - Open PRs with review comments (highest priority)
+   - Open GitHub issues / feature requests (triaged by complexity)
+   - Bugs Claude discovers in the code
+   - Features Claude thinks would be useful
+7. **Execute** — single Claude spawn or multi-stage pipeline (plan → implement → review)
+8. **Rebase check** — auto-resolve if target branch diverged
+9. **Open PR** with detailed description
+10. **Update documentation** affected by changes
+11. **Notify** via Discord, Slack, Telegram, or GitHub comments
+12. **Record** cost and context to SQLite for future runs
+
+## Model Selection
+
+Configure which Claude model to use per job:
+
+```yaml
+model: opus           # or: sonnet, haiku, default
+```
+
+Or with the pipeline, configure per stage:
+
+```yaml
+pipeline:
+  enabled: true
+  planModel: haiku        # Fast, cheap planning
+  implementModel: opus    # Best quality for code
+  reviewModel: sonnet     # Balanced review
+  maxReviewRounds: 2
+```
+
+Supported values: `sonnet`, `opus`, `haiku`, `default`, or full model IDs like `claude-opus-4-6`.
+
+## Agent Pipeline
+
+Enable multi-stage plan → implement → review for higher-quality PRs:
+
+```yaml
+pipeline:
+  enabled: true
+  planModel: haiku
+  implementModel: opus
+  reviewModel: sonnet
+  fixModel: opus
+  maxReviewRounds: 2
+  budgetSplit:
+    plan: 0.15
+    implement: 0.55
+    review: 0.15
+    fix: 0.15
+```
+
+Each stage spawns a separate Claude instance with a stage-specific system prompt:
+- **Plan** — reads codebase, understands the issue, creates implementation plan
+- **Implement** — executes the plan, writes code and tests
+- **Review** — checks implementation against the plan, can request changes
+- **Fix** — addresses review feedback (loops until review passes or max rounds)
+
+When the review stage finds issues, it rejects the PR and the fix stage runs. This loop continues until the review passes or `maxReviewRounds` is exceeded.
+
+Pipeline is disabled by default. Existing single-spawn configs work identically.
+
+## PR Feedback Loop
+
+Claude iterates on its own PRs based on reviewer feedback:
+
+1. Before picking new work, Claude checks for open PRs with unaddressed review comments
+2. When feedback exists, Claude checks out the existing PR branch and addresses it
+3. After fixing, pushes to the same branch and comments on the PR with what changed
+4. After `maxFeedbackRounds` (default 3), posts a "needs human review" comment and moves on
+
+Review comments are sanitized (XML framing, 2000-char truncation, bot comments filtered) to prevent prompt injection.
+
+## Issue Triage
+
+Claude evaluates issues before picking work:
+
+- **Complexity scoring** — body length, reproduction steps, labels, assignees
+- **Label priority** — "good first issue" (+30), "bug" (+20), "enhancement" (+10)
+- **Skip logic** — filters out spam (too short), vague issues, already-assigned, already-attempted
+- Top candidates are presented to Claude ranked by score
+
+## Cost Tracking
+
+Track spending and enforce budgets:
+
+```bash
+# View costs per job
+claude-auto cost
+claude-auto cost my-api --json
+
+# Set budget caps in config
+```
+
+```yaml
+budget:
+  dailyUsd: 10.00
+  weeklyUsd: 50.00
+  monthlyUsd: 150.00
+```
+
+When a budget cap is reached, scheduled runs skip with a `budget-exceeded` status and send a notification. Per-run limits still apply via `guardrails.maxBudgetUsd`.
+
+## Job Management
+
+```bash
+# List all jobs
+claude-auto list
+claude-auto list --json
+
+# View run history
+claude-auto logs my-api
+claude-auto logs my-api --limit 5
+
+# Aggregate report
+claude-auto report
+claude-auto report my-api
+
+# Cost tracking
+claude-auto cost
+claude-auto cost my-api
+
+# Pause / resume
+claude-auto pause my-api
+claude-auto resume my-api
+
+# Edit configuration
+claude-auto edit my-api --schedule "0 9 * * 1-5"
+claude-auto edit my-api --max-turns 100
+claude-auto edit my-api --model opus
+
+# Remove a job
+claude-auto remove my-api
+claude-auto remove my-api --keep-logs
+
+# Interactive dashboard
+claude-auto dashboard
+```
+
+Or use Claude Code skills:
+
+```
+/claude-auto:list
+/claude-auto:pause my-api
+/claude-auto:edit my-api
+/claude-auto:status my-api
+/claude-auto:logs my-api
+```
+
+## TUI Dashboard
+
+Launch an interactive terminal dashboard:
+
+```bash
+claude-auto dashboard
+```
+
+Features:
+- Live job status with auto-refresh (3-second polling)
+- Per-job cost summaries
+- Last run / next run times
+- Keyboard navigation: arrow keys, Enter for detail, Escape to go back
+- Quick actions: `p` pause/resume, `l` view logs, `q` quit
+
+Built with [ink](https://github.com/vadimdemedes/ink) + React. Dependencies are lazily loaded — no startup cost for non-dashboard commands.
+
+## Configuration
+
+Jobs are stored as human-readable YAML at `~/.claude-auto/jobs/<job-id>/config.yaml`. Edit them directly or use the CLI.
+
+```yaml
+# Job: my-api
+name: my-api
+repo: /Users/dev/my-api
+branch: main
+schedule: "0 */6 * * *"
+timezone: America/Chicago
+enabled: true
+
+# Model selection
+model: opus
+
+# What Claude focuses on
+focus:
+  - Fix open issues
+  - Improve test coverage
+  - Update outdated dependencies
+
+# Custom personality
+systemPrompt: |
+  You are a careful, senior engineer. Prefer small, focused changes.
+  Always add or update tests. Write detailed PR descriptions.
+  Never introduce new dependencies without strong justification.
+
+# Safety limits
+guardrails:
+  maxTurns: 50
+  maxBudgetUsd: 5.00
+  noNewDeps: false
+  noArchChanges: false
+  bugFixOnly: false
+  restrictToPaths: []
+
+# Budget caps (cumulative)
+budget:
+  dailyUsd: 10.00
+  weeklyUsd: 50.00
+  monthlyUsd: 150.00
+
+# PR feedback
+maxFeedbackRounds: 3
+
+# Multi-stage pipeline (optional)
+pipeline:
+  enabled: false
+  planModel: haiku
+  implementModel: opus
+  reviewModel: sonnet
+  fixModel: opus
+  maxReviewRounds: 2
+
+# Notifications
+discord:
+  webhookUrl: https://discord.com/api/webhooks/...
+  onSuccess: true
+  onFailure: true
+  onNoChanges: false
+  onLocked: false
+
+slack:
+  webhookUrl: https://hooks.slack.com/services/...
+  onSuccess: true
+  onFailure: true
+
+telegram:
+  botToken: "123456:ABC..."
+  chatId: "-100..."
+  onSuccess: true
+  onFailure: true
+```
+
+## Schedule Format
+
+Natural language (Claude converts during setup):
+
+```
+every 6 hours
+twice a day
+weekdays at 9am
+every monday at 2pm
+```
+
+Or standard cron:
+
+```
+0 */6 * * *       # every 6 hours
+0 9,17 * * *      # 9am and 5pm
+0 9 * * 1-5       # weekdays at 9am
+0 14 * * 1        # mondays at 2pm
+```
+
+## Guardrails
+
+Full trust by default. Optionally restrict what Claude can do:
+
+| Flag | Config key | Effect |
+|------|-----------|--------|
+| `--max-turns N` | `guardrails.maxTurns` | Terminate after N Claude turns |
+| `--max-budget N` | `guardrails.maxBudgetUsd` | Cap spend per run at $N |
+| `--no-new-deps` | `guardrails.noNewDeps` | Prevent adding new dependencies |
+| `--no-arch-changes` | `guardrails.noArchChanges` | Prevent architectural changes |
+| `--bug-fix-only` | `guardrails.bugFixOnly` | Only fix bugs, no new features |
+| `--restrict-paths` | `guardrails.restrictToPaths` | Only touch files in these directories |
+
+## Notifications
+
+Configure per job. Each provider supports event triggers:
+
+| Event | Default | When |
+|-------|---------|------|
+| `onSuccess` | true | PR created successfully |
+| `onFailure` | true | Run errored, merge conflict, or budget exceeded |
+| `onNoChanges` | false | Claude found nothing to do |
+| `onLocked` | false | Another run was already active |
+
+GitHub issue comments are automatic — when Claude works on an issue, it comments with status and PR link.
+
+## Git Safety
+
+These invariants are structurally enforced (not just policy):
+
+- **Never commits to main** or the configured branch
+- **Never force pushes** — no `--force` flag exists in the codebase
+- **Always creates a new branch** per run (`claude-auto/<job-id>/<timestamp>`)
+- **Always opens a PR** — human review before merge
+- **File-based locking** prevents concurrent runs on the same job
+- **Auto-rebase** before push when target branch has diverged
+- **Clean abort** on merge conflicts — never produces broken code
+
+## Cross-Run Context
+
+Claude remembers what it did in previous runs:
+
+- Stores structured facts (PR URLs, issue numbers, files modified, summaries) in SQLite
+- Loads a rolling window of recent runs into the system prompt
+- Avoids re-opening issues it already submitted PRs for
+- Tracks PR feedback rounds to know when to stop iterating
+
+Data is stored at `~/.claude-auto/claude-auto.db` (SQLite with WAL mode).
+
+## Platform Support
+
+| Platform | Scheduler | Status |
+|----------|-----------|--------|
+| macOS | launchd (plist) | Full support |
+| Linux | crontab | Full support |
+| Windows | Task Scheduler (schtasks.exe) | Full support |
+
+Common cron expressions are automatically translated to each platform's native format. Unsupported complex patterns throw a clear error with a suggestion to simplify.
+
+## Architecture
+
+```
+claude-auto (npm package)
+├── bin/
+│   ├── claude-auto.ts              # CLI entry point
+│   └── claude-auto-run.ts          # Cron entry point
+├── src/
+│   ├── core/                       # Config, job manager, schedule, types, database
+│   ├── platform/                   # Crontab, launchd, schtasks adapters
+│   ├── runner/                     # Orchestrator, pipeline, spawner, git ops,
+│   │                               # PR feedback, issue triage, cost tracker,
+│   │                               # context store, prompt builder, logger
+│   ├── notifications/              # Discord/Slack/Telegram formatters + dispatcher
+│   ├── cli/                        # Command router + 11 subcommands
+│   └── tui/                        # ink/React dashboard (lazily loaded)
+├── skills/                         # 8 Claude Code SKILL.md files
+├── .claude-plugin/                 # Plugin manifest
+└── scripts/                        # postinstall/preuninstall
+```
+
+## Multiple Jobs
+
+Run different jobs for different concerns:
+
+```bash
+# Security-focused, weekly, using Opus
+claude-auto create --name security-audit --repo ~/my-app \
+  --schedule "0 3 * * 0" --model opus \
+  --system-prompt-file security-prompt.txt
+
+# Bug fixes, daily, budget-capped
+claude-auto create --name bug-fixer --repo ~/my-app \
+  --schedule "0 2 * * *" --bug-fix-only \
+  --max-budget 3.00
+
+# Pipeline mode for complex work
+claude-auto create --name feature-builder --repo ~/my-app \
+  --schedule "0 10 * * 1-5" --model opus
+# Then enable pipeline in config:
+# claude-auto edit feature-builder (set pipeline.enabled: true)
+```
+
+## Development
+
+```bash
+git clone https://github.com/cj-vana/claude-auto.git
+cd claude-auto
+npm install
+npm run build
+npm test
+```
+
+```bash
+npm run typecheck    # TypeScript type checking
+npm run lint         # Biome linting
+npm run test:watch   # Watch mode
+```
+
+## License
+
+MIT

package/dist/check-repo-6C4QI2M2.js

@@ -0,0 +1,33 @@
+import {
+  execCommand
+} from "./chunk-3NEANSUS.js";
+
+// src/cli/commands/check-repo.ts
+import { stat } from "fs/promises";
+async function checkRepoCommand(args) {
+  const repoPath = args.path;
+  if (!repoPath) {
+    console.error("Usage: claude-auto check-repo --path <path>");
+    throw new Error("Missing --path argument");
+  }
+  try {
+    const s = await stat(repoPath);
+    if (!s.isDirectory()) {
+      console.log(JSON.stringify({ exists: false, error: "Not a directory" }));
+      return;
+    }
+    await execCommand("git", ["-C", repoPath, "rev-parse", "--git-dir"]);
+    const { stdout } = await execCommand("git", ["-C", repoPath, "remote", "get-url", "origin"]);
+    console.log(JSON.stringify({ exists: true, isGitRepo: true, remote: stdout.trim() }));
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      console.log(JSON.stringify({ exists: false }));
+      return;
+    }
+    console.log(JSON.stringify({ exists: false }));
+  }
+}
+export {
+  checkRepoCommand
+};
+//# sourceMappingURL=check-repo-6C4QI2M2.js.map

package/dist/check-repo-6C4QI2M2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/commands/check-repo.ts"],"sourcesContent":["import { stat } from \"node:fs/promises\";\nimport { execCommand } from \"../../util/exec.js\";\nimport type { ParsedCommand } from \"../types.js\";\n\n/**\n * Check if a path is a valid git repository.\n * Outputs JSON for the setup wizard to consume.\n */\nexport async function checkRepoCommand(args: ParsedCommand[\"args\"]): Promise<void> {\n\tconst repoPath = args.path as string | undefined;\n\tif (!repoPath) {\n\t\tconsole.error(\"Usage: claude-auto check-repo --path <path>\");\n\t\tthrow new Error(\"Missing --path argument\");\n\t}\n\n\ttry {\n\t\tconst s = await stat(repoPath);\n\t\tif (!s.isDirectory()) {\n\t\t\tconsole.log(JSON.stringify({ exists: false, error: \"Not a directory\" }));\n\t\t\treturn;\n\t\t}\n\n\t\t// Check if it's a git repo\n\t\tawait execCommand(\"git\", [\"-C\", repoPath, \"rev-parse\", \"--git-dir\"]);\n\n\t\t// Get remote URL\n\t\tconst { stdout } = await execCommand(\"git\", [\"-C\", repoPath, \"remote\", \"get-url\", \"origin\"]);\n\t\tconsole.log(JSON.stringify({ exists: true, isGitRepo: true, remote: stdout.trim() }));\n\t} catch (err: unknown) {\n\t\tif (err instanceof Error && \"code\" in err && (err as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\tconsole.log(JSON.stringify({ exists: false }));\n\t\t\treturn;\n\t\t}\n\t\t// If stat succeeded but git commands failed, still report as not a git repo\n\t\tconsole.log(JSON.stringify({ exists: false }));\n\t}\n}\n"],"mappings":";;;;;AAAA,SAAS,YAAY;AAQrB,eAAsB,iBAAiB,MAA4C;AAClF,QAAM,WAAW,KAAK;AACtB,MAAI,CAAC,UAAU;AACd,YAAQ,MAAM,6CAA6C;AAC3D,UAAM,IAAI,MAAM,yBAAyB;AAAA,EAC1C;AAEA,MAAI;AACH,UAAM,IAAI,MAAM,KAAK,QAAQ;AAC7B,QAAI,CAAC,EAAE,YAAY,GAAG;AACrB,cAAQ,IAAI,KAAK,UAAU,EAAE,QAAQ,OAAO,OAAO,kBAAkB,CAAC,CAAC;AACvE;AAAA,IACD;AAGA,UAAM,YAAY,OAAO,CAAC,MAAM,UAAU,aAAa,WAAW,CAAC;AAGnE,UAAM,EAAE,OAAO,IAAI,MAAM,YAAY,OAAO,CAAC,MAAM,UAAU,UAAU,WAAW,QAAQ,CAAC;AAC3F,YAAQ,IAAI,KAAK,UAAU,EAAE,QAAQ,MAAM,WAAW,MAAM,QAAQ,OAAO,KAAK,EAAE,CAAC,CAAC;AAAA,EACrF,SAAS,KAAc;AACtB,QAAI,eAAe,SAAS,UAAU,OAAQ,IAA8B,SAAS,UAAU;AAC9F,cAAQ,IAAI,KAAK,UAAU,EAAE,QAAQ,MAAM,CAAC,CAAC;AAC7C;AAAA,IACD;AAEA,YAAQ,IAAI,KAAK,UAAU,EAAE,QAAQ,MAAM,CAAC,CAAC;AAAA,EAC9C;AACD;","names":[]}

package/dist/check-repo-SXWFIVO5.js

@@ -0,0 +1,8 @@
+import {
+  checkRepoCommand
+} from "./chunk-TGKCHHXT.js";
+import "./chunk-3NEANSUS.js";
+export {
+  checkRepoCommand
+};
+//# sourceMappingURL=check-repo-SXWFIVO5.js.map

package/dist/check-repo-SXWFIVO5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}