Metadata-Version: 2.4
Name: claun-tui
Version: 0.3.1
Summary: Schedule Claude Code jobs with a beautiful TUI or headless mode
Project-URL: Homepage, https://github.com/nsmith/claun
Project-URL: Repository, https://github.com/nsmith/claun
Project-URL: Issues, https://github.com/nsmith/claun/issues
Author: nsmith
License: GPL-3.0
License-File: LICENSE
Keywords: automation,claude,cli,scheduler,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: croniter>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.89.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: textual-dev>=1.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# claun

![Claun TUI](docs/screenshot.png)

Schedule Claude Code jobs with a TUI or headless mode. Sometimes systemd is just overkill. Pronounced "Klon" like the guitar pedal.

In all seriousness, the purpose of this tool is to quickly prototype workflows, or for something that is going to run on your dev desktop (like pulling/fixing bugs and submitting PRs). Please don't use it for a production pipeline! If you want to build something that you can rely on, please use systemd or Kinesis/Glue/Lambda (or I guess cron if you are old school like that). I am not responsible for any 3am pages when this falls over ;) 

## Installation

```bash
pip install claun-tui
```

## Quick Start

```bash
# Launch TUI (default)
claun

# Launch TUI with pre-filled command
claun -c "Review our metrics from the past hour for anomalies"

# Run in headless mode
claun -H -c "Update bug list from Linear MCP and fix" -m 60

# See what would run without executing
claun --dry-run -c "test command"
```

## Features

- **Simple TUI**: Single-page interface with all controls visible - no menu diving
- **Headless mode**: Run as a background service with terminal output
- **Flexible scheduling**: Days of week, hour ranges, minute intervals
- **Job timeout**: Configurable timeout kills stuck processes (default: 120s)
- **Claude flags**: Pass any flags to claude (like `--resume` for session persistence)
- **Simple logging**: Automatic log files with browseable history

## TUI Mode

Launch with `claun` to get an interactive interface with:

- Command input field
- Optional Claude flags (e.g., `--resume <session-id>` or `--model sonnet`)
- Timeout setting (seconds, 0 to disable)
- Day-of-week toggles (M T W T F S S)
- Minute interval selector (1, 5, 15, or 60 minutes)
- Big countdown clock to next run
- Pause/Resume control
- Live output log

**Keyboard shortcuts:**
- `q` - Quit
- `p` - Pause/Resume
- `r` - Run now
- `c` - Clear log

## Headless Mode

Run without TUI for background/automated use:

```bash
# Every 15 minutes (default)
claun -H -c "Check for issues"

# Hourly during work hours
claun -H -c "Status update" --hours "9am-5pm" -m 60

# Weekdays only
claun -H -c "Daily standup" --weekdays -m 60
```

## Job Timeout

Jobs have a default timeout of 120 seconds. If a job exceeds the timeout, the process is killed and the next cycle proceeds normally.

```bash
# Set a 5-minute timeout
claun -c "Big refactor" --timeout 300

# Disable timeout entirely
claun -c "Long-running task" --timeout 0

# Run once with a short timeout
claun --once -c "Quick check" --timeout 30
```

In the TUI, the timeout is editable via the "Timeout" input field. The `timeout_seconds` field is also saved/loaded from `.claun.json` config files.

## Session Persistence

To resume a previous Claude Code session, use the `--flags` option to pass `--resume`:

```bash
# First, note your session ID from a previous run
# Then resume it:
claun -c "Continue working on the feature" -f "--resume abc123-def456"

# In the TUI, enter in the "Claude Flags" field:
# --resume abc123-def456
```

You can also pass other claude flags:

```bash
# Use a specific model
claun -c "Pull and fix bugs from the Linear MCP, run /code-simplifier and push PRs" -f "--model opus"

# Enable web search
claun -c "What is the score of the Niners/Seahawks game?" -f "--allowedTools WebSearch"

# Combine multiple flags
claun -c "Fix the next bug on the bug list" -f "--resume abc123 --model sonnet"
```

## CLI Options

```
Options:
  -c, --command TEXT      Claude Code command to run
  -f, --flags TEXT        Extra flags for claude (e.g., '--resume abc123')
  -H, --headless          Run in headless mode (no TUI)
  -d, --days TEXT         Days to run (mon,tue,wed,thu,fri,sat,sun)
  --weekdays              Run only on weekdays (mon-fri)
  --weekends              Run only on weekends (sat-sun)
  --hours TEXT            Hour range (e.g., '9-17' or '9am-5pm')
  -m, --minutes [1|5|15|60]  Minute interval
  -t, --timeout INTEGER   Timeout in seconds per job (default: 120, 0 to disable)
  -l, --log-path PATH     Directory for log files
  --log-id TEXT           Optional ID prefix for log filenames
  -P, --paused            Start in paused state
  --once                  Run once immediately and exit
  --dry-run               Show schedule without executing
  -v, --version           Show version
```

## Subcommands

### Browse Logs

```bash
# List recent logs in current directory
claun logs

# List logs from specific path
claun logs --path /var/log/claun

# Limit to 10 most recent
claun logs -n 10
```

## Log Files

Logs are saved as: `[log_id_]claun_YYYYMMDD_HHMMSS_microseconds.txt`

Examples:
- `claun_20260112_143022_123456.txt`
- `myproject_claun_20260112_143022_789012.txt` (with --log-id)

## License

GPL-3.0
