kage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kage - Autonomous AI Project Agent

kage - 自主AI项目代理

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.

kage

是AI Agent的自主执行层。它在多次执行间维护状态（Memory），将高层目标拆解为待办事项列表，并提供强大的工作流控制。

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.

自主工作流：将任务拆解为Markdown清单，并通过Memory跟踪进度。
执行模式：
```
continuous
```
（默认）、
```
once
```
（运行一次后停用）、
```
autostop
```
（当AI表示任务完成时停止）。
混合任务类型：AI驱动的提示词（Markdown正文）或直接Shell命令（
```
command
```
前置元数据）。
并发控制：
```
allow
```
、
```
forbid
```
（若任务正在运行则跳过）、
```
replace
```
（终止旧任务并重启）。
时间窗口：
```
allowed_hours: "9-17"
```
或
```
denied_hours: "12"
```
。
状态持久化：存储于
```
.kage/memory/{task}/{date}.json
```
。
连接器：与Discord/Slack/Telegram集成，实现任务通知（始终启用）和可选的双向聊天（
```
poll = true
```
）。

分层配置：

.kage/config.local.toml

.kage/config.toml

~/.kage/config.toml

> 默认配置。

CLI

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.

```
kage onboard
```
— 设置全局目录和
```
kage cron
```
。
```
kage init
```
— 在当前目录初始化kage。
```
kage run <task>
```
— 立即执行指定任务。
```
kage compile <task>
```
— 将提示词任务编译为同级的
```
.lock.sh
```
覆盖文件。
```
kage cron run
```
— 执行一次调度器循环（供cron/launchd调用）。
```
kage runs
```
— 以相对时间表格形式列出执行记录；添加
```
--absolute-time
```
参数可查看详细时间戳。
```
kage runs show <exec_id>
```
— 查看运行元数据和日志路径。
```
kage runs stop <exec_id>
```
— 停止正在运行的任务执行。
```
kage logs [<task>]
```
— 打开指定任务最新运行的原始日志；若省略任务名则合并所有任务日志。
```
kage logs --run <exec_id>
```
— 打开指定运行记录的原始日志。
```
kage task list
```
— 列出所有任务，显示简短项目名、有效类型、提供商/命令。
```
kage task show <name>
```
— 查看任务的详细配置，包括当前提示词哈希值。
```
kage connector list
```
— 列出所有已配置的连接器。
```
kage connector setup <type>
```
— 显示指定类型连接器的设置指南（discord、slack、telegram）。
```
kage connector poll
```
— 手动触发所有连接器的轮询操作。
```
kage doctor
```
— 诊断配置和环境状态。
```
kage migrate install
```
— 手动运行待处理的安装时迁移脚本。
```
kage ui
```
— 打开Web控制面板。
```
kage tui
```
— 打开基于Textual的终端控制面板，包含日志、任务、连接器和设置标签页。

Shell补全支持位置参数（任务/运行记录），因此执行

kage completion install bash|zsh

后，

kage run <task>

、

kage compile <task>

、

kage logs [<task>]

、

kage task run <name>

、

kage task show <name>

、

kage runs show <exec_id>

和

kage stop <exec_id>

等命令都能自动补全具体值。

kage doctor

会报告这些补全脚本是否已安装。

如果提示词任务存在同级的编译锁定文件（如

.kage/tasks/nightly.lock.sh

），只有当存储的

prompt_hash

与当前提示词正文匹配时，kage才会执行该锁定文件而非Markdown提示词正文。若提示词正文发生变化，锁定文件会失效，需通过

kage compile <task>

重新生成。

kage doctor

、

kage task list

和控制面板都会显示锁定文件是新鲜、失效还是缺失状态，

kage task show <name>

会打印当前提示词的哈希值。

在

kage task list

中，提示词任务会显示为

Prompt

或

Prompt (Compiled)

，失效的编译锁定文件会高亮显示，项目列仅使用叶子目录名称，继承的提供商会明确显示为

gemini (Inherited)

这类值。内置的

codex

命令模板默认执行

codex exec --yolo ...

。

连接器轮询的回复会被记录为普通运行记录。使用

kage runs --source connector_poll

可找到这些记录，通过

kage logs --run <exec_id>

可查看原始AI CLI输出。

安装时迁移脚本会自动从

src/kage/migrations/install/

kage migrate install

和

install.sh

自动识别。

kage tui

是优先面向终端的控制面板。其日志标签页可通过任务列表和运行记录过滤日志，任务标签页显示任务详情，连接器标签页显示连接器历史，设置标签页显示已解析的全局配置。

Task File Template (

.kage/tasks/*.md

)

任务文件模板（

.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
---

markdown

---
name: <Task Name>
cron: "<cron expression>"
provider: <provider name>           # 例如：codex, claude, gemini, opencode, copilot, aider
mode: continuous                    # continuous | once | autostop
concurrency_policy: allow           # allow | forbid | replace
timeout_minutes: 60                 # 分钟（可选）
working_dir: ../../workspace        # 可选；相对于当前任务文件的路径，或绝对路径
timezone: "Asia/Tokyo"              # 例如："UTC", "Asia/Tokyo"（可选）
allowed_hours: "9-17"               # 例如："9-17,21"（可选）
denied_hours: "0-5"                 # 例如："0-5,12"（可选）
notify_connectors: ["discord"]      # 连接器名称列表（可选）
active: true
---

Task: <Title>

<Describe what the AI agent should do here.> ```

<在此描述AI Agent需要执行的操作。>

undefined

Shell-Command Task Variant

Shell命令任务变体

markdown

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

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.

连接器用于与外部聊天服务集成。只要配置了凭证，通过

notify_connectors

发送任务通知始终启用。轮询（双向聊天）功能由

poll

标志控制。

toml

[connectors.my_discord]
type = "discord"
poll = false          # 设置为true以启用双向聊天
working_dir = "~/my-project"  # 可选：该连接器的执行目录
bot_token = "..."
channel_id = "..."

⚠️ 安全警告：设置
poll = true
会允许频道内的任何人与AI交互，而AI拥有对您电脑文件系统和工具的完全访问权限。仅在私人/可信频道中启用轮询功能。

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/config.local.toml
```
（Git忽略的覆盖配置）
```
.kage/config.toml
```
（项目共享配置）
```
~/.kage/config.toml
```
（用户全局配置）
库默认配置

后台循环：通过
```
kage cron install
```
运行（基于cron/launchd）。

kage

Original

Translation

kage - Autonomous AI Project Agent

kage - 自主AI项目代理

Core Features

核心特性

CLI

CLI 命令

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

任务文件模板（
`.kage/tasks/*.md`
）

Task: <Title>

Task: <Title>

Shell-Command Task Variant

Shell命令任务变体

Connectors

连接器

Configuration Hierarchy

配置层级

kage

Original

Translation

kage - Autonomous AI Project Agent

kage - 自主AI项目代理

Core Features

核心特性

CLI

CLI 命令

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

任务文件模板（.kage/tasks/*.md）

Task: <Title>

Task: <Title>

Shell-Command Task Variant

Shell命令任务变体

Connectors

连接器

Configuration Hierarchy

配置层级

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

任务文件模板（
`.kage/tasks/*.md`
）