Claude Tasks

A TUI scheduler for running Claude tasks on a cron schedule. Built with Bubble Tea.

Fork of kylemclaren/claude-tasks with additional features for model selection, permission control, session observability, and structured logging.

Screenshots

Features

Cron Scheduling - Schedule Claude tasks using 6-field cron expressions (second granularity)
One-off Tasks - Run tasks immediately or schedule for a specific time
Model Selection - Choose per-task model: Opus, Sonnet, or Haiku
Permission Modes - Per-task permission control: Bypass, Default, Accept Edits, or Plan
Session Observability - Track session IDs, view resume commands, and observe running tasks live in Terminal
Run History - Tabular run history with stats (success rate, avg duration), session IDs, and output preview
Cron Descriptions - Human-readable schedule descriptions (e.g., "Every hour, at 0 minutes past the hour")
Structured Logging - JSON log files per task run with model, permission mode, and session metadata
Real-time TUI - Terminal interface with live updates, spinners, search/filter, and responsive columns
Discord & Slack Webhooks - Task results posted with rich formatting
Usage Tracking - Monitor Anthropic API usage with visual progress bars and auto-skip thresholds
Markdown Rendering - Task output rendered with Glamour
Self-Update - Upgrade to the latest version with claude-tasks upgrade
SQLite Storage - Persistent task and run history
Multi-Process Safety - Scheduler leadership lease ensures only one process executes tasks at a time
Health Diagnostics - claude-tasks doctor validates environment, credentials, database, and scheduler state
Preflight Failure Tracking - Usage/credential failures are persisted as run records with structured logs

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/ASRagab/claude-tasks/main/install.sh | bash

This downloads the latest binary for your platform to ~/.local/bin/.

Build from Source

# Clone the repo
git clone https://github.com/ASRagab/claude-tasks.git
cd claude-tasks

# Build
go build -o claude-tasks ./cmd/claude-tasks

# Run
./claude-tasks

Requirements

Go 1.24+
Claude CLI installed and authenticated
SQLite (bundled via go-sqlite3)

Usage

CLI Commands

claude-tasks                                   # Launch the interactive TUI
claude-tasks tui --scheduler=auto|on|off       # Launch TUI with explicit scheduler mode
claude-tasks daemon [--scheduler=true|false]   # Run scheduler in foreground (for services)
claude-tasks serve [--port 8080] [--scheduler=true|false]  # Run HTTP API server
claude-tasks doctor                            # Run environment diagnostics
claude-tasks version                           # Show version information
claude-tasks upgrade                           # Upgrade to the latest version
claude-tasks help                              # Show help message

Keybindings

Task List

Key	Action
`a`	Add new task
`e`	Edit selected task
`d`	Delete selected task (with confirmation)
`t`	Toggle task enabled/disabled
`r`	Run task immediately
`/`	Search/filter tasks
`Enter`	View run history
`s`	Settings (usage threshold)
`?`	Toggle help
`q`	Quit

Run History

Key	Action
`Enter`	View full run output
`o`	Observe running task (opens Terminal with `claude --resume`)
`r`	Refresh run list
`Esc`	Back to task list

Add/Edit Form

Key	Action
`Tab`	Next field
`Shift+Tab`	Previous field
`Left/Right`	Toggle options (Model, Permission Mode, Task Type)
`?`	Cron preset picker (in cron field)
`Ctrl+S`	Save
`Esc`	Cancel

Task Configuration

Each task supports:

Model - Default (CLI default), Opus, Sonnet, or Haiku
Permission Mode - Bypass Permissions (default for scheduled tasks), Default, Accept Edits, or Plan
Cron Expression - 6-field format: second minute hour day month weekday
Working Directory - Where Claude CLI runs
Webhooks - Discord and/or Slack notification URLs

Cron Format

Uses 6-field cron expressions: second minute hour day month weekday

The TUI shows human-readable descriptions as you type:

Cron Expression  Every hour, at 0 minutes past the hour
0 0 * * * *

Preset picker available with ?:

0 * * * * *      # Every minute
0 0 9 * * *      # Every day at 9:00 AM
0 30 8 * * 1-5   # Weekdays at 8:30 AM
0 0 */2 * * *    # Every 2 hours
0 0 9 * * 0      # Every Sunday at 9:00 AM

Session Observability

Every task execution generates a unique session ID. From the run history view:

Session column shows truncated session IDs for each run
Run detail shows the full session ID with a claude --resume command
o key on a running task opens a new Terminal window with claude --resume, inheriting the task's working directory and permission mode

Structured Logging

Each task run produces a JSON log file at ~/.claude-tasks/logs/<task_id>/:

{
  "run_id": 42,
  "task_id": 1,
  "task_name": "Daily Review",
  "model": "sonnet",
  "permission_mode": "bypassPermissions",
  "session_id": "a1b2c3d4-e5f6-...",
  "status": "completed",
  "duration_ms": 45230,
  "output": "..."
}

Webhooks (Discord & Slack)

Add webhook URLs when creating a task to receive notifications:

Discord:

Rich embeds with colored sidebar (green/red/yellow)
Markdown formatting preserved
Task status, duration, working directory

Slack:

Block Kit formatting with rich layouts
Markdown converted to Slack's mrkdwn format
Timestamps and status fields

Usage Threshold

Press s to configure the usage threshold (default: 80%). When your Anthropic API usage exceeds this threshold, scheduled tasks will be skipped to preserve quota.

The header shows real-time usage:

◆ Claude Tasks  5h ████░░░░░░ 42% │ 7d ██████░░░░ 61% │ ⏱ 2h15m │ ⚡ 80%

Health Diagnostics

Run claude-tasks doctor to validate your environment:

claude-tasks doctor
[PASS] claude_binary: found at /usr/local/bin/claude
[PASS] usage_credentials: credentials available
[PASS] data_dir: writable
[PASS] logs_dir: writable
[PASS] database: open and writable
[PASS] scheduler_lease: holder=scheduler-12345 (active)
Doctor checks passed

Checks: Claude CLI binary, API credentials, data/logs directory permissions, database writability, scheduler lease state. Any FAIL exits non-zero.

Multi-Process Safety

Multiple instances (TUI + daemon, multiple serve processes) safely share the same database. A scheduler leadership lease ensures only one process actively schedules tasks. Others operate as followers and will take over if the leader stops.

Control scheduler behavior per mode:

TUI: --scheduler=auto (default, skip if daemon running), on, off
Daemon/Serve: --scheduler=true (default), false

Configuration

Data is stored in ~/.claude-tasks/:

tasks.db - SQLite database with tasks, runs, and settings
logs/ - Structured JSON log files per task run

Environment variables:

CLAUDE_TASKS_DATA - Override default data directory
CLAUDE_TASKS_AUTH_TOKEN - Enable Bearer auth on API routes (except /api/v1/health)
CLAUDE_TASKS_CORS_ORIGIN - Enforce a single allowed CORS origin (403 on mismatch)
CLAUDE_TASKS_API_RUN_CONCURRENCY - Max concurrent POST /run executions (0 disables run endpoint)
CLAUDE_TASKS_DISABLE_USAGE_CHECK - Disable usage threshold enforcement (useful for non-Anthropic auth setups like Vertex)

Example:

CLAUDE_TASKS_DATA=/custom/path \
CLAUDE_TASKS_AUTH_TOKEN=supersecret \
CLAUDE_TASKS_CORS_ORIGIN=https://app.example.com \
CLAUDE_TASKS_API_RUN_CONCURRENCY=8 \
CLAUDE_TASKS_DISABLE_USAGE_CHECK=1 \
./claude-tasks serve

REST API

The serve command starts an HTTP server. Task and run endpoints include model, permission_mode, and session_id fields.

When CLAUDE_TASKS_AUTH_TOKEN is set, include Authorization: Bearer <token> on all API requests except health.

GET    /api/v1/health                   Health check
GET    /api/v1/tasks                    List all tasks
POST   /api/v1/tasks                    Create task (supports model, permission_mode)
GET    /api/v1/tasks/{id}               Get task by ID
PUT    /api/v1/tasks/{id}               Update task
DELETE /api/v1/tasks/{id}               Delete task
POST   /api/v1/tasks/{id}/toggle        Toggle enabled
POST   /api/v1/tasks/{id}/run           Run immediately
GET    /api/v1/tasks/{id}/runs          Get task run history (includes session_id)
GET    /api/v1/tasks/{id}/runs/{runID}  Get a specific run by ID
GET    /api/v1/tasks/{id}/runs/latest   Get latest run
GET    /api/v1/settings                 Get settings
PUT    /api/v1/settings                 Update settings
GET    /api/v1/usage                    Get API usage stats

Example Tasks

Development Workflow

Task	Schedule	Model	Prompt
Daily Code Review	6pm daily	sonnet	Review any uncommitted changes in this repo. Summarize what was worked on and flag any potential issues.
Morning Standup Prep	8:30am weekdays	haiku	Analyze git log from the last 24 hours and prepare a brief standup summary of what was accomplished.
Dependency Audit	9am Mondays	sonnet	Check go.mod for outdated dependencies and security vulnerabilities. Suggest updates if needed.
Security Scan	9am Sundays	opus	Audit code for common security issues: SQL injection, XSS, hardcoded secrets, unsafe operations.
Weekly Summary	5pm Fridays	sonnet	Generate a weekly development summary from git history. Include stats, highlights, and next steps.

Data & Analysis

Task	Schedule	Model	Prompt
HN Sentiment Analysis	9am daily	sonnet	Pull the top 10 HackerNews stories and run sentiment analysis on all the comments using python and then list the posts with their analysis
GitHub Trending	9am Mondays	haiku	Pull trending GitHub repos from the last week and summarize what each one does, categorizing by language/domain
Gold/Silver Prices	9am daily	haiku	Fetch silver/gold prices and correlate with recent news sentiment

Tech Stack

Bubble Tea - TUI framework
Bubbles - TUI components (table, spinner, viewport, progress)
Lip Gloss - Styling
Glamour - Markdown rendering
robfig/cron - Cron scheduler
lnquy/cron - Cron expression to English descriptions
go-sqlite3 - SQLite driver
go-chi/chi - HTTP router for REST API

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
assets		assets
cmd/claude-tasks		cmd/claude-tasks
internal		internal
mobile		mobile
plans		plans
scripts/tui		scripts/tui
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Claude Tasks

Screenshots

Features

Installation

Quick Install (Recommended)

Build from Source

Requirements

Usage

CLI Commands

Keybindings

Task List

Run History

Add/Edit Form

Task Configuration

Cron Format

Session Observability

Structured Logging

Webhooks (Discord & Slack)

Usage Threshold

Health Diagnostics

Multi-Process Safety

Configuration

REST API

Example Tasks

Development Workflow

Data & Analysis

Tech Stack

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Claude Tasks

Screenshots

Features

Installation

Quick Install (Recommended)

Build from Source

Requirements

Usage

CLI Commands

Keybindings

Task List

Run History

Add/Edit Form

Task Configuration

Cron Format

Session Observability

Structured Logging

Webhooks (Discord & Slack)

Usage Threshold

Health Diagnostics

Multi-Process Safety

Configuration

REST API

Example Tasks

Development Workflow

Data & Analysis

Tech Stack

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 0

Languages

Packages

Contributors