winhok / agent-os

# Agent OS
**A self-hosted command layer for running Claude Code and Codex through Feishu (Lark).**
Give a bot a goal in a Feishu thread. Agent OS keeps the CLI session tied to that thread, routes work between configured bot roles, and brings questions, plans, approvals, progress, and results back to Feishu. The work runs on your own machine in the project directory you configure.
简体中文
## What it does
- **Thread-based sessions:** Continue a task in the same thread, start a new session, resume an earlier one, compact context, or switch project directories.
- **Two CLI engines:** Configure Claude Code or Codex as each bot's default engine, or choose one when starting a thread.
- **Team coordination:** A designated team leader can assign work to other configured bots and summarize their results.
- **Decisions in Feishu:** Answer clarification questions, review product plans, and respond to operation approval cards.
- **Product handoff:** Review a Feishu document or a local plan before implementation. With Feishu document delivery, comments can drive revisions to the same document.
- **Scheduled work:** Create one-time, interval, or Cron tasks, then pause, resume, run, or delete them.
- **Local state:** Session metadata, approvals, schedules, and run records stay on the host running Agent OS.
## Get started
### Prerequisites
- Node.js 22.13+ (22.x) or 24+ and pnpm (use the version in `package.json`, currently 12.6.0).
- At least one installed and authenticated CLI, `claude` or `codex`, that can run in the target project directory.
- A Feishu custom app with bot capability for each enabled bot. You need its App ID and App Secret.
- For the example product delivery workflow: install the Skills named in the bot configuration separately. Feishu document delivery also requires `lark-cli` and the appropriate user authorization. Listing a Skill in the configuration does not install it.
From the repository root:
 [code] 
### Configure bots and workspaces
Edit `.env` with the App ID and App Secret for each enabled bot. The variable names come from `appIdEnv` and `appSecretEnv` in `config/bots.json`.
The example configuration defines three bots:
| Bot ID | Role |
| --------------- | -------------------------------------------------------- |
| `ceo-assistant` | Understand goals, assign work, and summarize results |
| `product` | Clarify requirements and prepare the product plan |
| `developer` | Implement an approved plan and run its configured checks |
`teamLeader` must name an enabled bot. Set `enabled: false` for a bot you are not using; disabled bots do not need credentials.
| Setting | Purpose |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `defaultCli` | `claude` or `codex` |
| `workspace` | Bot's project directory; relative paths resolve from the Agent OS startup directory |
| `role` / `systemPrompt` | Bot responsibilities and instructions |
| `skills` | Names of Skills available