pmgo

A local-first AI project manager for Windows, macOS, and Linux. OpenClaw and Hermes are optional connectors.

Languages: English · 简体中文 · 繁體中文

Heads up — early development. Design and APIs may still change. Shipped in tree: project-core, daily/weekly reports, risk-radar, GitHub/Linear/Jira connectors, and the policy-aware MCP server. Still planned: Feishu/DingTalk/Notion depth, Live Canvas, and richer multi-agent runtime wiring. Feedback and issues are welcome.

pmgo is becoming a standalone, local-first desktop project manager. SQLite, Markdown, and attachments stay on your device; model access is provided through replaceable providers. OpenClaw and Hermes remain optional connectors for channels and automation, not prerequisites.

• Personal GTD / OKR
• Agile team workflows (Jira, Linear, GitHub Issues)
• Full software development lifecycle (requirements → dev → test → release)
• General team project management (Feishu, DingTalk, Notion)

It ships as a skills pack, not a fork — one MCP server and one memory store work on both runtimes without merge pain.

• Native desktop — one product for Windows, macOS, and Linux, with an Electron shell and bundled Python core.
• Local first — SQLite and Markdown use the OS application-data directory; project data does not require a cloud service.
• Model choice — OpenAI-compatible endpoints and local Ollama are the first providers; keys are held by OS secure storage.
• Optional runtimes — the same skills can still connect to OpenClaw and Hermes.
• Multi-channel — Telegram, Feishu, Slack, Discord, WhatsApp, and more via your gateway.
• Always-on — heartbeats drive morning briefings, blocker scans, and Friday reports without you asking.
• Persistent memory — SQLite + human-readable Markdown under memory/projects/<slug>/.
• Sandboxed — allow-list policy for sensitive writes (Jira transitions, PR close, file writes).
• Multi-agent — a main pmgo brain delegates to planner, tracker, risker, and reporter sub-agents.
• i18n-ready — English, Simplified Chinese, and Traditional Chinese out of the box.

Desktop development preview:

npm install
npm run pmgo -- onboard --name "My Work" --locale en
npm run desktop:dev

The desktop client creates its data on first launch and needs neither OpenClaw nor Hermes. Release builds are produced natively for each OS through the desktop workflow. See desktop architecture.

Optional headless/runtime workflow:

# 1) Bootstrap repository memory + linked project
npm run gtd:bootstrap -- --name "My GTD" --locale zh-CN
# eval the printed exports, or:
export PMGO_WORKSPACE="$(pwd)"
export PMGO_DEFAULT_PROJECT_ID="<uuid-from-output>"

# 2) First report without a gateway
npm run daily-standup -- report

# 3) One-command runtime setup (installs missing MCP deps, registers MCP + persona/agent)
npm run setup -- --runtime openclaw   # or: hermes

# 4) Diagnose, then launch the runtime dashboard
npm run doctor -- --runtime openclaw  # or: hermes
npm run start -- --runtime openclaw   # or: hermes

# Safe removal (keeps pmgo project data and the OpenClaw workspace)
npm run uninstall -- --runtime openclaw  # or: hermes

Install the free CLI for direct pmgo commands:

python3.11 -m pip install -e .
pmgo project list
pmgo task add "Prepare weekly review" --priority high
pmgo context --json

CLI reference: docs/CLI.md.

Preview setup without changing runtime configuration with --dry-run. The older npm run runtime:config -- --runtime ... command remains available when you want to apply the generated configuration manually. Setup creates/reuses the dedicated .pmgo-venv and makes the MCP registration use that exact Python interpreter.

Guides: OpenClaw · Hermes · Telegram E2E · Feishu E2E · PRD · Architecture

• apps/desktop/ — cross-platform desktop shell and local UI
• pmgo_app/ — runtime-independent SQLite core, loopback API, and model providers
• agent/ — persona package (SOUL.md, IDENTITY.md, USER.md, TOOLS.md, AGENTS.md)
• runtimes/ — OpenClaw and Hermes integration guides
• shared/ — shared MCP env and cron message templates
• skills/ - MCP skill definitions and implementations
• locales/ - runtime i18n dictionaries (en, zh-CN, zh-TW)
• policy/pmgo.policy.yaml - allow-list and confirmation policy
• cron/jobs.yaml - schedule intent (generate CLI via npm run cron:config)
• docs/ - architecture, deploy, first-report, Live Canvas, publishing
• memory/templates/ - locale-aware reporting templates
• memory/schema.sql - canonical SQLite schema snapshot
• memory/migrations/ - append-only schema migration history

pmgo uses a hybrid memory model:

• SQLite DB (memory/pmgo.db) stores structured long-term entities.
• Schema SQL (memory/schema.sql) defines canonical database structure.
• Markdown (memory/projects/<slug>/) stores human-readable project notes.

Initialize and verify local memory DB:

npm run memory:check
npm run memory:init
npm run memory:migrate
npm run memory:verify

Or run the full bootstrap pipeline in one command:

npm run memory:scaffold

And with project markdown scaffolding:

npm run memory:scaffold -- --project-name "PMGO MVP" --locale zh-CN

Initialize project-scoped markdown memory directory:

npm run memory:init:project -- --name "PMGO MVP" --locale en

Optional arguments:

• --slug to force a custom directory name under memory/projects/.
• --locale supports en, zh-CN, and zh-TW (default: en).

Set GITHUB_TOKEN and GITHUB_REPO=owner/name (for example flygoly/pmgo). Then use the bundled REST helper:

npm run github-issues -- smoke
npm run github-issues -- list --state open
npm run github-issues -- import-task --project-id <UUID> --number 42

Details: skills/integration-github/SKILL.md. Importing creates a local task with source=github and external_id set to GitHub’s numeric issue id for idempotency.

Set LINEAR_API_KEY from Linear → Settings → API. Then:

npm run linear-issues -- smoke
npm run linear-issues -- list --first 10
npm run linear-issues -- get ENG-123
npm run linear-issues -- import-task --project-id <UUID> --identifier ENG-123

Details: skills/integration-linear/SKILL.md. Importing sets source=linear and external_id to Linear’s issue UUID.

Set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN (optional JIRA_PROJECT for default list JQL). Then:

npm run jira-issues -- smoke
npm run jira-issues -- list --max-results 10
npm run jira-issues -- get PROJ-123
npm run jira-issues -- import-task --project-id <UUID> --issue-key PROJ-123

Details: skills/integration-jira/SKILL.md. Importing sets source=jira and external_id to Jira’s numeric issue id.

Register the policy-aware MCP server (scripts/pmgo_mcp_server.py), connect channels, and schedule daily/weekly runs:

Generate gateway cron commands from cron/jobs.yaml:

npm run cron:config -- --runtime openclaw   # or hermes

Gateway (OpenClaw or Hermes — channels)
        │
        ▼
   pmgo Agent  ──► planner / tracker / risker / reporter
        │
        ▼
  Skills Pack (MCP stdio — shared)
   project-core · daily-standup · weekly-report · risk-radar
   integration-{github,linear,jira,notion,feishu,dingtalk}
        │
        ▼
   Memory: SQLite + Markdown   ◄── Cron / heartbeat

See docs/ROADMAP.md.

• Code, identifiers, commit messages, and inline comments: English only.
• README: English is canonical; README.zh-Hans.md and README.zh-Hant.md mirror it.
• User-facing strings (agent replies, report templates, error messages, UI labels) are loaded from locales/{en,zh-CN,zh-TW}.json and selected per-session based on the user's locale (fallback: en).
• Agent persona files: agent/*.md are English canonical; localised overlays live under agent/locales/{zh-CN,zh-TW}/*.md.
• Contributions: please write new strings in English first, then add translations for zh-CN and zh-TW in the same PR.

Contributions are welcome. A few ground rules:

1. Code, variable names, function names, file names, and commit messages are in English.
2. New user-facing strings must be added to all three locale files in the same PR.
3. Follow the allow-list policy in policy/pmgo.policy.yaml — never expand shell or delete permissions casually.

Before opening a PR, run the repository checks (agent i18n validation, memory asset and database verification, project-core list smoke, daily-standup / weekly-report / risk-radar smokes when a project exists, github-issues:smoke, linear-issues:smoke, and jira-issues:smoke when the respective API env vars are missing, and mcp:pmgo:check for OpenClaw MCP dependencies when pip install mcp pyyaml is available):

npm run validate

See CONTRIBUTING.md for the full workflow.

• Code of Conduct
• Contributing Guide
• Security Policy

Licensed under the Apache License, Version 2.0. See NOTICE for attribution requirements.