{"id":50988201,"url":"https://github.com/simplerjiang/agent-foreman","last_synced_at":"2026-06-19T22:30:47.571Z","repository":{"id":365933772,"uuid":"1270785854","full_name":"simplerjiang/agent-foreman","owner":"simplerjiang","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-19T14:18:58.000Z","size":195,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T15:25:31.483Z","etag":null,"topics":["ai-agent","automation","claude-code","codex","llm","project-manager","pwa","python","web-push"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplerjiang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T03:44:29.000Z","updated_at":"2026-06-19T14:19:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simplerjiang/agent-foreman","commit_stats":null,"previous_names":["simplerjiang/agent-foreman"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/simplerjiang/agent-foreman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplerjiang%2Fagent-foreman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplerjiang%2Fagent-foreman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplerjiang%2Fagent-foreman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplerjiang%2Fagent-foreman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplerjiang","download_url":"https://codeload.github.com/simplerjiang/agent-foreman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplerjiang%2Fagent-foreman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34550858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","claude-code","codex","llm","project-manager","pwa","python","web-push"],"created_at":"2026-06-19T22:30:47.504Z","updated_at":"2026-06-19T22:30:47.566Z","avatar_url":"https://github.com/simplerjiang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Foreman 🦺\n\n**A self-hosted PM agent for your local coding agents.**\n\nForeman is a daemon that runs on your PC and acts like a project manager / foreman over your local\nAI coding agents (**Claude Code** and **Codex CLI**). It **monitors** them, **dispatches** work,\n**reviews** their output with your own LLM, and **reports to your phone** via a self-hosted PWA —\nbuzzing you for approval when an agent wants to do something risky, and letting you hand it new\ntasks while you're away from the keyboard.\n\n\u003e Inspired by [Cteno](https://github.com/zalan159/cteno-community), but deliberately scoped down to\n\u003e a single-machine MVP you can actually run tonight. See the full design in\n\u003e **[docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)**.\n\n---\n\n## Why\n\nTwo painful moments when working with CLI agents:\n\n- **When you walk away** — the agent stalls, drifts, or hits a \"are you sure?\" gate and just stops.\n- **When you come back** — you have to archaeology the logs to recall where it got to.\n\nForeman puts an LLM-driven PM in the loop 24/7: it auto-reviews and lets safe work flow, **pauses\nand pings your phone** at risk gates, and gives you a one-tap **approve / reject / redirect** from\nanywhere.\n\n## What it does\n\n| | |\n|---|---|\n| 👀 **Monitor** | Watches Claude Code (via hooks) \u0026 Codex (via output + git) in real time. |\n| 🎛️ **Dispatch** | Launch and steer `claude` / `codex` in a workspace — from the PC or your phone. |\n| 🔍 **Review** | Sends diffs to **your own LLM API** for a structured verdict (risks, suggestions). |\n| 🚦 **Gate** | Classifies actions safe / needs-strategy / requires-approval; risky ones wait for you. |\n| 📱 **Report** | Pushes briefings \u0026 approval cards to a self-hosted PWA (iOS/Android), Web Push. |\n\n## Architecture (1-minute version)\n\n```\nPC: PM Core (Python) ── drives ──▶ claude -p / codex exec   (your code workspaces)\n        │  ▲                            │\n        │  └── hooks / git / process ───┘   (monitoring)\n        │\n        └── FastAPI (REST + WS + WebPush) ──HTTPS via Tailscale──▶ 📱 Phone PWA\n                                                                   (timeline / approve / dispatch)\n```\n\nFull diagram \u0026 component contracts: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n## Status\n\n🚧 **Design + scaffold (P0).** This repo currently contains the design docs and a project skeleton.\nImplementation follows the [roadmap](docs/ROADMAP.md): P1 single-machine driving → P2 review +\ncheckpoints → P3 phone+approvals → P4 decision loop (operator + auditor + decision cards) → P5\ndefinition engine (open-core \"secret sauce\") → P6 UI editor → P7 team/relay mode.\n\nRuns **personal** (local process serves its own PWA) or **team** (one shared server acts as a relay\nfor multiple users' local processes, each connecting with an access key). Same codebase. See\n[DESIGN.zh-CN.md §8](docs/DESIGN.zh-CN.md).\n\n## Stack\n\nPython 3.11+ · FastAPI · SQLite (SQLModel) · httpx · Web Push (VAPID) · PWA service worker.\nYou bring your **own LLM API** (OpenAI-compatible or Anthropic-compatible).\n\n## Quick start (P0 scaffold)\n\n```bash\npip install -e .\ncp .env.example .env            # put your LLM API base_url + key\ncp config.example.yaml config.yaml\nforeman serve                   # boots backend, opens DB, exposes /health\n```\n\n## Docs\n\n- 🇨🇳 **[设计方案 DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)** — the primary design document.\n- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — component contracts \u0026 APIs.\n- [ROADMAP.md](docs/ROADMAP.md) — phased plan.\n- [SECURITY.md](docs/SECURITY.md) — remote access \u0026 threat model.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplerjiang%2Fagent-foreman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplerjiang%2Fagent-foreman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplerjiang%2Fagent-foreman/lists"}