opencrons

README

🟪🟩 OpenCrons — Automated AI Scheduler

Automate Claude Code on a schedule.
Chat with Claude from Telegram.
Manage everything from a beautiful TUI.

Why OpenCrons · Install · How it works · Quick start · Telegram bot · CLI reference · Configuration · Security · Roadmap

---

OpenCrons is an open-source scheduler that runs Claude Code (claude -p) jobs on cron schedules. It pairs a terminal-native TUI with a Telegram bot — so you can define, monitor, and chat with your AI jobs from anywhere. Built for developers, researchers, and teams who want structured, repeatable AI automation.

Built with Go · Cobra · Charmbracelet · SQLite · Catppuccin Mocha

---

⚠️ Security

OpenCrons is a young project — security coverage is incomplete. Use it with this in mind.

Agent execution model

Every scheduled job runs claude -p with --permission-mode bypassPermissions. This means:

• No sandbox — the agent process runs with your full user permissions, in your working directory, with access to your filesystem, network, and any tools Claude Code can invoke
• No tool restrictions by default — unless you explicitly set disallowed_tools on a job, the agent can read files, write files, run shell commands, and call external services
• Unattended — jobs trigger on a cron schedule with no human in the loop to approve or reject individual actions

This is intentional for automation — but it means the prompt is the security boundary. A poorly scoped prompt can lead to unintended writes, deletions, or network calls.

Practical guidance:

• Scope prompts tightly to the task at hand
• Use disallowed_tools to restrict capabilities where possible (e.g. Bash(rm:*))
• Set a working_dir that contains only what the job needs access to
• Review execution logs regularly (opencrons logs)
• Keep your Claude Code version up to date

Known limitations

• Prompt files are stored as plain Markdown — no encryption at rest
• settings.json stores your Telegram bot token in plaintext
• No audit log beyond the SQLite execution records
• No rate limiting or circuit breaker on job execution

This project just released and does not yet cover all security aspects. Contributions and issues are welcome.

---

Why OpenCrons 💡

The OAuth lockdown changed the game

In January 2026, Anthropic deployed server-side restrictions that blocked third-party tools from authenticating with Claude Pro and Max subscription OAuth tokens. Tools like OpenCode, OpenClaw, and other Third-party stopped working overnight. The official policy is clear:

OAuth authentication (used with Free, Pro, and Max plans) is intended exclusively for Claude Code and Claude.ai. Using OAuth tokens in any other product, tool, or service is not permitted. — Claude Code Docs — Legal and compliance

But here's the thing — claude -p is Claude Code. It's Anthropic's own CLI, running with your own subscription, exactly as intended. No OAuth hijacking, no third-party token routing, no terms of service violations. Just Claude Code doing what Claude Code was built to do.

OpenCrons wraps claude -p in a structured scheduler. Every job is a direct invocation of Claude Code — the same binary, the same auth, the same process you'd run by hand in your terminal. Nothing in between.

OpenClaw is great, but cron deserves better

OpenClaw is a fantastic personal AI assistant — WhatsApp, Telegram, iMessage, 500+ integrations. But for many developers, 80–90% of what they actually use it for is cron jobs: daily code reviews, morning briefings, CI monitoring, scheduled cleanups.

OpenCrons takes that core use case and gives it the dedicated tooling it deserves:

	OpenClaw	OpenCrons
🎯 Focus	General-purpose AI assistant	Purpose-built cron scheduler
👁️ Visibility	Jobs buried in a JSON file	Interactive TUI + structured logs
📊 Tracking	Minimal job history	SQLite with cost, tokens, status per run
🔐 Auth	Uses Claude Code OAuth	Uses Claude Code directly — fully compliant

If you need a Swiss Army knife, use OpenClaw. If you need your cron jobs to just work — with clear visibility, cost tracking, and a beautiful interface — that's OpenCrons.

---

📦 Install

Requires Go 1.25+ and Claude Code.

go install github.com/DikaVer/opencrons/cmd/opencrons@latest

That's it. The binary lands in $GOPATH/bin — already in your PATH if Go is set up correctly.

🔨 Build from source

git clone https://github.com/DikaVer/opencrons.git
cd opencrons

# Linux / macOS
sudo make install

# Windows
go install ./cmd/opencrons/

🗑️ Uninstall

# Linux / macOS
sudo make uninstall

# Windows (PowerShell)
Remove-Item "$(go env GOPATH)\bin\opencrons.exe"

Verify:

opencrons --help

---

⚙️ How it works

OpenCrons has three modes of operation:

Mode	What it does
🖥️ Interactive TUI	Run opencrons with no args. A full-screen menu for creating, editing, and managing jobs.
⌨️ CLI commands	Scriptable subcommands — opencrons add, opencrons list, opencrons run, etc.
💬 Telegram bot	Runs inside the daemon. Chat with Claude, trigger jobs, and get notifications — all from your phone.

The execution flow

📝 You define a job
  → ⏰ cron schedule triggers it
    → 📄 OpenCrons reads the prompt file
      → 🚀 pipes it to `claude -p` with your configured model & effort
        → 📊 captures output, cost, and token usage
          → 💾 logs everything to SQLite
            → 💬 (optionally) sends a summary to Telegram

Every job runs as an isolated subprocess with --permission-mode bypassPermissions for unattended operation, and --output-format json for structured result parsing.

---

🚀 Quick start

1. Run the setup wizard

opencrons setup

The wizard walks you through:

• 🔑 Provider — detects your Anthropic configuration
• 💬 Messenger — connect a Telegram bot (optional)
• 🤖 Chat defaults — pick a default model and effort level
• ⚡ Daemon mode — background process or OS service

2. Create your first job

opencrons add

The interactive wizard asks for a name, cron schedule, working directory, model, and prompt. Or go fully non-interactive:

opencrons add --non-interactive \
  --name "daily-review" \
  --schedule "0 9 * * *" \
  --working-dir "/path/to/project" \
  --prompt-content "Review open PRs and summarize findings." \
  --model sonnet

3. Start the daemon

opencrons start

The daemon runs your cron jobs, watches for config changes (hot-reload), and starts the Telegram bot if configured. Stop it with opencrons stop.

4. Check the logs

opencrons logs                    # all jobs
opencrons logs daily-review       # specific job
opencrons logs daily-review -n 50 # specific job, last 50 entries

---

💬 Telegram bot

The Telegram integration turns OpenCrons into a remote AI assistant you can reach from your pocket.

Setup

1. 🤖 Create a bot via @BotFather on Telegram
2. 🔧 Run opencrons setup or opencrons settings to configure the bot token
3. 🔐 Pair your account:
   • Verification code — OpenCrons generates a code, you send it to your bot to prove ownership

Bot commands

Command	Action
/new	🆕 Start a fresh chat session
/stop	🛑 Cancel a running query
/jobs	📋 Browse and trigger jobs
/model	🧠 Switch model (Sonnet, Opus, Haiku)
/effort	⚡ Adjust effort level
/status	📊 Daemon and session info
/help	❓ Show all commands

Send any text message to chat with Claude directly. Sessions persist across messages — Claude remembers context until you /new.

---

📖 CLI reference

📋 Job management

opencrons add              # create a job (interactive wizard)
opencrons list             # list all jobs
opencrons edit <name>      # edit a job
opencrons remove <name>    # delete a job (--force to skip confirmation)
opencrons enable <name>    # enable a disabled job
opencrons disable <name>   # disable a job
opencrons validate         # validate all job configs

▶️ Execution

opencrons run <name>       # run a job immediately
opencrons logs [name]      # view execution logs (-n to set limit)

🔄 Daemon

opencrons start            # start the daemon (foreground)
opencrons start --install  # install as OS service
opencrons stop             # stop the daemon
opencrons status           # check daemon status

🔧 Settings

opencrons setup            # first-time setup wizard
opencrons settings         # manage all settings
opencrons debug [on|off]   # toggle debug logging

🏳️ Global flags

opencrons --verbose        # verbose output (any subcommand)
opencrons --help           # help for any command

---

🗂️ Configuration

Job config

Each job is a YAML file in schedules/ with a corresponding prompt in prompts/.

Field	Description	Default
name	Unique identifier (alphanumeric, hyphens, underscores)	required
schedule	Cron expression (0 9 * * *)	required
working_dir	Project directory for execution	required
prompt_file	Markdown file with the prompt	<name>.md
model	sonnet, opus, or haiku	provider default
effort	low, medium, high, or max	high
timeout	Seconds before killing the job	300
disallowed_tools	Tool restrictions (e.g. Bash(git:*))	none
summary_enabled	Generate execution summary	false
enabled	Whether the job runs on schedule	true

📂 Directory structure

OpenCrons stores its configuration and data in a platform-specific directory:

Platform	Path
🐧 Linux	~/.opencrons/ or $XDG_CONFIG_HOME/opencrons/
🍎 macOS	~/.opencrons/ or $XDG_CONFIG_HOME/opencrons/
🪟 Windows	%APPDATA%\opencrons\

~/.opencrons/
├── .agents/              # agent config directory (canonical)
│   └── skills/           # scheduling skill + plugin skills
├── .claude/ → .agents/   # provider symlink (Anthropic)
├── AGENTS.md             # agent instructions (canonical)
├── CLAUDE.md → AGENTS.md # provider symlink (Anthropic)
├── schedules/            # job configs (YAML)
├── prompts/              # prompt files (Markdown)
├── logs/                 # execution stdout/stderr
├── summary/              # execution summaries
├── data/opencrons.db     # SQLite database
├── settings.json         # all settings
└── opencrons.pid         # daemon lock file

The .agents/ directory and AGENTS.md file are the canonical (real) locations. Provider-specific names like .claude/ and CLAUDE.md are created as symlinks so that each provider's tooling finds what it expects. On Windows without developer mode, junctions and hard links are used as fallbacks.

🤖 Agent instructions (AGENTS.md)

OpenCrons copies AGENTS.md and .agents/ into your config directory during setup. AGENTS.md is injected into every job as context — it acts as a shared system prompt so Claude understands it's running inside OpenCrons.

You can customize it to add project-wide instructions, coding standards, or constraints that apply to all your scheduled jobs.

A ready-to-use example is included in the repo at .workspace-example/ — it's copied automatically on first run via opencrons setup.

🖥️ Platform support

	Linux	macOS	Windows
CLI & TUI	✅	✅	✅
Daemon	✅	✅	✅
OS service install	✅	✅	✅

---

🔍 How jobs execute

When a job triggers, OpenCrons:

1. 📄 Reads the prompt file and prepends a task preamble
2. 📎 Optionally appends a summary prompt
3. 🔒 Pipes everything via stdin to claude -p (avoids argument length limits)
4. 🚀 Passes --effort, --model, --permission-mode bypassPermissions, --output-format json
5. 📝 Captures stdout/stderr to log files
6. 📊 Parses the JSON response for cost, token usage, and result
7. 💾 Writes execution records to SQLite

Config changes are picked up automatically — the daemon watches the schedules/ directory with fsnotify and hot-reloads jobs without restart.

---

🗺️ Roadmap

OpenCrons is focused on Claude Code today, but the vision is broader.

🔜 Coming soon

• 🧠 Anthropic API — run jobs directly with Anthropic API without requiring Claude Code installed — lower overhead, API key auth, usage-based billing
• 🤖 OpenAI API — first-class support for the OpenAI API — same scheduling, same TUI, same logs, different provider
• ⌨️ Codex CLI support — run OpenAI's Codex CLI alongside Claude Code jobs
• 🔌 Plugin system — interactive, controllable integrations:

Plugin	What it does
🐙 GitHub	Auto-review PRs, create issues, merge when checks pass
📧 Email	Morning digest, inbox triage, auto-replies
📐 Linear	Create/update issues from job results, sync sprint status
💬 Slack	Post summaries, respond to threads, channel notifications
📊 Custom	Bring your own plugin — webhook-based architecture

🔮 Future ideas

• 🏷️ Job tags and filtering
• 📱 Push notifications (beyond Telegram)
• 🔀 Multi-provider jobs — run the same prompt against Claude and GPT in parallel, compare results
• 🧠 Agent task memory — persistent per-job memory that survives between runs; agents accumulate context across executions rather than starting cold each time
• 🔄 Workflow agent pipeline — chain multiple agents into a directed pipeline where each agent's output becomes the next one's input; branch on conditions, fan out in parallel, merge results
• 📦 Sandbox environment — run agents inside an isolated container or VM with restricted filesystem and network access, so bypassPermissions is safer by construction

Have an idea? Open an issue — contributions are welcome.

---

🛠️ Development

make build          # build binary
make build-all      # cross-compile (linux + windows)
make test           # run tests
make lint           # golangci-lint
make tidy           # go mod tidy
make clean          # remove build artifacts

Architecture

cmd/opencrons/           → entry point
internal/
├── cmd/                → Cobra commands + TUI menu
├── config/             → job config, YAML I/O, prompt files
├── tui/                → interactive wizards and menus
├── executor/           → claude -p command builder and runner
├── storage/            → SQLite (execution logs, chat sessions)
├── daemon/             → cron orchestrator, hot-reload, OS service
├── platform/           → cross-platform paths, PID, settings
├── provider/           → AI provider interface
├── messenger/telegram/ → Telegram bot handlers
├── chat/               → chat session manager
├── logger/             → debug logging
└── ui/                 → shared styles (Catppuccin Mocha)