kage - Autonomous AI Project Agent

kage

is an autonomous execution layer for AI agents. It maintains state across executions (Memory), decomposes high-level goals into Todo lists, and provides robust workflow controls.

Core Features

Autonomous Workflow: Decomposes tasks into Markdown checklists and tracks progress via Memory.
Execution Modes:
```
continuous
```
(default),
```
once
```
(run once and deactivate),
```
autostop
```
(stop when AI signals completion).
Hybrid Task Types: AI-driven prompts (Markdown body) or direct shell commands (
```
command
```
front matter).
Concurrency Control:
```
allow
```
,
```
forbid
```
(skip if running),
```
replace
```
(kill old and restart).
Time Windows:
```
allowed_hours: "9-17"
```
or
```
denied_hours: "12"
```
.
State Persistence:
```
.kage/memory/{task}/{date}.json
```
.
Connectors: Integrate with Discord/Slack/Telegram for task notifications (always on) and optional bi-directional chat (
```
poll = true
```
).

Layered Config:

.kage/config.local.toml

.kage/config.toml

~/.kage/config.toml

> defaults.

CLI

```
kage onboard
```
— Setup global directories and
```
kage cron
```
.
```
kage init
```
— Initialize in current directory.
```
kage run <task>
```
— Execute a specific task immediately.
```
kage compile <task>
```
— Compile a prompt task into a sibling
```
.lock.sh
```
override.
```
kage cron run
```
— Execute the scheduler loop once (used by cron/launchd).
```
kage runs
```
— List execution runs in a relative-time table; add
```
--absolute-time
```
for detailed timestamps.
```
kage runs show <exec_id>
```
— Inspect run metadata and log paths.
```
kage runs stop <exec_id>
```
— Stop a running execution.
```
kage logs [<task>]
```
— Open raw logs for the latest run of a task, or merge all task logs when omitted.
```
kage logs --run <exec_id>
```
— Open raw logs for a specific run.
```
kage task list
```
— List tasks with short project names, effective type, and provider/command.
```
kage task show <name>
```
— Detailed task configuration, including the current prompt hash.
```
kage connector list
```
— List all configured connectors.
```
kage connector setup <type>
```
— Show setup guide for a connector (discord, slack, telegram).
```
kage connector poll
```
— Manually trigger polling for all connectors.
```
kage doctor
```
— Diagnose config and environment.
```
kage migrate install
```
— Run pending install-time migrations manually.
```
kage ui
```
— Open web dashboard.
```
kage tui
```
— Open the Textual terminal dashboard with logs, tasks, connectors, and settings tabs.

Shell completion covers positional task/run arguments as well, so

kage run <task>

kage compile <task>

kage logs [<task>]

kage task run <name>

kage task show <name>

kage runs show <exec_id>

, and

kage stop <exec_id>

can all suggest concrete values after

kage completion install bash|zsh

kage doctor

reports whether those completion scripts are installed.

If a prompt task has a sibling compiled lock like

.kage/tasks/nightly.lock.sh

, kage executes that lock instead of the Markdown prompt body only while the stored

prompt_hash

still matches the current prompt body. If the prompt body changes, the lock becomes stale and must be regenerated with

kage compile <task>

kage doctor

kage task list

, and the UI all surface whether the lock is fresh, stale, or missing, and

kage task show <name>

prints the current prompt hash.

kage task list

, prompt tasks render as

Prompt

Prompt (Compiled)

, stale compiled locks are highlighted, the project column uses only the leaf directory name, and inherited providers show up explicitly as values like

gemini (Inherited)

. The built-in

codex

command template runs

codex exec --yolo ...

by default.

Connector poll replies are recorded as normal runs. Use

kage runs --source connector_poll

to find them and

kage logs --run <exec_id>

to inspect raw AI CLI output.

Install-time migrations are discovered automatically from

src/kage/migrations/install/

. New migration modules added there are picked up by both

kage migrate install

and

install.sh

kage tui

is the terminal-first dashboard. Its Logs tab filters logs from a task list and run list, its Tasks tab shows task details, its Connector tab shows connector history, and its Settings tab shows the resolved global config.

Task File Template (

.kage/tasks/*.md

)

markdown

---
name: <Task Name>
cron: "<cron expression>"
provider: <provider name>           # e.g. codex, claude, gemini, opencode, copilot, aider
mode: continuous                    # continuous | once | autostop
concurrency_policy: allow           # allow | forbid | replace
timeout_minutes: 60                 # minutes (optional)
working_dir: ../../workspace        # optional; relative to this task file, or absolute path
timezone: "Asia/Tokyo"              # e.g. "UTC", "Asia/Tokyo" (optional)
allowed_hours: "9-17"               # e.g. "9-17,21" (optional)
denied_hours: "0-5"                 # e.g. "0-5,12" (optional)
notify_connectors: ["discord"]      # list of connector names (optional)
active: true
---

# Task: <Title>

<Describe what the AI agent should do here.>

Shell-Command Task Variant

markdown

---
name: <Task Name>
cron: "<cron expression>"
command: "<shell command>"
shell: bash
working_dir: ../../workspace
---

Connectors

Connectors integrate with external chat services. Sending (task notifications via

notify_connectors

) is always enabled as long as credentials are configured. Polling (bi-directional chat) is controlled by the

poll

flag.

toml

[connectors.my_discord]
type = "discord"
poll = false          # Set to true to enable bi-directional chat
working_dir = "~/my-project"  # Optional: execution directory for this connector
bot_token = "..."
channel_id = "..."

⚠️ Security Warning: Setting
poll = true
allows anyone in the channel to interact with the AI, which has full access to your PC's file system and tools. Only enable polling in private/trusted channels.

Configuration Hierarchy

```
.kage/config.local.toml
```
(Git-ignored overrides)
```
.kage/config.toml
```
(Project-shared)
```
~/.kage/config.toml
```
(User-global)
Library Defaults

Background Loop: Runs via
```
kage cron install
```
(cron/launchd).

kage

NPX Install

Tags

SKILL.md Content

kage - Autonomous AI Project Agent

Core Features

CLI

Task File Template (
`.kage/tasks/*.md`
)

Shell-Command Task Variant

Connectors

Configuration Hierarchy

kage

NPX Install

Tags

SKILL.md Content

kage - Autonomous AI Project Agent

Core Features

CLI

Task File Template (.kage/tasks/*.md)

Shell-Command Task Variant

Connectors

Configuration Hierarchy

Task File Template (
`.kage/tasks/*.md`
)