kage-ai 0.1.10

AI-native cron task runner for per-project scheduled prompts and commands.

kage 影 - Autonomous AI Project Agent

English | 日本語

kage is an autonomous execution layer for project-specific AI agents. It schedules AI-driven tasks via cron, maintains state across runs using a persistent memory system, and provides advanced workflow controls.

Go to sleep. Wake up to results. — kage runs your AI agents overnight, so you start every morning with answers, not questions.

Dashboard

Execution Logs	Settings & Tasks

Features

• Autonomous Agent Logic: Automatically decomposes tasks into GFM checklists and tracks progress.
• Persistent Memory: Stores task state in .kage/memory/ to maintain context across runs.
• Hybrid Tasks: Supports both AI prompts (Markdown body) and direct shell commands (command in front matter).
• Advanced Workflow Controls:
  • Execution Modes: continuous, once, autostop.
  • Concurrency Policy: allow, forbid (skip if running), replace (kill old).
  • Time Windows: Restrict execution using allowed_hours: "9-17" or denied_hours: "12".
• Markdown-First: Define tasks using simple Markdown files with YAML front matter.
• Layered Configuration: .kage/config.local.toml > .kage/config.toml > ~/.kage/config.toml > defaults.
• Web Dashboard: Execution history, task management, and AI chat — all in one place.

Installation

pip install kage-ai
# or
curl -sSL https://raw.githubusercontent.com/igtm/kage/main/install.sh | bash

Quick Start

kage onboard     # Global setup (daemons, directories, DB)
cd your-project
kage init         # Initialize kage in the current directory
# Edit .kage/tasks/*.md to define your tasks
kage run          # Manually trigger tasks (or let the daemon handle it)
kage ui           # Open the web dashboard

Use Cases

🌙 Overnight Tech Evaluation (OCR Model Benchmark)

The killer use case: go to sleep, wake up with a complete technology evaluation report.

Create a single task that, on every cron run, picks the next untested OCR model, implements it, runs it against your test PDFs, and records the accuracy. By morning, you have a ranked comparison.

.kage/tasks/ocr_benchmark.md:

---
name: OCR Model Benchmark
cron: "0 * * * *"
provider: claude
mode: autostop
denied_hours: "9-23"
---

# Task: PDF OCR Technology Evaluation

You are conducting a systematic evaluation of free/open-source OCR solutions for extracting text from Japanese financial PDF documents.

## Target Models (test one per run)
- Tesseract (jpn + jpn_vert)
- EasyOCR
- PaddleOCR
- Surya OCR
- DocTR (doctr)
- manga-ocr (for vertical text)
- Google Vision API (free tier)

## Instructions
1. Check `.kage/memory/` for which models have already been tested.
2. Pick the NEXT untested model from the list above.
3. Install it and write a test script in `benchmark/test_{model_name}.py`.
4. Run it against the PDF files in `benchmark/test_pdfs/`.
5. Measure: Character accuracy (CER), processing time, memory usage.
6. Save results to `benchmark/results/{model_name}.json`.
7. Update `benchmark/RANKING.md` with a comparison table of all tested models so far.
8. When all models are tested, set status to "Completed" in memory.

When you wake up:

benchmark/
├── RANKING.md              ← Full comparison table, ready for decision
├── results/
│   ├── tesseract.json
│   ├── easyocr.json
│   ├── paddleocr.json
│   └── ...
└── test_pdfs/
    ├── invoice_001.pdf
    └── report_002.pdf

🔍 Overnight Codebase Audit

.kage/tasks/audit.md:

---
name: Architecture Auditor
cron: "0 2 * * *"
provider: gemini
mode: continuous
denied_hours: "9-18"
---

# Task: Nightly Architecture Health Check
Analyze the codebase for:
- Dead code and unused exports
- Circular dependencies
- API endpoints without tests
- Security anti-patterns (hardcoded secrets, SQL injection risks)

Write findings to `reports/audit_{date}.md`.

🧪 Overnight PoC Builder

.kage/tasks/poc_builder.md:

---
name: PoC Builder
cron: "30 0 * * *"
provider: claude
mode: autostop
denied_hours: "8-23"
---

# Task: Build a Proof of Concept

Read the spec in `specs/next_poc.md` and implement a working prototype.
- Create the implementation in `poc/` directory
- Include a README with setup instructions and demo commands
- Write basic tests to verify core functionality
- Set status to "Completed" when the PoC is functional

⚡ Simple Examples

AI Task — hourly health check:

---
name: Project Auditor
cron: "0 * * * *"
provider: gemini
---
Analyze the current codebase for architectural drifts.

Shell-Command Task — nightly log cleanup:

---
name: Log Cleanup
cron: "0 0 * * *"
command: "rm -rf ./logs/*.log"
shell: "bash"
---
Cleanup old logs every midnight.

Commands

Command	Description
kage onboard	Global setup (daemons, directories, DB)
kage init	Initialize kage in the current directory
kage run	Manually trigger due tasks
kage task list	List all tasks with status and schedule
kage task show <name>	Show detailed task configuration
kage doctor	Diagnose configuration health
kage skill	Display agent skill guidelines
kage ui	Open the web dashboard

Configuration

File	Scope
~/.kage/config.toml	Global settings
.kage/config.toml	Project-shared settings
.kage/config.local.toml	Local overrides (git-ignored)
.kage/system_prompt.md	Project-specific AI instructions

License

MIT