aiwff-runtime

繁體中文說明 -> README.zh-TW.md

What is this?

aiwff-runtime is a local minimal brain for personal AI work: send a message to Telegram, Claude runs on your machine autonomously, the result is pushed back to you, and you can watch progress in the browser.

It is designed for a single local operator who wants an agent runtime, not just another chat surface.

The shortest version is:

Telegram message
  -> local daemon creates a task
  -> Claude CLI reads CLAUDE.md and runs the task
  -> result is written under data/artifacts/
  -> Telegram and WebUI show the outcome

Where it sits in the AI stack

aiwff-runtime is the L5 base: a single-machine agent runtime with persistent task state. Full AIWFF is the larger L6 system.

Architecture

The minimal-brain design has 8 components. Phase 2 implements the practical core: daemon, Telegram polling, Claude CLI worker, file-bus, WebUI, CLAUDE.md brain configuration, and lightweight memory injection.

The infographic above shows the full runtime loop at a glance. For a compact source-oriented map, see docs/architecture.md.

                 ┌────────────────────┐
                 │     Telegram       │
                 │ message / result   │
                 └─────────┬──────────┘
                           │ polling with TG_BOT_TOKEN
                           v
┌────────────┐     ┌────────────────────┐     ┌────────────────────┐
│  Browser   │<--->│  Node.js daemon    │---->│   Claude CLI worker │
│  WebUI     │     │  agent/index.js    │     │   reads CLAUDE.md   │
└────────────┘     └─────────┬──────────┘     └─────────┬──────────┘
                             │                          │
                             v                          v
                    ┌────────────────────┐     ┌────────────────────┐
                    │ data/tasks/*.json  │     │ memory/facts.md    │
                    │ progress .jsonl    │     │ memory/preferences │
                    └─────────┬──────────┘     └────────────────────┘
                              │
                              v
                    ┌────────────────────┐
                    │ data/artifacts/    │
                    │ <task>.result.md   │
                    └────────────────────┘

One full pass looks like this:

You send a Telegram task
  -> TG polling receives it
  -> daemon writes data/tasks/<id>.json
  -> daemon spawns Claude CLI
  -> Claude reads CLAUDE.md plus memory files
  -> Claude writes progress and a result artifact
  -> daemon marks the task done or failed
  -> Telegram receives the result notice
  -> WebUI shows the same task state

Screenshots

HUD dashboard	Task progress	Chat / new task

Quick Start

Prerequisites:

10-minute setup:

git clone https://github.com/zaxardery8011-design/aiwff-runtime
cd aiwff-runtime
cp .env.example .env

Edit .env:

TG_BOT_TOKEN=<your_bot_token>
ADMIN_TG_CHAT_ID=<your_chat_id>

Start the runtime:

npm start

Custom port / Windows note: the default port is 3100. To use another port: PORT=3200 npm start (bash / macOS / Linux). On Windows PowerShell the inline VAR=value command form does not work; run $env:PORT=3200; npm start instead.

Then verify it:

1. Open http://127.0.0.1:3100.
2. Send any message to your Telegram Bot.
3. Confirm a new task appears in the WebUI.
4. Wait for the Telegram completion notice.
5. Inspect the artifact path shown in the task detail panel.

Useful local checks:

npm run doctor
npm run demo
npm run verify-demo

For a mock-only run without Claude CLI execution, set:

MOCK_WORKER=1

Codex Install Prompt

Paste this prompt into a local coding agent when you want a mock-only install and verification pass:

你是我的本機 coding agent。請幫我安裝並驗證 aiwff-runtime。

目標：
- clone 官方 repo 到本機工作資料夾
- 只跑 mock demo
- 不接 Telegram、LINE、Claude OAuth、Task Scheduler
- 不讀取、上傳或修改我的私人檔案
- 安裝完成後啟動 WebUI，並回報可開啟的 localhost URL

步驟：
1. git clone https://github.com/zaxardery8011-design/aiwff-runtime
2. cd aiwff-runtime
3. 檢查 Node.js 與 npm：node --version；npm --version。Node.js 必須 >= 18。
4. npm install
5. npm run doctor
6. MOCK_WORKER=1 npm run demo
   - PowerShell 可用：$env:MOCK_WORKER='1'; npm run demo
7. npm run verify-demo
8. npm run web
9. 回報：
   - demo task id
   - artifact path
   - verifier verdict
   - localhost URL

如果任何一步失敗，不要亂改系統、不要接 Telegram/OAuth、不要改 Task Scheduler；先停下來回報錯誤與你已執行的命令。

TG Bot Setup

1. Open Telegram and search for @BotFather.
2. Send /newbot.
3. Follow the prompts and copy the token.
4. Paste it into .env as TG_BOT_TOKEN.
5. Send any message to @userinfobot.
6. Copy your numeric chat ID.
7. Paste it into .env as ADMIN_TG_CHAT_ID.

ADMIN_TG_CHAT_ID is required when TG_BOT_TOKEN is set. If it is left empty, the runtime refuses Telegram polling.

This runtime uses polling. You do not need a webhook, public hostname, reverse proxy, or public IP address.

Brain Configuration

Editing CLAUDE.md changes the brain's behaviour. No JavaScript code change is needed.

Claude CLI reads CLAUDE.md from the repo root. In Phase 2, the daemon also injects:

• memory/facts.md
• memory/preferences.md
• the task title, instruction, and task ID
• the required artifact path
• the final DONE: ... completion line contract

Minimal CLAUDE.md template:

# Agent Configuration

You are the user's local AI assistant. When you receive a task, do not only answer.
Use tools and execute the task until it is complete.

## Execution Rules
1. Understand the intent, not only the literal wording.
2. Use tools to complete the task: Read / Write / Edit / Bash / Glob / Grep.
3. Save the result to `data/artifacts/<task_id>.result.md`.
4. The final line must be: `DONE: <one sentence describing what you completed>`.

## Boundaries
- Do not modify `.env` or credential files.
- Do not make external network requests unless the task explicitly asks for them.
- If you do not know how to complete the task, say so in progress. Do not pretend it is done.

## Working Directory
{project_root}

Examples of things you can tune in CLAUDE.md:

Prebuilt personas live in templates/claude/: dev partner, research assistant, and daily helper.

Configuration

Copy .env.example to .env. The current .env.example exposes these fields:

In real Claude mode, the daemon sends the generated task prompt through stdin instead of placing it in argv. This avoids long prompt and quoting issues while preserving streamed stdout progress.

Current .env.example:

PORT=3100
TG_BOT_TOKEN=
ADMIN_TG_CHAT_ID=
CLAUDE_CMD=claude
MOCK_WORKER=1
ENABLE_REAL_CLAUDE_WORKER=
CLAUDE_BYPASS_APPROVALS=

WORK_DIR appears in the design draft, but it is not present in the current .env.example and is not read by the current Phase 2 runtime.

Vs Full AIWFF

The rule of this repo: remove multi-node complexity, keep the single-machine agent loop understandable.

Honest Limitations

These limitations are intentionally not softened.

Roadmap

Until this PR is merged, the public master baseline remains Phase 1. Phase 2 is the current PR branch scope.

Support

• Technical support: GitHub Issues.
• Full / customized version: https://zax.com.tw

Related — the discipline toolchain

aiwff-runtime is the engine — the local agent runtime that actually runs your agents. Want it to stay disciplined once it's running? Pair it with the guardrails:

• soplint — static SOP-compliance audit for AI work nodes
• execution-proofs — MCP telemetry gateway: force agents to prove "done" with real files & timestamps
• aiwff-runtime — the local agent runtime (this repo)

引擎（跑得動的 agent）＋護欄（審紀律、逼證明），同一套「讓 AI 守紀律」哲學的兩面。

License

MIT