{"id":50142129,"url":"https://github.com/pwrdrvr/pwragent","last_synced_at":"2026-07-07T23:00:35.971Z","repository":{"id":358375967,"uuid":"1212767451","full_name":"pwrdrvr/PwrAgent","owner":"pwrdrvr","description":"Desktop coding agent driven from Telegram, Discord, Slack, Mattermost, Feishu / Lark, or LINE. Codex-compatible — runs on your laptop, lives in your phone.","archived":false,"fork":false,"pushed_at":"2026-07-06T20:11:57.000Z","size":33778,"stargazers_count":28,"open_issues_count":40,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T21:12:58.285Z","etag":null,"topics":["agentic-engineering","ai-development","codex","discord","feishu","lark","mattermost","slack","telegram"],"latest_commit_sha":null,"homepage":"https://pwragent.ai","language":"TypeScript","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/pwrdrvr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"huntharo","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-04-16T17:59:07.000Z","updated_at":"2026-07-06T20:12:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pwrdrvr/PwrAgent","commit_stats":null,"previous_names":["pwrdrvr/pwragent"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/pwrdrvr/PwrAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdrvr%2FPwrAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdrvr%2FPwrAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdrvr%2FPwrAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdrvr%2FPwrAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwrdrvr","download_url":"https://codeload.github.com/pwrdrvr/PwrAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdrvr%2FPwrAgent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35245324,"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-07-07T02:00:07.222Z","response_time":90,"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":["agentic-engineering","ai-development","codex","discord","feishu","lark","mattermost","slack","telegram"],"created_at":"2026-05-24T02:03:03.260Z","updated_at":"2026-07-07T23:00:35.958Z","avatar_url":"https://github.com/pwrdrvr.png","language":"TypeScript","funding_links":["https://github.com/sponsors/huntharo"],"categories":[],"sub_categories":[],"readme":"# PwrAgent\n\n**Your coding agent runs on your laptop. You drive it from your phone.**\n\nAn open-source desktop coding agent. Pair it once with Telegram, Discord, Slack, Mattermost, Feishu / Lark, or LINE — then start, resume, steer, and approve from wherever you happen to be reading.\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/pwrdrvr/PwrAgent/releases/latest/download/PwrAgent.dmg\"\u003e\n    \u003cimg src=\"docs/assets/buttons/download-macos.png\" alt=\"Download for macOS\" width=\"440\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://docs.pwragent.ai\"\u003e\n    \u003cimg src=\"docs/assets/buttons/read-the-docs.png\" alt=\"Read the docs\" width=\"440\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n![PwrAgent desktop in use — Directories lens grouping threads across two repos, a thread mid-conversation, four messenger status icons in the title bar, per-thread model / access / fast-mode / worktree controls above the composer.](https://docs.pwragent.ai/assets/screenshots/desktop-hero.png)\n\n## Why you might want it\n\n- **Code keeps moving when you're away from the keyboard.** Approvals, follow-up prompts, \"what did you ship while I was at lunch\" check-ins — all from your phone. Cellular or hotel WiFi is fine; the agent is on your laptop, the messenger is just the steering wheel.\n- **Stack three asks and walk away.** `make a branch and PR for the OAuth refactor` → queue `/review main` → queue `squash and force-push`. The composer dispatches FIFO, one turn at a time. Come back: three things done.\n- **Isolated profiles for work and life.** As many PwrAgent windows as you want, each on its own profile, each bound to its own Codex identity. Auth and messaging credentials never cross.\n- **Works alongside Codex Desktop.** Shares thread state by default; start a thread in either, finish in the other. PwrAgent adds per-thread controls, worktree isolation with handoff, the Markdown composer, and the messaging surface — things Codex Desktop doesn't have today.\n- **No cloud, no account, no telemetry.** Everything runs on your machine. Bot tokens encrypted in the macOS Keychain. Closed-by-default messaging with two-keyed allowlists (see [Is this safe for work?](#is-this-safe-for-work)).\n- **Free, MIT, dogfooded.** The author uses PwrAgent as their primary coding environment. Hundreds of PRs in this repository and others were created or reviewed through it.\n\nThe longer-form pitch lives at **[pwragent.ai](https://pwragent.ai)**; the operator-facing setup walkthroughs live at **[docs.pwragent.ai](https://docs.pwragent.ai)**.\n\n## Take a look\n\n| | |\n|---|---|\n| ![Thread bound to a messenger](docs/assets/screenshots/screenshot-bound-thread.png) \u003cbr/\u003e*Bound thread — desktop and messenger stay in sync* | ![Messenger status surface](docs/assets/screenshots/screenshot-messenger-status.png) \u003cbr/\u003e*Messenger status at a glance* |\n| ![Pairing flow](docs/assets/screenshots/screenshot-pairing.gif) \u003cbr/\u003e*Paste-token pairing with in-app connection test* | ![Messaging activity with denied unauthorized users](docs/assets/screenshots/screenshot-closed-by-default.png) \u003cbr/\u003e*Closed by default — only allowlisted users can reach the bot* |\n\nScreenshots are produced by a Playwright spec that drives the real UI surfaces against deterministic replay fixtures, then shells out to a Swift script for native window capture (stoplights + drop-shadow + retina). See [`apps/desktop/AGENTS.md`](apps/desktop/AGENTS.md) → \"Capturing README Screenshots\" for regen.\n\n## Get it\n\n### Just want to use it\n\n1. **Download** [PwrAgent.dmg](https://github.com/pwrdrvr/PwrAgent/releases/latest/download/PwrAgent.dmg). Universal binary — runs natively on Apple Silicon (M1+) and Intel Macs. Developer ID-signed and Apple-notarized, so first launch is a single Gatekeeper prompt (no right-click-open dance).\n2. **Install** by opening the DMG and dragging PwrAgent into Applications.\n3. **(Optional) Pair a messenger** from **Settings → Messaging → \\\u003cyour platform\\\u003e**. End-to-end walkthroughs at **[docs.pwragent.ai/providers/](https://docs.pwragent.ai/providers/)**; the usage guide (bound threads, slash commands, queue/steer, monitor cards, detach) lives at **[docs.pwragent.ai/using-codex/](https://docs.pwragent.ai/using-codex/)**.\n\nConfig + state live under `~/.pwragent/profiles/\u003cname\u003e/` ([on-disk layout](docs/state-layout.md)). Multiple profiles via `--profile \u003cname\u003e` at launch.\n\n### Want to hack on it\n\n```bash\ngit clone https://github.com/pwrdrvr/PwrAgent.git\ncd PwrAgent\npnpm install\npnpm dev:no-messaging   # full UI, no live messaging adapters\n# or\npnpm dev                # full UI + live messaging\n```\n\nCodex App Server credentials live in `~/.config/grok-app-server/config.toml` or the equivalent env vars. Full dev workflow, test strategy, replay fixtures, and diagnostics in **[CONTRIBUTING.md](CONTRIBUTING.md)**.\n\n## How it's built\n\n| Layer | Stack | Where it lives |\n|---|---|---|\n| Desktop shell | Electron + TypeScript + React + TipTap composer | `apps/desktop/` |\n| Codex protocol | Codex App Server protocol contracts | `@pwrdrvr/codex-app-server-protocol` |\n| Agent core | Provider-agnostic coding-agent runtime (currently Grok / xAI) | `packages/agent-core/` |\n| Messaging interface | Capability-profile contract; one shape, six providers | `packages/messaging/interface/` |\n| Messaging providers | Telegram, Discord, Slack, Mattermost, Feishu / Lark, LINE | `packages/messaging/providers/*/` |\n| Shared types | Cross-package contracts and helpers | `packages/shared/` |\n| Local persistence | sqlite WAL via `better-sqlite3`, forward-compatible config TOML | `apps/desktop/src/main/state/`, `packages/agent-core/src/persistence/` |\n\nThe dependency graph is **strictly layered and enforced** by `dependency-cruiser`: leaf (`shared`) → mid-tier (`messaging/*`, `agent-core`) → top (`apps/desktop`). The renderer can only import `@pwragent/shared`; everything else crosses the IPC bridge. CI fails any boundary violation — see [`.dependency-cruiser.cjs`](.dependency-cruiser.cjs).\n\nArchitecture deep-dive: **[ARCHITECTURE.md](ARCHITECTURE.md)**.\n\n## Is this safe for work?\n\n**Research and comply with your company's policies before installing PwrAgent on a work machine or connecting it to a work messaging platform.** That responsibility is yours, not the project's.\n\nA sensible adoption path:\n\n- **Start on a personal project on a personally owned machine.** Run it locally without messaging enabled, or pair to a personal Telegram / Discord bot. Get a feel for what the agent does and what data it touches.\n- **Confirm policy before installing on a work machine.** Some employers disallow third-party developer tools by default; some allow them only after a security review.\n- **If you bind PwrAgent to a messaging platform at work, use only your employer's approved platform** (usually Slack or Mattermost) and walk the integration through your security team first. What ends up in your messenger from the agent matters as much as the agent itself.\n- **Don't mix work and personal.** Don't connect a work installation to a personal Telegram bot. Don't point a work Slack workspace at a personal experimentation install. Use [profiles](https://docs.pwragent.ai/desktop/#multiple-profiles) to keep them isolated.\n\n**Messaging is closed by default — and stays that way.** Only platform user IDs you've explicitly allowlisted can DM the bot. Inside shared spaces (Slack workspaces, Discord servers, Telegram supergroups), authorization is **two-keyed**: the space has to be on the allowlist *and* the user has to be on the allowlist. Inviting the bot into a workspace doesn't authorize anyone in it; being in an authorized workspace doesn't authorize a user. Unauthorized attempts are denied and surfaced in PwrAgent's messaging activity log, so you can see who tried and from where. Adding a new authorized user or space is a deliberate, opt-in change made from the desktop — never a side effect of someone discovering the bot.\n\nSecrets are encrypted at rest via Electron `safeStorage` (macOS Keychain backend). The entire state surface lives at `~/.pwragent/` ([documented layout](docs/state-layout.md)). The agent's permissions mode is set per thread (Default Access or Full Access — see the in-app description before changing it). What the project can't tell you is whether the policies at your employer permit any of this. That's still your call to make.\n\n## Roadmap\n\nmacOS-first today. Linux and Windows aren't supported yet. The honest list of what's still missing (thread forking, restoring archived threads, time-based auto-archiving, branch auto-naming) and what's actively in flight lives at **[docs.pwragent.ai/desktop/#not-yet](https://docs.pwragent.ai/desktop/#not-yet)**.\n\nThe desktop release pipeline (signing, notarization, auto-update) is documented in [docs/desktop-release-runbook.md](docs/desktop-release-runbook.md).\n\n## Background\n\nPwrAgent grew out of [openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server), a project that aimed to be the best Codex-into-Telegram-and-Discord integration. PwrAgent supersedes it: a desktop-first, thread-centric coding-agent shell with first-class messenger integration, and a generic messaging protocol that lets one workflow layer drive six providers from the same code path. That protocol is stable today and is a candidate to submit upstream to OpenClaw.\n\n## Going deeper\n\n| Doc | What it covers |\n|---|---|\n| **[pwragent.ai](https://pwragent.ai)** | Marketing landing — the WHY in 60 seconds. |\n| **[docs.pwragent.ai](https://docs.pwragent.ai)** | Operator reference — per-platform setup, the streaming-responses tradeoff, the webhook security note, settings reference. |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | Process model, storage layers, messaging layer summary, dependency boundaries, workspace map. |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Development workflow, testing, replay fixtures, diagnostics. |\n| [SECURITY.md](SECURITY.md) | How to report vulnerabilities. |\n| [docs/messaging-architecture.md](docs/messaging-architecture.md) | Layered messaging architecture, capability profiles, callback delivery models. |\n| [docs/messaging-adapter-contract.md](docs/messaging-adapter-contract.md) | Formal per-adapter contract for the messaging interface. |\n| [docs/messaging-adding-a-provider.md](docs/messaging-adding-a-provider.md) | Hands-on walkthrough when adding a seventh provider. |\n| [docs/state-layout.md](docs/state-layout.md) | On-disk state layout, environment variables, profiles. |\n| [docs/config-file-evolution.md](docs/config-file-evolution.md) | Forward-compatible config migration rules. |\n\n## License\n\nPwrAgent is licensed under the [MIT License](LICENSE). Third-party dependency notices are aggregated in [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES) and shipped with desktop distributions. See [docs/third-party-license-notices.md](docs/third-party-license-notices.md) for the Electron / Chromium runtime notice policy.\n\nCreated by [PwrDrvr LLC](https://pwrdrvr.com). Follow [@PwrAgentAI](https://x.com/PwrAgentAI) for releases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwrdrvr%2Fpwragent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwrdrvr%2Fpwragent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwrdrvr%2Fpwragent/lists"}