{"id":51178198,"url":"https://github.com/hackerphysics/agent-phonon","last_synced_at":"2026-06-27T05:05:12.210Z","repository":{"id":367237566,"uuid":"1274079273","full_name":"hackerphysics/agent-phonon","owner":"hackerphysics","description":"Unified scheduler for local AI coding agents (Claude Code/Codex/OpenCode/OpenClaw/Hermes) with one protocol for remote task dispatch.","archived":false,"fork":false,"pushed_at":"2026-06-25T06:02:31.000Z","size":500,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T07:11:06.244Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/hackerphysics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"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}},"created_at":"2026-06-19T06:49:38.000Z","updated_at":"2026-06-25T06:02:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hackerphysics/agent-phonon","commit_stats":null,"previous_names":["hackerphysics/agent-phonon"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/hackerphysics/agent-phonon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerphysics%2Fagent-phonon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerphysics%2Fagent-phonon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerphysics%2Fagent-phonon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerphysics%2Fagent-phonon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hackerphysics","download_url":"https://codeload.github.com/hackerphysics/agent-phonon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerphysics%2Fagent-phonon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34842072,"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-27T02:00:06.362Z","response_time":126,"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":[],"created_at":"2026-06-27T05:05:11.487Z","updated_at":"2026-06-27T05:05:12.199Z","avatar_url":"https://github.com/hackerphysics.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-phonon\n\n[中文说明](./README.zh-CN.md)\n\n\u003e Orchestrate many agents as one — run them on your device, command them from anywhere.\n\n**agent-phonon** is a device-side daemon that discovers local AI coding agents\n(Claude Code, Codex, OpenCode, OpenClaw, Hermes, and more) and exposes them to a\nserver through one uniform WebSocket/JSON protocol.\n\nThe name comes from the **phonon** in condensed-matter physics: a collective\nquasiparticle that emerges when many atoms vibrate together. Individual agents\nact alone; orchestrated together they become one system. *More is different.*\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n\n---\n\n## What it does\n\nLocal AI agents are powerful but siloed. Each has a different CLI, session model,\nstreaming format, model switch mechanism, and set of capabilities. agent-phonon\nputs a small daemon in front of them so a server can:\n\n- discover which agents and models are available on a device,\n- create/send/interrupt/terminate sessions through one protocol,\n- stream output and receive unsolicited/proactive agent output,\n- manage projects, worktrees, skills, files, env vars, and HITL hooks,\n- orchestrate many devices while each device still enforces its own local policy.\n\nAdapters declare their real capabilities; agent-phonon does **not** pretend every\nagent works the same way.\n\n## Architecture\n\n```text\n        server(s)                          your device(s)\n   ┌────────────────┐   wire protocol   ┌────────────────────────────┐\n   │  server SDK    │◄─────WS / JSON────►│  phonon daemon (core)      │\n   │  (TS / Python) │                   │   ├─ adapter: OpenClaw      │\n   │  console / app │                   │   ├─ adapter: Claude Code   │\n   └────────────────┘                   │   ├─ adapter: Codex         │\n                                        │   ├─ adapter: OpenCode      │\n                                        │   └─ adapter: Hermes        │\n                                        └────────────────────────────┘\n```\n\n## Packages\n\n| Directory | Published package | For |\n|---|---|---|\n| `packages/daemon` | `agent-phonon` (npm) | Device daemon / CLI |\n| `packages/protocol` | `@agent-phonon/protocol` (npm) | Protocol types and zod schemas |\n| `packages/sdk-server-ts` | `@agent-phonon/server-sdk` (npm) | TypeScript/Node server SDK |\n| `sdk-python` | `agent-phonon-sdk` (PyPI) | Python server SDK |\n\n`@agent-phonon/core` is bundled into the daemon package and is not published as a\nseparate runtime dependency. Console/test/plugin packages are kept in the repo\nfor development and integration testing.\n\n## Requirements\n\n- Node.js \u003e= 22.5\n- npm or pnpm\n- Optional local agents:\n  - Claude Code: `claude`\n  - Codex CLI: `codex`\n  - OpenCode: `opencode`\n  - Hermes: `hermes`\n  - OpenClaw Gateway/plugin for OpenClaw integration\n\nLinux service management currently targets **systemd --user**. macOS launchd and\nWindows service support are planned separately.\n\n## Install the device daemon\n\n```bash\nnpm install -g agent-phonon\nagent-phonon --help\n```\n\nInitialize local config:\n\n```bash\nagent-phonon init\n```\n\nThe config file is created at:\n\n```text\n~/.agent-phonon/config.json\n```\n\nIt contains the device id, local database path, adapter overrides, server\nconnections, and local policy. Secrets are redacted by default when printed:\n\n```bash\nagent-phonon config\nagent-phonon config --show-secrets   # only when you really need it\n```\n\n## Configure a server connection\n\nIf your server gives you a WebSocket URL and device key:\n\n```bash\nagent-phonon server add wss://your-server.example/phonon --device-key \u003cdevice-key\u003e\n```\n\nFor local development only, you can mark a server as trusted-local:\n\n```bash\nagent-phonon server add ws://127.0.0.1:4317/phonon --trust-local\n```\n\nList configured servers:\n\n```bash\nagent-phonon server list\n```\n\n## Run as a Linux user service\n\nInstall the systemd user unit:\n\n```bash\nagent-phonon service install\n```\n\nStart it:\n\n```bash\nagent-phonon service start\n```\n\nUseful service commands:\n\n```bash\nagent-phonon service status\nagent-phonon service restart\nagent-phonon service stop\nagent-phonon service uninstall\n```\n\n`service install` writes:\n\n```text\n~/.config/systemd/user/agent-phonon.service\n```\n\nand runs:\n\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable agent-phonon.service\n```\n\nIt does not start the daemon until you explicitly run `service start`.\n\nIf the daemon should run after logout on a Linux server, you may need to enable\nlinger for your user:\n\n```bash\nloginctl enable-linger \"$USER\"\n```\n\n## Run in the foreground\n\nFor debugging or non-systemd environments:\n\n```bash\nagent-phonon start\n```\n\n## Discover local agents and models\n\nRun:\n\n```bash\nagent-phonon doctor\nagent-phonon discover\n```\n\n`doctor` checks whether local CLIs and integrations are available. `discover`\nreturns normalized agent descriptors, including available models and declared\ncapabilities.\n\nAdapter auto-detection is conservative:\n\n- CLI availability is checked by executing each CLI's version command.\n- Commands are resolved to absolute paths when possible, so systemd/launchd PATH\n  differences do not hide globally installed CLIs.\n- Codex models are discovered from the user's Codex config provider endpoint\n  (`GET \u003cbase_url\u003e/models`) when available, with safe fallback models.\n- Hermes models are discovered from Hermes profile/config/catalog information\n  with provider fallbacks when the catalog is incomplete.\n- No user-specific provider names, endpoints, or local machine paths are\n  hard-coded.\n\n## Adapter overrides\n\nMost users should rely on auto-detection. Add an adapter override only when you\nneed to force a path/model/provider:\n\n```bash\nagent-phonon adapter add codex --bin /path/to/codex --model default\nagent-phonon adapter add claude-code --bin /path/to/claude --model default\nagent-phonon adapter add hermes --bin /path/to/hermes\nagent-phonon adapter add opencode --bin /path/to/opencode\n```\n\nOpenClaw integration:\n\n```bash\nagent-phonon plugin install openclaw\nagent-phonon adapter add openclaw --agent main\n```\n\n## Server SDKs\n\n### TypeScript / Node\n\n```bash\nnpm install @agent-phonon/server-sdk\n```\n\n```ts\nimport { PhononServer } from \"@agent-phonon/server-sdk\";\n\nconst server = new PhononServer({ port: 4317 });\nserver.listen();\n```\n\n### Python\n\n```bash\npip install agent-phonon-sdk\n```\n\n```python\nfrom agent_phonon import PhononServer\n\nserver = PhononServer(port=4317)\nserver.run()\n```\n\n## Development\n\n```bash\npnpm install\npnpm run consistency\npnpm -r build\npnpm -r test\n```\n\nBefore committing or tagging releases, install the project git hook:\n\n```bash\npnpm run install-hooks\n```\n\nRelease guardrails live in:\n\n- `AGENTS.md`\n- `docs/COMMIT_RELEASE_CHECKLIST.md`\n- `scripts/check-consistency.mjs`\n- `scripts/release-guard.mjs`\n\n## Documentation\n\n- [Wire protocol](./docs/PROTOCOL.md)\n- [L3 orchestration protocol](./docs/L3_ORCHESTRATION.md)\n- [Design decisions](./docs/design.md)\n- [Agent CLI integration](./docs/agent-cli-integration.md)\n- [Release checklist](./docs/COMMIT_RELEASE_CHECKLIST.md)\n- [Security](./SECURITY.md)\n\n## Security model\n\nagent-phonon is a remote control plane for local agents. The local device owner\nis the authorization boundary. Filesystem access is policy-gated, secrets are\nredacted by default and encrypted at rest where stored by phonon, and dangerous\noperations are denied unless local policy explicitly allows them.\n\n## License\n\n[MIT](./LICENSE) © agent-phonon contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerphysics%2Fagent-phonon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackerphysics%2Fagent-phonon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerphysics%2Fagent-phonon/lists"}