{"id":43902428,"url":"https://github.com/portel-dev/photon","last_synced_at":"2026-05-16T10:04:33.174Z","repository":{"id":322667780,"uuid":"1090423951","full_name":"portel-dev/photon","owner":"portel-dev","description":"Define intent once. Photon turns a single TypeScript file into CLI tools, MCP servers, and web interfaces.","archived":false,"fork":false,"pushed_at":"2026-05-11T00:28:29.000Z","size":18747,"stargazers_count":93,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-11T00:31:06.337Z","etag":null,"topics":["ai-tools","beam","claude-code","claude-desktop","cli-tool","cloudflare-workers","cursor","developer-tools","marketplace","mcp","mcp-servers","model-context-protocol","single-file","typescript"],"latest_commit_sha":null,"homepage":"","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/portel-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":null,"dco":null,"cla":null}},"created_at":"2025-11-05T16:42:44.000Z","updated_at":"2026-05-11T00:28:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"76738abb-b4df-4a5f-9c8d-3cfeb92456d0","html_url":"https://github.com/portel-dev/photon","commit_stats":null,"previous_names":["portel-dev/photon"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/portel-dev/photon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fphoton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fphoton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fphoton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fphoton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/portel-dev","download_url":"https://codeload.github.com/portel-dev/photon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portel-dev%2Fphoton/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32963174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"ssl_error","status_checked_at":"2026-05-12T23:30:18.191Z","response_time":102,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-tools","beam","claude-code","claude-desktop","cli-tool","cloudflare-workers","cursor","developer-tools","marketplace","mcp","mcp-servers","model-context-protocol","single-file","typescript"],"created_at":"2026-02-06T19:07:26.742Z","updated_at":"2026-05-16T10:04:33.167Z","avatar_url":"https://github.com/portel-dev.png","language":"TypeScript","funding_links":[],"categories":["Frameworks"],"sub_categories":["Common Lisp"],"readme":"\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-logo.png\" alt=\"Photon\" width=\"500\"\u003e\n\u003c/div\u003e\n\n[![npm version](https://img.shields.io/npm/v/@portel/photon?color=cb3837\u0026label=npm)](https://www.npmjs.com/package/@portel/photon)\n[![npm downloads](https://img.shields.io/npm/dm/@portel/photon?color=cb3837)](https://www.npmjs.com/package/@portel/photon)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/portel-dev/photon/blob/main/LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg)](https://www.typescriptlang.org)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-43853d.svg)](https://nodejs.org)\n[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)\n\n### Define intent once. Deliver everywhere.\n\nPhoton turns a single TypeScript file into:\n\n- **MCP server** for AI agents  \n- **CLI tool** for automation  \n- **Web interface** for humans\n\nPhoton is free and open source software released under the [MIT license](./LICENSE).\n\n*Interfaces are optional. Intent is mandatory.*\n\n---\n\n## One definition. Multiple interfaces.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png\" alt=\"Photon: one file, three surfaces\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n---\n\n### Example\n\n```typescript\n// hello.photon.ts\nexport default class Hello {\n  greet(name: string) {\n    return `Hello, ${name}!`;\n  }\n}\n```\n\nThat's a complete photon. From this single file you get:\n\n```\n$ photon cli hello greet --name Ada        # CLI\n$ photon                                    # Web UI at localhost:3008\n$ photon mcp hello                          # MCP server for Claude, Cursor, etc.\n```\n\nNo decorators. No registration. No server boilerplate.\nJust define the intent. Photon handles the rest.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png\" alt=\"One file, three interfaces\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n---\n\n## Why Photon Exists\n\nMost software is built around interfaces: web apps, CLI tools, APIs, and now MCP servers for AI agents. But the underlying logic is often the same.\n\nPhoton starts from a different place: capture the intent once in a TypeScript file and let the system expose it through multiple interfaces — CLI tools, web interfaces, and MCP servers.\n\nOne definition. Multiple surfaces.\n\n---\n\n### Quick Start\n\nFrom zero to an MCP server connected to Claude Desktop in three commands:\n\n```bash\nbun add -g @portel/photon\nphoton new my-tool                  # Scaffolds ./my-tool.photon.ts in your CWD\nphoton mcp install my-tool          # Registers it in Claude Desktop's config\n# Restart Claude Desktop. Your tool is live.\n```\n\nPrefer the web dashboard? Skip step 3 and run `photon` instead — it opens Beam, the auto-generated UI.\n\nOr try without installing globally:\n\n```bash\nbunx @portel/photon new my-tool\nbunx @portel/photon mcp install my-tool\n\n# pnpm users can use pnpm dlx instead:\npnpm dlx @portel/photon new my-tool\npnpm dlx @portel/photon mcp install my-tool\n```\n\n\u003e Requires [Node.js 20+](https://nodejs.org). TypeScript is compiled internally; no `tsconfig.json` needed.\n\u003e\n\u003e **Where do photon files live?** `./` (a project directory you cd into) or `~/.photon/` (global, auto-discovered). User settings persist under `~/.photon/state/\u003cphoton\u003e/`. See [Where things live](docs/getting-started.md#where-things-live).\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://www.youtube.com/watch?v=FI0M8s6ZKv4\"\u003e\n  \u003cimg src=\"https://img.youtube.com/vi/FI0M8s6ZKv4/maxresdefault.jpg\" alt=\"Watch: Why Photon? (2 min)\" width=\"100%\"\u003e\n\u003c/a\u003e\n\n\u003c/div\u003e\n\n---\n\n### How It Works\n\nYou write a TypeScript class. Methods are your capabilities. Types describe what's valid. Comments explain the intent. Photon reads all of it and generates three interfaces from one file. Same logic. Same validation. Same data.\n\n```\nanalytics.photon.ts  →  Web UI (Beam)  ·  CLI  ·  MCP Server for AI\n```\n\nThe more you express, the more Photon derives:\n\n| What you write | What Photon derives |\n|---|---|\n| Method signatures | Tool definitions: names, inputs, outputs |\n| Type annotations | Input validation rules, UI field types |\n| JSDoc comments | Documentation for AI clients and human users |\n| Constructor parameters | Config UI, environment variable mapping, runtime injection (`Photon`, `Cloudflare`, `CloudflareEnv`) |\n| `@tags` | Validation, formatting, scheduling, webhooks |\n\nWhen you add a `@param city {@pattern ^[a-zA-Z\\s]+$}` annotation, Beam validates it in the form, the CLI validates it before running, and the MCP schema enforces it for the AI. One annotation. Three consumers.\n\n### Three ways to author\n\n`extends Photon` is one shape. You can also inject `Photon` as a constructor parameter when you already extend something else, or compose without inheritance — same API either way. CF resources reach the photon through a separate `Cloudflare` injection so portable photons stay portable. See [docs/guides/PHOTON-INJECTION.md](docs/guides/PHOTON-INJECTION.md).\n\n---\n\n## Beam: Human Exploration\n\nBeam is the web dashboard. Every photon becomes an interactive form automatically. Run `photon`. That's the whole command.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png\" alt=\"Beam Dashboard\" width=\"100%\"\u003e\n\u003c/div\u003e\n\nThe UI is **fully auto-generated** from your method signatures: field types, validation, defaults, layouts. You never write frontend code. When you add a `{@choice a,b,c}` tag to a parameter, Beam renders a dropdown. When you mark a string as `{@format email}`, the field validates email format. The UI evolves as your code does.\n\nWhen forms aren't the right interface for what you're building, you can replace Beam's auto-generated view with your own HTML. A global named after your photon is auto-injected (e.g., `analytics.onResult(data =\u003e ...)`) — no framework required. `window.photon.url` is also injected and resolves to the Beam base URL so your HTML can construct fetch paths correctly whether running locally or behind a reverse proxy.\n\n\u003e Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./docs/guides/CUSTOM-UI.md).\n\nPhotons that declare `@get` or `@post` HTTP routes are shown in Beam as web apps. Routes support dynamic path segments (e.g. `@get /items/:id`) matched by specificity: literal segments win over parameters. Beam proxies requests to those routes and injects an `x-photon-base-path` header so the app can construct correct absolute paths regardless of where Beam is hosted.\n\n---\n\n## AI Agents: Machine Invocation\n\n```bash\nphoton info analytics --mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"analytics\": {\n      \"command\": \"photon\",\n      \"args\": [\"mcp\", \"analytics\"]\n    }\n  }\n}\n```\n\nPaste into your AI client's config. Your photon is now an MCP server. Claude can call your methods. Cursor can call your methods. Any MCP-compatible host can call your methods.\n\nThe AI sees the same thing a human sees in Beam: the method names, the parameter descriptions from your JSDoc, the validation rules from your types. The JSDoc comment you wrote to document the tool for yourself is what Claude reads to decide when and how to call it.\n\nThe MCP tools themselves work with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any MCP-compatible client.\n\nWhen your photon has a custom UI, clients that support the [MCP Apps Extension](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) render it natively, no separate app needed. The photon below is running inside Claude Desktop, same UI, same data as Beam.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/claude-desktop.png\" alt=\"Photon running as an MCP App with custom UI inside Claude Desktop\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n---\n\n## How a Photon Evolves\n\nHere is how a photon grows. Each step adds one thing and gets multiple capabilities from it.\n\n### Add comments: AI understands your intent\n\n```typescript\n/**\n * Weather - Check weather forecasts worldwide\n */\nexport default class Weather {\n  /**\n   * Get the weather forecast for a city\n   * @param city City name (e.g., \"London\")\n   */\n  async forecast(params: { city: string }) { ... }\n}\n```\n\nThe class description becomes how AI clients introduce the tool to users. The `@param` description is what the AI reads before deciding what value to pass. Same comments. Human help text and AI contract at once.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png\" alt=\"Step 2\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n### Declare configuration: a settings tool appears\n\n```typescript\nexport default class Weather {\n  /** User-tunable knobs. Photon auto-generates a `settings` tool from this. */\n  protected settings = {\n    /** Units for forecast values */\n    units: 'metric',\n    /** Polling interval in seconds */\n    pollIntervalSec: 300,\n  };\n\n  async forecast(params: { city: string }) {\n    const res = await fetch(`...?units=${this.settings.units}`);\n    return await res.json();\n  }\n}\n```\n\n`protected settings` is the canonical way to expose runtime knobs. Photon reads the JSDoc on each property, generates an MCP `settings` tool with typed inputs, and persists user changes to `~/.photon/state/\u003cphoton\u003e/\u003cinstance\u003e-settings.json`. Inside methods, `this.settings` is a read-only Proxy. To change a value, the user (or AI) calls the auto-generated `settings` tool.\n\nFor **secrets** that should never be persisted in a settings file (API keys, tokens), use a constructor parameter instead. Photon maps the parameter name to an env var:\n\n```typescript\nexport default class Weather {\n  constructor(private apiKey: string) {}  // → WEATHER_API_KEY\n}\n```\n\nThe constructor pattern is for primitives that come from `.env`. The `protected settings` pattern is for everything else, including any knob the user should be able to change at runtime without restarting. **When in doubt, reach for `settings`.**\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png\" alt=\"Step 3\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n### Add tags: behavior extends across all surfaces\n\n```typescript\n/**\n * @dependencies node-fetch@^3.0.0\n */\nexport default class Weather {\n  /**\n   * @param city City name {@example London} {@pattern ^[a-zA-Z\\s]+$}\n   * @param days Number of days {@min 1} {@max 7}\n   * @format table\n   */\n  async forecast(params: { city: string; days?: number }) { ... }\n}\n```\n\n`@dependencies` installs `node-fetch` automatically on first run, no manual package install needed. The `{@pattern}` validates in the form, the CLI, and the MCP schema simultaneously. `days` becomes a number spinner with bounds. `@format table` renders the result as a table in Beam. One annotation, three surfaces.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png\" alt=\"Step 4\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n### System CLI dependencies\n\nIf your photon wraps a command-line tool, declare it and Photon enforces it at load time:\n\n```typescript\n/**\n * @cli ffmpeg - https://ffmpeg.org/download.html\n */\nexport default class VideoProcessor {\n  async convert({ input, format }: { input: string; format: string }) {\n    // ffmpeg is guaranteed to exist when this runs\n  }\n}\n```\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png\" alt=\"Step 5\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n---\n\n## What Comes for Free\n\nThings you don't build because Photon handles them:\n\n| | |\n|---|---|\n| **Auto-UI** | Forms, field types, validation, layouts generated from your signatures |\n| **Stateful instances** | Multiple named instances of the same photon, each with isolated state |\n| **Persistent memory** | `this.memory` gives your photon per-instance key-value storage, no database needed |\n| **Scheduled execution** | `@scheduled` runs any method on a cron schedule |\n| **Webhooks** | `@webhook` exposes any method as an HTTP endpoint |\n| **OAuth (client)** | Built-in OAuth 2.0 flows for Google, GitHub, Microsoft |\n| **OAuth Authorization Server** | Issue tokens to MCP clients yourself: CIMD + DCR, PKCE, OIDC id_token, RFC 8693 token exchange |\n| **SQLite persistence** | Audit log, execution history, and OAuth grants survive daemon restart (bun:sqlite or better-sqlite3) |\n| **Daemon ops** | `photon ps` lists and controls scheduled jobs, webhooks, and live sessions |\n| **Distributed locks** | `@locked` serializes access: one caller at a time, across processes |\n| **Cross-photon calls** | `this.call()` invokes another photon's methods |\n| **Cloudflare runtime** | `this.cf.r2('blobs')`, `this.cf.d1('app')`, `this.cf.kv('cache')` — same shape locally (miniflare) and deployed (real bindings). See [CF-BINDINGS.md](docs/guides/CF-BINDINGS.md) |\n| **Real-time events** | `this.emit()` fires named events to the browser UI with zero wiring |\n| **Live rendering** | `this.render()` pushes formatted output to CLI and Beam in real time |\n| **Delegated LLM** | `this.sample()` asks the driving agent's model to generate text — no API key, agent pays |\n| **Inline confirm / input** | `this.confirm()` and `this.elicit()` route through the client's native UI (Beam dialog, Claude prompt) |\n| **Scoped remote access** | `photon claim` generates a short-lived code to scope a remote MCP session to one directory |\n| **Standalone binaries** | `photon build` compiles any photon to a single executable via Bun |\n| **Dependency management** | `@dependencies` auto-installs npm packages on first run |\n\n---\n\n## Coordination: Locks + Events\n\nTwo primitives. Together they unlock a class of things that are surprisingly hard to build today.\n\n**Locks** serialize access. When a method is marked `@locked`, only one caller can execute at a time, whether that caller is a human in Beam, a CLI script, or an AI agent. Everyone else waits their turn.\n\n**Events** push state changes to any browser UI in real time. `this.emit({ event: 'boardUpdated', data: board })` on the server becomes `chess.onBoardUpdated(handler)` in your custom UI — named after your photon file. No WebSockets to configure. No polling. Events are delivered via SSE through the MCP Streamable HTTP transport.\n\nTogether: **turn-based coordination with live state**.\n\n```typescript\nexport default class Chess {\n  /** Make a move. Locks ensure human and AI alternate turns. */\n  /** @locked */\n  async move(params: { from: string; to: string }) {\n    const result = await this.applyMove(params.from, params.to);\n\n    // Browser UI updates instantly, no polling needed\n    this.emit({ event: 'boardUpdated', data: result.board });\n    this.emit({ event: 'turnChanged', data: { next: result.nextPlayer } });\n\n    return result;\n  }\n}\n```\n\n```javascript\n// In your custom UI (ui/chess.html)\n// The global `chess` is auto-injected, named after your photon file\nchess.onBoardUpdated(board =\u003e renderBoard(board));\nchess.onTurnChanged(({ next }) =\u003e showTurn(next));\n\n// Call server methods directly\nchess.move({ from: 'e2', to: 'e4' });\n```\n\nA human moves through Beam. Claude is configured with the MCP server. The lock ensures they truly alternate. Events keep the board live on both sides. That's a fully functional turn-based chess game, human vs AI, in about 50 lines of application logic.\n\nThe same pattern applies beyond games: approval workflows where a human reviews before AI continues, collaborative tools where edits from any source appear instantly, simulations where steps must execute in strict sequence, any system where **who acts next matters**.\n\n---\n\n## MCP Primitives on `this`\n\nThe MCP protocol's user-facing primitives are surfaced as plain methods\non every photon instance — no decorators, no capability flags, no SDK\nimports. The runtime routes each call through whichever surface the\nrequest arrived on (Beam, Claude Desktop, Cursor, CLI).\n\n```typescript\nexport default class Editor {\n  async summarize(params: { text: string }) {\n    // Ask the driving agent's LLM. No API key. Agent pays.\n    return await this.sample({\n      prompt: `Summarize in one sentence:\\n\\n${params.text}`,\n      maxTokens: 128,\n    });\n  }\n\n  async deploy() {\n    if (!(await this.confirm('Ship to production?'))) return;\n    const env = await this.elicit\u003cstring\u003e({\n      ask: 'select',\n      message: 'Which environment?',\n      options: ['staging', 'prod'],\n    });\n    await this.run(env);\n  }\n}\n```\n\n| Primitive | What it does |\n|---|---|\n| `await this.sample({ prompt })` | Delegates LLM generation to the caller's model via MCP sampling |\n| `await this.confirm(question)` | Yes/no prompt — returns `boolean` |\n| `await this.elicit(params)` | Arbitrary input (text, select, form, file, etc.) |\n| `this.status(msg)` / `this.progress(v)` | Live feedback during long work; routes to SSE stream in Beam |\n| `this.roots` | MCP workspace roots declared by the connected client (`roots/list`) |\n| `this.notifyResourceUpdated(uri)` | Push `notifications/resources/updated` to subscribed clients |\n\nFull reference: [`docs/reference/MCP-PRIMITIVES.md`](docs/reference/MCP-PRIMITIVES.md).\n\n---\n\n## Remote Access: Claim Codes\n\nBy default every installed photon is visible to every connected MCP\nclient. When you want to pair a *remote* agent with a *subset* of your\nphotons — your phone driving Beam, a teammate reviewing one project,\na CI agent scoped to a single directory — generate a claim code:\n\n```bash\n$ photon claim --scope /workspace/proj --ttl 4h --label \"phone\"\n✓ Claim code: R3K-9QZ\n  Scope:      /workspace/proj\n  Expires in: 4h\n```\n\nThe remote client presents the code as the `Mcp-Claim-Code` header on\nits MCP session. `tools/list` then only exposes photons whose source\nlives under that directory. Sessions without a code keep full access —\nthe feature is strictly opt-in.\n\nFull reference: [`docs/reference/CLAIM-CODES.md`](docs/reference/CLAIM-CODES.md).\n\n---\n\n## Marketplace\n\n32 photons ready to install: databases, APIs, developer tools, and more.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png\" alt=\"Marketplace\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n```bash\nphoton search postgres\nphoton add postgres\n```\n\nYou can also install directly from any GitHub repository using qualified refs:\n\n```bash\nphoton add owner/repo/photon-name\n```\n\nBrowse the full catalog in the [official photons repository](https://github.com/portel-dev/photons). You can also host a private marketplace for your team: internal tools that stay off the public internet.\n\n---\n\n## Commands\n\n```bash\n# Run\nphoton                            # Open Beam UI\nphoton mcp \u003cname\u003e                 # Run as MCP server\nphoton mcp \u003cname\u003e --dev           # MCP server with hot reload\nphoton cli \u003cname\u003e [method]        # Run as CLI tool\n\n# Install from GitHub\nphoton beam owner/repo/name       # Install \u0026 open in Beam\nphoton cli owner/repo/name method # Install \u0026 run via CLI\n\n# Create\nphoton maker new \u003cname\u003e           # Scaffold a new photon\n\n# Build\nphoton build \u003cname\u003e               # Compile to standalone binary\nphoton build \u003cname\u003e --with-app    # Include Beam UI in binary\n\n# Manage\nphoton info                       # List all photons\nphoton info \u003cname\u003e --mcp          # Get MCP client config\nphoton maker validate \u003cname\u003e      # Check for errors\n\n# Marketplace\nphoton add \u003cname\u003e                 # Install photon\nphoton search \u003cquery\u003e             # Search marketplace\nphoton upgrade                    # Upgrade all\n\n# Ops\nphoton doctor                     # Diagnose environment\nphoton test                       # Run tests\nphoton ps                         # Observe \u0026 control scheduled jobs, webhooks, sessions\n```\n\n### `photon ps`: scheduled jobs, webhooks, and sessions\n\n`photon ps` is the operator surface for the daemon. Without arguments\nit prints a four-section snapshot — ACTIVE schedules, DECLARED-but-\nnot-enrolled, WEBHOOKS, and ACTIVE SESSIONS.\n\n```bash\nphoton ps                          # full snapshot\nphoton ps --json                   # structured output for scripts\nphoton ps --type active            # one section only\nphoton ps --base ~/Projects/kith   # filter to one PHOTON_DIR\n```\n\n**Two-step model.** A `@scheduled` annotation in source is **DECLARED**\nuntil enrolled. Enrollment is per-machine, persistent, and explicit:\n\n```bash\nphoton ps enable  newsletter:sendDigest    # DECLARED → ACTIVE\nphoton ps disable newsletter:sendDigest    # ACTIVE → suppressed (survives restart)\nphoton ps pause   newsletter:sendDigest    # stop firing without removing enrollment\nphoton ps resume  newsletter:sendDigest    # undo pause\nphoton ps history newsletter:sendDigest    # last 20 firings: timestamp, status, error\n```\n\nFor manual cron schedules without a `@scheduled` tag, use the Beam Pulse\npanel (\"Add schedule\") or call `this.schedule.create()` from photon code.\n\n`this.schedule.create()` (programmatic schedules) skips DECLARED and\ngoes straight to ACTIVE. See\n[`docs/GUIDE.md#scheduling`](docs/GUIDE.md#scheduling-scheduled-thisschedule-photon-ps)\nfor the full reference, the daemon state layout, and `.photon-no-host`\nfor multi-host setups.\n\n### Install from GitHub\n\nUse qualified refs to install and run photons directly from any GitHub repository:\n\n```bash\nphoton beam Arul-/photons/claw        # Install from GitHub, open in Beam\nphoton cli Arul-/photons/todo add     # Install from GitHub, run method\n```\n\nThe format is `owner/repo/photon-name`. Transitive `@photon` dependencies from the same repo are resolved automatically.\n\n### Compile to Binary\n\nBuild standalone executables from any photon — no Node.js required on the target machine:\n\n```bash\nphoton build my-tool                         # Binary for current platform\nphoton build my-tool -t bun-linux-x64        # Cross-compile for Linux\nphoton build my-tool --with-app              # Embed Beam UI as a desktop app\n```\n\nUses Bun's compiler under the hood. The binary bundles the photon, its `@dependencies`, and transitive `@photon` deps into a single file.\n\n---\n\n## Tag Reference\n\n| Tag | Where | What it does |\n|---|---|---|\n| `@dependencies` | Class | Auto-install npm packages on first run |\n| `@cli` | Class | Declare system CLI dependencies, checked at load time |\n| `@format` | Method | Result rendering (table, list, markdown, code, etc.) |\n| `@param ... {@choice a,b,c}` | Param | Dropdown selection in Beam |\n| `@param ... {@choice-from method}` | Param | Dynamic dropdown populated from another method's return value |\n| `@param ... {@format email}` | Param | Input validation and field type |\n| `@param ... {@min N} {@max N}` | Param | Numeric range constraints |\n| `@ui` | Class/Method | Link a custom HTML template |\n| `@expose` | Method | Auto-bind to `POST /api/\u003ckebab\u003e` for SPA fetch (`public` skips the SameSite gate) |\n| `@get /path` | Method | HTTP-only GET route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |\n| `@post /path` | Method | HTTP-only POST route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |\n| `@resource \u003curi\u003e` | Method | Dynamic MCP resource resolver (canonical form; replaces `@Static`) |\n| `@prompt` | Method | MCP prompt template (canonical form; replaces `@Template`) |\n| `@webhook` | Method | Expose as HTTP endpoint |\n| `@scheduled` | Method | Run on a cron schedule |\n| `@locked` | Method | Distributed lock across processes |\n| `@autorun` | Method | Auto-execute when selected in Beam |\n| `@mcp` | Class | Inject another MCP server as a dependency |\n| `@icon` | Class/Method | Set emoji icon |\n\n\u003e See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all 30+ tags with examples.\n\n---\n\n## Documentation\n\n**Start here:**\n\n| Guide | |\n|---|---|\n| [Getting Started](./docs/getting-started.md) | Install, build, and run your first photon in 5 minutes |\n| [Core Concepts](./docs/concepts.md) | The 6 ideas behind Photon |\n| [Output Formats](./docs/formats.md) | Visual gallery of every `@format` type |\n| [Intent Metadata](./docs/reference/INTENT-METADATA.md) | How comments, schemas, annotations, and formats map to native surfaces |\n| [Settings](./docs/GUIDE.md#settings-user-configurable-knobs) | Declare runtime knobs with `protected settings` (the canonical config pattern) |\n| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues and solutions |\n\n**Go deeper:**\n\n| Topic | |\n|---|---|\n| [Custom UI](./docs/guides/CUSTOM-UI.md) | Build rich interactive interfaces with the photon bridge API |\n| [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.0 with Google, GitHub, Microsoft |\n| [MCP Client Registration](./docs/guides/mcp-client-registration.md) | Register MCP clients with Photon's AS via CIMD or DCR |\n| [Observability](./docs/guides/observability.md) | OpenTelemetry traces, metrics, logs, and structured errors |\n| [Protocol Features](./docs/guides/PROTOCOL-FEATURES.md) | Capability handshake, structured errors, trace correlation |\n| [Daemon Pub/Sub](./docs/internals/DAEMON-PUBSUB.md) | Real-time cross-process messaging |\n| [Webhooks](./docs/reference/WEBHOOKS.md) | HTTP endpoints for external services |\n| [Locks](./docs/reference/LOCKS.md) | Distributed locks for exclusive access |\n| [Advanced Patterns](./docs/guides/ADVANCED.md) | Lifecycle hooks, dependency injection, interactive workflows |\n| [Marketplace Configuration](./docs/guides/MARKETPLACE-CONFIG.md) | Sharing settings across related photons in one marketplace |\n| [Deployment](./docs/guides/DEPLOYMENT.md) | Docker, Cloudflare Workers, AWS Lambda, Systemd |\n\n**Operate:**\n\n| Topic | |\n|---|---|\n| [Security](./SECURITY.md) | Best practices and audit checklist |\n| [Marketplace Publishing](./docs/guides/MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |\n| [Best Practices](./docs/guides/BEST-PRACTICES.md) | Patterns for production photons |\n\n**Reference:** [Complete Developer Guide](./docs/GUIDE.md) · [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) · [Naming Conventions](./docs/guides/NAMING-CONVENTIONS.md) · [Architecture](./docs/internals/ARCHITECTURE.md) · [OAuth Authorization Server](./docs/internals/OAUTH-AUTHORIZATION-SERVER.md) · [Lifecycle \u0026 Ingress](./docs/internals/LIFECYCLE-AND-INGRESS.md) · [PHOTON_DIR \u0026 Namespace](./docs/internals/PHOTON-DIR-AND-NAMESPACE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)\n\n---\n\n## Open Source\n\nPhoton is free and open source under the [MIT license](./LICENSE).\n\nThe project is still evolving and contributions are welcome.\n\n- Star the repository if the idea resonates\n- [Report issues](https://github.com/portel-dev/photon/issues)\n- [Contribute improvements or examples](./CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportel-dev%2Fphoton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fportel-dev%2Fphoton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportel-dev%2Fphoton/lists"}