https://github.com/simplerjiang/agent-foreman
A self-hosted PM agent that supervises your local coding agents (Claude Code / Codex), reviews their work with your own LLM, and reports to your phone via PWA + Web Push.
https://github.com/simplerjiang/agent-foreman
ai-agent automation claude-code codex llm project-manager pwa python web-push
Last synced: 6 days ago
JSON representation
A self-hosted PM agent that supervises your local coding agents (Claude Code / Codex), reviews their work with your own LLM, and reports to your phone via PWA + Web Push.
- Host: GitHub
- URL: https://github.com/simplerjiang/agent-foreman
- Owner: simplerjiang
- License: mit
- Created: 2026-06-16T03:44:29.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-19T14:18:58.000Z (6 days ago)
- Last Synced: 2026-06-19T15:25:31.483Z (6 days ago)
- Topics: ai-agent, automation, claude-code, codex, llm, project-manager, pwa, python, web-push
- Language: Python
- Size: 190 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/SECURITY.md
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# Foreman ๐ฆบ
**A self-hosted PM agent for your local coding agents.**
Foreman is a daemon that runs on your PC and acts like a project manager / foreman over your local
AI coding agents (**Claude Code** and **Codex CLI**). It **monitors** them, **dispatches** work,
**reviews** their output with your own LLM, and **reports to your phone** via a self-hosted PWA โ
buzzing you for approval when an agent wants to do something risky, and letting you hand it new
tasks while you're away from the keyboard.
> Inspired by [Cteno](https://github.com/zalan159/cteno-community), but deliberately scoped down to
> a single-machine MVP you can actually run tonight. See the full design in
> **[docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)**.
---
## Why
Two painful moments when working with CLI agents:
- **When you walk away** โ the agent stalls, drifts, or hits a "are you sure?" gate and just stops.
- **When you come back** โ you have to archaeology the logs to recall where it got to.
Foreman puts an LLM-driven PM in the loop 24/7: it auto-reviews and lets safe work flow, **pauses
and pings your phone** at risk gates, and gives you a one-tap **approve / reject / redirect** from
anywhere.
## What it does
| | |
|---|---|
| ๐ **Monitor** | Watches Claude Code (via hooks) & Codex (via output + git) in real time. |
| ๐๏ธ **Dispatch** | Launch and steer `claude` / `codex` in a workspace โ from the PC or your phone. |
| ๐ **Review** | Sends diffs to **your own LLM API** for a structured verdict (risks, suggestions). |
| ๐ฆ **Gate** | Classifies actions safe / needs-strategy / requires-approval; risky ones wait for you. |
| ๐ฑ **Report** | Pushes briefings & approval cards to a self-hosted PWA (iOS/Android), Web Push. |
## Architecture (1-minute version)
```
PC: PM Core (Python) โโ drives โโโถ claude -p / codex exec (your code workspaces)
โ โฒ โ
โ โโโ hooks / git / process โโโโ (monitoring)
โ
โโโ FastAPI (REST + WS + WebPush) โโHTTPS via Tailscaleโโโถ ๐ฑ Phone PWA
(timeline / approve / dispatch)
```
Full diagram & component contracts: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Status
๐ง **Design + scaffold (P0).** This repo currently contains the design docs and a project skeleton.
Implementation follows the [roadmap](docs/ROADMAP.md): P1 single-machine driving โ P2 review +
checkpoints โ P3 phone+approvals โ P4 decision loop (operator + auditor + decision cards) โ P5
definition engine (open-core "secret sauce") โ P6 UI editor โ P7 team/relay mode.
Runs **personal** (local process serves its own PWA) or **team** (one shared server acts as a relay
for multiple users' local processes, each connecting with an access key). Same codebase. See
[DESIGN.zh-CN.md ยง8](docs/DESIGN.zh-CN.md).
## Stack
Python 3.11+ ยท FastAPI ยท SQLite (SQLModel) ยท httpx ยท Web Push (VAPID) ยท PWA service worker.
You bring your **own LLM API** (OpenAI-compatible or Anthropic-compatible).
## Quick start (P0 scaffold)
```bash
pip install -e .
cp .env.example .env # put your LLM API base_url + key
cp config.example.yaml config.yaml
foreman serve # boots backend, opens DB, exposes /health
```
## Docs
- ๐จ๐ณ **[่ฎพ่ฎกๆนๆก DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)** โ the primary design document.
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) โ component contracts & APIs.
- [ROADMAP.md](docs/ROADMAP.md) โ phased plan.
- [SECURITY.md](docs/SECURITY.md) โ remote access & threat model.
## License
MIT