Skip to content
Back to search

photon

Define intent once. Photon turns a single TypeScript file into CLI tools, MCP servers, and web interfaces.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/portel-dev--photon/badge.svg)](/listings/portel-dev--photon)

HTML

<a href="/listings/portel-dev--photon"><img src="/api/listings/portel-dev--photon/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From zero to an MCP server connected to Claude Desktop in three commands:

bun add -g @portel/photon
photon new my-tool                  # Scaffolds ./my-tool.photon.ts in your CWD
photon mcp install my-tool          # Registers it in Claude Desktop's config
# Restart Claude Desktop. Your tool is live.

Prefer the web dashboard? Skip step 3 and run `photon` instead — it opens Beam, the auto-generated UI.

Or try without installing globally:

bunx @portel/photon new my-tool
bunx @portel/photon mcp install my-tool

# pnpm users can use pnpm dlx instead:
pnpm dlx @portel/photon new my-tool
pnpm dlx @portel/photon mcp install my-tool

> Requires [Node.js 20+](https://nodejs.org). TypeScript is compiled internally; no `tsconfig.json` needed. > > **Where do photon files live?** `./` (a project directory you cd into) or `~/.photon/` (global, auto-discovered). User settings persist under `~/.photon/state/<photon>/`. See [Where things live](docs/getting-started.md#where-things-live).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 714 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-logo.png" alt="Photon" width="500">
  3. </div>
  4. [![npm version](https://img.shields.io/npm/v/@portel/photon?color=cb3837&label=npm)](https://www.npmjs.com/package/@portel/photon)
  5. [![npm downloads](https://img.shields.io/npm/dm/@portel/photon?color=cb3837)](https://www.npmjs.com/package/@portel/photon)
  6. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/portel-dev/photon/blob/main/LICENSE)
  7. [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg)](https://www.typescriptlang.org)
  8. [![Node](https://img.shields.io/badge/node-%3E%3D20-43853d.svg)](https://nodejs.org)
  9. [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
  10. [![Docs](https://img.shields.io/badge/docs-photon-blue)](https://photon.portel.dev/)
  11. ### One TypeScript capability becomes the whole agent stack.
  12. Photon is the fastest way to turn a small, verified TypeScript method into
  13. something humans can operate and agents can trust. Write the capability once;
  14. Photon derives the interfaces, contracts, and runtime behavior around it:
  15. - **MCP server** for Claude, ChatGPT, Cursor, and agents
  16. - **Embedded app UI** for chat clients that support MCP app resources
  17. - **CLI tool** for scripts, demos, and automation
  18. - **Beam web interface** for humans
  19. - **Web routes, schedules, webhooks, retries, state, and audit history** when the
  20. capability grows into a production workflow
  21. Photon is free and open source software released under the [MIT license](./LICENSE).
  22. Full documentation lives at [photon.portel.dev](https://photon.portel.dev/).
  23. Related Portel project: [NCP](https://portel-dev.github.io/ncp/) gives agents
  24. one natural MCP interface to discover and run tools across a whole tool
  25. ecosystem. Photon builds reliable agent-facing capabilities; NCP helps agents
  26. find and use them alongside every other MCP.
  27. **Try it in two minutes:**
  28. ```bash
  29. bun add -g @portel/photon
  30. photon new my-tool
  31. photon
  32. ```
  33. That opens Beam, the generated human UI. Add `photon mcp install my-tool` when
  34. you want the same capability inside Claude Desktop or another MCP client.
  35. *Interfaces are optional. Intent is mandatory.*
  36. ```bash
  37. gh repo star portel-dev/photon
  38. ```
  39. ---
  40. ## From one method to every surface
  41. The weather example is intentionally small: one TypeScript method, a few
  42. docblock tags, and one `@ui` HTML asset. Photon turns that into a CLI command,
  43. Beam UI, MCP tool, and embedded app surface for MCP app-capable chat clients.
  44. Claude Desktop can run it from a local stdio MCP command; ChatGPT developer
  45. mode can connect to the same Photon over a public HTTPS `/mcp` endpoint.
  46. <div align="center">
  47. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/photon-surface-map.svg" alt="Infographic showing one Photon method becoming CLI, Beam, MCP, Claude Desktop, ChatGPT, and other agent surfaces" width="100%">
  48. </div>
  49. Real clients, same Photon:
  50. <table>
  51. <tr>
  52. <td width="50%" align="center" valign="top">
  53. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/chatgpt-photon-weather-local-dot.png" alt="Real ChatGPT developer-mode session rendering the Photon weather app from a public HTTPS MCP endpoint">
  54. <br><sub>ChatGPT developer mode rendering the Photon weather UI from a public HTTPS <code>/mcp</code> endpoint.</sub>
  55. </td>
  56. <td width="50%" align="center" valign="top">
  57. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/claude-weather-real.png" alt="Real Claude Desktop session rendering the Photon weather app through local MCP">
  58. <br><sub>Claude Desktop rendering the same Photon through local MCP.</sub>
  59. </td>
  60. </tr>
  61. </table>
  62. [Follow the step-by-step tutorial](./docs/tutorials/from-method-to-chat-app.md)
  63. or open the runnable example in
  64. [`examples/weather-showcase`](./examples/weather-showcase).
  65. The tutorial also includes Beam, CLI, and a concept animation for the full
  66. transformation.
  67. ---
  68. ## The Photon Promise
  69. Photon is the modern dev stack for the agentic age: each photon is a small,
  70. auditable brick that can be used by humans, agents, schedulers, webhooks, and
  71. apps without rewriting the same capability for every interface.
  72. <div align="center">
  73. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-agentic-stack.png" alt="Photon agentic stack infographic showing one intent becoming MCP contracts, human surfaces, apps, operations, trust boundaries, and composable systems" width="100%">
  74. </div>
  75. That is the core idea: **tiny trusted capabilities compose into larger
  76. systems**. A photon can start as a helper method, become a CLI command, render
  77. as an app, run on a schedule, accept webhooks, and still expose a clean
  78. agent-readable contract.
  79. ---
  80. ### Example
  81. ```typescript
  82. // hello.photon.ts
  83. export default class Hello {
  84. greet(name: string) {
  85. return `Hello, ${name}!`;
  86. }
  87. }
  88. ```
  89. That's a complete photon. From this single file you get:
  90. ```
  91. $ photon cli hello greet --name Ada # CLI
  92. $ photon # Web UI at localhost:3008
  93. $ photon mcp hello # MCP server for Claude, Cursor, etc.
  94. ```
  95. No decorators. No registration. No server boilerplate.
  96. Just define the intent. Photon handles the rest.
  97. ---
  98. ### Quick Start
  99. From zero to an MCP server connected to Claude Desktop in three commands:
  100. ```bash
  101. bun add -g @portel/photon
  102. photon new my-tool # Scaffolds ./my-tool.photon.ts in your CWD
  103. photon mcp install my-tool # Registers it in Claude Desktop's config
  104. # Restart Claude Desktop. Your tool is live.
  105. ```
  106. Prefer the web dashboard? Skip step 3 and run `photon` instead — it opens Beam, the auto-generated UI.
  107. Or try without installing globally:
  108. ```bash
  109. bunx @portel/photon new my-tool
  110. bunx @portel/photon mcp install my-tool
  111. # pnpm users can use pnpm dlx instead:
  112. pnpm dlx @portel/photon new my-tool
  113. pnpm dlx @portel/photon mcp install my-tool
  114. ```
  115. > Requires [Node.js 20+](https://nodejs.org). TypeScript is compiled internally; no `tsconfig.json` needed.
  116. >
  117. > **Where do photon files live?** `./` (a project directory you cd into) or `~/.photon/` (global, auto-discovered). User settings persist under `~/.photon/state/<photon>/`. See [Where things live](docs/getting-started.md#where-things-live).
  118. ### How It Works
  119. You 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.
  120. <div align="center">
  121. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-core-concepts.svg" alt="Six Photon core concepts: methods, comments, types and tags, settings, UI and routes, and operations" width="100%">
  122. </div>
  123. ```
  124. analytics.photon.ts → Beam · Web app · Webhook · WebSocket · CLI · MCP
  125. ```
  126. The more you express, the more Photon derives:
  127. | What you write | What Photon derives |
  128. |---|---|
  129. | Method signatures | Tool definitions: names, inputs, outputs |
  130. | Type annotations | Input validation rules, UI field types |
  131. | JSDoc comments | Documentation for AI clients and human users |
  132. | Constructor parameters | Config UI, environment variable mapping, runtime injection (`Photon`, `Cloudflare`, `CloudflareEnv`) |
  133. | `@tags` | Validation, formatting, scheduling, webhooks, and HTTP routes |
  134. When 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.
  135. ### Three ways to author
  136. `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).
  137. ---
  138. ## Reuse a Photon in application code
  139. Existing Photons can also be application dependencies. Load their source through
  140. the public API and call methods from your own Node code:
  141. ```typescript
  142. import { createPhotonRuntime } from '@portel/photon';
  143. const runtime = createPhotonRuntime();
  144. try {
  145. const todo = await runtime.photon<{
  146. add(text: string): Promise<unknown>;
  147. }>('./todo.photon.ts', { baseDir: '/srv/my-app/photons' });
  148. await todo.add('Review the release');
  149. } finally {
  150. await runtime.close();
  151. }
  152. ```
  153. This manages initialization and shutdown without starting a server. It executes
  154. trusted code in your application process; the host owns authorization. The object
  155. is separate from a live Beam/daemon instance. Use MCP when your application needs
  156. to operate on that same live instance. For source resolution, persistence, and
  157. constructor-dependency lifecycle limits, see [Photon as a library](docs/internals/PHOTON-AS-LIBRARY.md).
  158. ---
  159. ## Beam: Human Exploration
  160. [Run the shared task-board walkthrough](docs/tutorials/human-agent-task-board.md) to see a human and an MCP client operate the same state.
  161. Beam is the web dashboard. Every photon becomes an interactive form automatically. Run `photon`. That's the whole command.
  162. <div align="center">
  163. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="100%">
  164. </div>
  165. The 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.
  166. When 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 => ...)`) — 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.
  167. > Custom UIs follow the [official MCP Apps Extension](https://modelcontextprotocol.io/extensions/apps/overview) and work across compatible hosts. See the [Custom UI Guide](./docs/guides/CUSTOM-UI.md).
  168. Photons that declare HTTP routes with `@get`, `@post`, `@put`, `@patch`, or `@delete` 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. Web apps and WebSockets are Photon application targets; MCP Apps are a separate official MCP extension for embedded UI resources.
  169. ---
  170. ## AI Agents: Machine Invocation
  171. Photon ships separate, tested MCP adapters: sessionful MCP 2025 over stdio and
  172. Streamable HTTP, plus stateless MCP `2026-07-28` release-candidate support over
  173. Streamable HTTP. See the
  174. [compatibility matrix and runnable clients](./docs/guides/MCP-COMPATIBILITY.md),
  175. or run `photon doctor mcp` against your installed runtime.
  176. ```bash
  177. photon info analytics --mcp
  178. ```
  179. ```json
  180. {
  181. "mcpServers": {
  182. "analytics": {
  183. "command": "photon",
  184. "args": ["mcp", "analytics"]
  185. }
  186. }
  187. }
  188. ```
  189. Paste 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.
  190. The 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.
  191. The 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. When your photon has a custom UI, clients that support the [MCP Apps Extension](https://modelcontextprotocol.io/extensions/apps/overview) can render it natively, as shown in the weather proof above.
  192. ---
  193. ## How a Photon Evolves
  194. Here is how a photon grows. Each step adds one thing and gets multiple capabilities from it.
  195. ### Add comments: AI understands your intent
  196. ```typescript
  197. /**
  198. * Weather - Check weather forecasts worldwide
  199. */
  200. export default class Weather {
  201. /**
  202. * Get the weather forecast for a city
  203. * @param city City name (e.g., "London")
  204. */
  205. async forecast(params: { city: string }) { ... }
  206. }
  207. ```
  208. The 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.
  209. <div align="center">
  210. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2" width="100%">
  211. </div>
  212. ### Declare configuration: a settings tool appears
  213. ```typescript
  214. export default class Weather {
  215. /** User-tunable knobs. Photon auto-generates a `settings` tool from this. */
  216. protected settings = {
  217. /** Units for forecast values */
  218. units: 'metric',
  219. /** Polling interval in seconds */
  220. pollIntervalSec: 300,
  221. };
  222. async forecast(params: { city: string }) {
  223. const res = await fetch(`...?units=${this.settings.units}`);
  224. return await res.json();
  225. }
  226. }
  227. ```
  228. `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/<photon>/<instance>-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.
  229. For **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:
  230. ```typescript
  231. export default class Weather {
  232. constructor(private apiKey: string) {} // → WEATHER_API_KEY
  233. }
  234. ```
  235. The 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`.**
  236. <div align="center">
  237. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3" width="100%">
  238. </div>
  239. ### Add tags: behavior extends across all surfaces
  240. ```typescript
  241. /**
  242. * @dependencies node-fetch@^3.0.0
  243. */
  244. export default class Weather {
  245. /**
  246. * @param city City name {@example London} {@pattern ^[a-zA-Z\s]+$}
  247. * @param days Number of days {@min 1} {@max 7}
  248. * @format table
  249. */
  250. async forecast(params: { city: string; days?: number }) { ... }
  251. }
  252. ```
  253. `@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.
  254. <div align="center">
  255. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4" width="100%">
  256. </div>
  257. ### System CLI dependencies
  258. If your photon wraps a command-line tool, declare it and Photon enforces it at load time:
  259. ```typescript
  260. /**
  261. * @cli ffmpeg - https://ffmpeg.org/download.html
  262. */
  263. export default class VideoProcessor {
  264. async convert({ input, format }: { input: string; format: string }) {
  265. // ffmpeg is guaranteed to exist when this runs
  266. }
  267. }
  268. ```
  269. <div align="center">
  270. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5" width="100%">
  271. </div>
  272. ---
  273. ## What Comes for Free
  274. Things you don't build because Photon handles them:
  275. | | |
  276. |---|---|
  277. | **Auto-UI** | Forms, field types, validation, layouts generated from your signatures |
  278. | **Stateful instances** | Multiple named instances of the same photon, each with isolated state |
  279. | **Persistent memory** | `this.memory` gives your photon per-instance key-value storage, no database needed |
  280. | **Scheduled execution** | `@scheduled` runs any method on a cron schedule |
  281. | **Webhooks** | `@webhook` exposes any method as an HTTP endpoint |
  282. | **OAuth (client)** | Built-in OAuth 2.0 flows for Google, GitHub, Microsoft |
  283. | **OAuth Authorization Server** | Issue tokens to MCP clients yourself: CIMD + DCR, PKCE, OIDC id_token, RFC 8693 token exchange |
  284. | **SQLite persistence** | Audit log, execution history, and OAuth grants survive daemon restart (bun:sqlite or better-sqlite3) |
  285. | **Daemon ops** | `photon ps` lists and controls scheduled jobs, webhooks, and live sessions |
  286. | **Distributed locks** | `@locked` serializes access: one caller at a time, across processes |
  287. | **Cross-photon calls** | `this.call()` invokes another photon's methods |
  288. | **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) |
  289. | **Real-time events** | `this.emit()` fires named events to the browser UI with zero wiring |
  290. | **Live rendering** | `this.render()` pushes formatted output to CLI and Beam in real time |
  291. | **Delegated LLM** | `this.sample()` asks the driving agent's model to generate text — no API key, agent pays |
  292. | **Inline confirm / input** | `this.confirm()` and `this.elicit()` route through the client's native UI (Beam dialog, Claude prompt) |
  293. | **Scoped remote access** | `photon claim` generates a short-lived code to scope a remote MCP session to one directory |
  294. | **Standalone binaries** | `photon build` compiles any photon to a single executable via Bun |
  295. | **Dependency management** | `@dependencies` auto-installs npm packages on first run |
  296. ---
  297. ## Coordination: Locks + Events
  298. Two primitives. Together they unlock a class of things that are surprisingly hard to build today.
  299. **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.
  300. **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.
  301. Together: **turn-based coordination with live state**.
  302. ```typescript
  303. export default class Chess {
  304. /** Make a move. Locks ensure human and AI alternate turns. */
  305. /** @locked */
  306. async move(params: { from: string; to: string }) {
  307. const result = await this.applyMove(params.from, params.to);
  308. // Browser UI updates instantly, no polling needed
  309. this.emit({ event: 'boardUpdated', data: result.board });
  310. this.emit({ event: 'turnChanged', data: { next: result.nextPlayer } });
  311. return result;
  312. }
  313. }
  314. ```
  315. ```javascript
  316. // In your custom UI (ui/chess.html)
  317. // The global `chess` is auto-injected, named after your photon file
  318. chess.onBoardUpdated(board => renderBoard(board));
  319. chess.onTurnChanged(({ next }) => showTurn(next));
  320. // Call server methods directly
  321. chess.move({ from: 'e2', to: 'e4' });
  322. ```
  323. A 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.
  324. The 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**.
  325. ---
  326. ## MCP Primitives on `this`
  327. The MCP protocol's user-facing primitives are surfaced as plain methods
  328. on every photon instance — no decorators, no capability flags, no SDK
  329. imports. The runtime routes each call through whichever surface the
  330. request arrived on (Beam, Claude Desktop, Cursor, CLI).
  331. ```typescript
  332. export default class Editor {
  333. async summarize(params: { text: string }) {
  334. // Ask the driving agent's LLM. No API key. Agent pays.
  335. return await this.sample({
  336. prompt: `Summarize in one sentence:\n\n${params.text}`,
  337. maxTokens: 128,
  338. });
  339. }
  340. async deploy() {
  341. if (!(await this.confirm('Ship to production?'))) return;
  342. const env = await this.elicit<string>({
  343. ask: 'select',
  344. message: 'Which environment?',
  345. options: ['staging', 'prod'],
  346. });
  347. await this.run(env);
  348. }
  349. }
  350. ```
  351. | Primitive | What it does |
  352. |---|---|
  353. | `await this.sample({ prompt })` | Delegates LLM generation to the caller's model via MCP sampling |
  354. | `await this.confirm(question)` | Yes/no prompt — returns `boolean` |
  355. | `await this.elicit(params)` | Arbitrary input (text, select, form, file, etc.) |
  356. | `this.status(msg)` / `this.progress(v)` | Live feedback during long work; routes to SSE stream in Beam |
  357. | `this.roots` | MCP workspace roots declared by the connected client (`roots/list`) |
  358. | `this.notifyResourceUpdated(uri)` | Push `notifications/resources/updated` to subscribed clients |
  359. Full reference: [`docs/reference/MCP-PRIMITIVES.md`](docs/reference/MCP-PRIMITIVES.md).
  360. ---
  361. ## Remote Access: Claim Codes
  362. By default every installed photon is visible to every connected MCP
  363. client. When you want to pair a *remote* agent with a *subset* of your
  364. photons — your phone driving Beam, a teammate reviewing one project,
  365. a CI agent scoped to a single directory — generate a claim code:
  366. ```bash
  367. $ photon claim --scope /workspace/proj --ttl 4h --label "phone"
  368. ✓ Claim code: R3K-9QZ
  369. Scope: /workspace/proj
  370. Expires in: 4h
  371. ```
  372. The remote client presents the code as the `Mcp-Claim-Code` header on
  373. its MCP session. `tools/list` then only exposes photons whose source
  374. lives under that directory. Sessions without a code keep full access —
  375. the feature is strictly opt-in.
  376. Full reference: [`docs/reference/CLAIM-CODES.md`](docs/reference/CLAIM-CODES.md).
  377. ---
  378. ## Marketplace
  379. A curated set of photons is ready to install. The public gallery is now kept
  380. small on purpose: polished apps and tools in one place, teaching examples in
  381. another.
  382. <div align="center">
  383. <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="100%">
  384. </div>
  385. ```bash
  386. photon search boards
  387. photon add boards
  388. ```
  389. You can also install directly from any GitHub repository using qualified refs:
  390. ```bash
  391. photon add owner/repo/photon-name
  392. ```
  393. Browse the [Photon Apps marketplace](https://github.com/portel-dev/photons)
  394. for ready-to-use photons, or the
  395. [Photon Examples marketplace](https://github.com/portel-dev/photon-examples)
  396. for focused learning examples. You can also host a private marketplace for your
  397. team: internal tools that stay off the public internet.
  398. ---
  399. ## Commands
  400. ```bash
  401. # Run
  402. photon # Open Beam UI
  403. photon mcp <name> # Run as MCP server
  404. photon mcp <name> --dev # MCP server with hot reload
  405. photon cli <name> [method] # Run as CLI tool
  406. # Install from GitHub
  407. photon beam owner/repo/name # Install & open in Beam
  408. photon cli owner/repo/name method # Install & run via CLI
  409. # Create
  410. photon maker new <name> # Scaffold a new photon
  411. # Build
  412. photon build <name> # Compile to standalone binary
  413. photon build <name> --with-app # Include Beam UI in binary
  414. # Manage
  415. photon info # List all photons
  416. photon info <name> --mcp # Get MCP client config
  417. photon maker validate <name> # Check for errors
  418. # Marketplace
  419. photon add <name> # Install photon
  420. photon search <query> # Search marketplace
  421. photon upgrade # Upgrade all
  422. # Ops
  423. photon doctor # Diagnose environment
  424. photon test # Run tests
  425. photon ps # Observe & control scheduled jobs, webhooks, sessions
  426. ```
  427. ### `photon ps`: scheduled jobs, webhooks, and sessions
  428. `photon ps` is the operator surface for the daemon. Without arguments
  429. it prints a four-section snapshot — ACTIVE schedules, DECLARED-but-
  430. not-enrolled, WEBHOOKS, and ACTIVE SESSIONS.
  431. ```bash
  432. photon ps # full snapshot
  433. photon ps --json # structured output for scripts
  434. photon ps --type active # one section only
  435. photon ps --base ~/Projects/kith # filter to one PHOTON_DIR
  436. ```
  437. **Two-step model.** A `@scheduled` annotation in source is **DECLARED**
  438. until enrolled. Enrollment is per-machine, persistent, and explicit:
  439. ```bash
  440. photon ps enable newsletter:sendDigest # DECLARED → ACTIVE
  441. photon ps disable newsletter:sendDigest # ACTIVE → suppressed (survives restart)
  442. photon ps pause newsletter:sendDigest # stop firing without removing enrollment
  443. photon ps resume newsletter:sendDigest # undo pause
  444. photon ps history newsletter:sendDigest # last 20 firings: timestamp, status, error
  445. ```
  446. For manual cron schedules without a `@scheduled` tag, use the Beam Pulse
  447. panel ("Add schedule") or call `this.schedule.create()` from photon code.
  448. `this.schedule.create()` (programmatic schedules) skips DECLARED and
  449. goes straight to ACTIVE. See
  450. [`docs/GUIDE.md#scheduling`](docs/GUIDE.md#scheduling-scheduled-thisschedule-photon-ps)
  451. for the full reference, the daemon state layout, and `.photon-no-host`
  452. for multi-host setups.
  453. ### Install from GitHub
  454. Use qualified refs to install and run photons directly from any GitHub repository:
  455. ```bash
  456. photon beam Arul-/photons/claw # Install from GitHub, open in Beam
  457. photon cli Arul-/photons/todo add # Install from GitHub, run method
  458. ```
  459. The format is `owner/repo/photon-name`. Transitive `@photon` dependencies from the same repo are resolved automatically.
  460. ### Compile to Binary
  461. Build standalone executables from any photon — no Node.js required on the target machine:
  462. ```bash
  463. photon build my-tool # Binary for current platform
  464. photon build my-tool -t bun-linux-x64 # Cross-compile for Linux
  465. photon build my-tool --with-app # Embed Beam UI as a desktop app
  466. ```
  467. Uses Bun's compiler under the hood. The binary bundles the photon, its `@dependencies`, and transitive `@photon` deps into a single file.
  468. ---
  469. ## Tag Reference
  470. | Tag | Where | What it does |
  471. |---|---|---|
  472. | `@dependencies` | Class | Auto-install npm packages on first run |
  473. | `@cli` | Class | Declare system CLI dependencies, checked at load time |
  474. | `@format` | Method | Result rendering (table, list, markdown, code, etc.) |
  475. | `@param ... {@choice a,b,c}` | Param | Dropdown selection in Beam |
  476. | `@param ... {@choice-from method}` | Param | Dynamic dropdown populated from another method's return value |
  477. | `@param ... {@format email}` | Param | Input validation and field type |
  478. | `@param ... {@min N} {@max N}` | Param | Numeric range constraints |
  479. | `@ui` | Class/Method | Link a custom HTML template |
  480. | `@auth` | Class | Require or describe MCP authentication, including passwordless methods such as `@auth email passkey`, and populate `this.caller` |
  481. | `@scope` | Method | Override the inferred OAuth scope for a protected MCP tool call |
  482. | `@expose` | Method | Auto-bind to `POST /api/<kebab>` for SPA fetch (`public` skips the SameSite gate) |
  483. | `@get /path` | Method | HTTP-only GET route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |
  484. | `@post /path` | Method | HTTP-only POST route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |
  485. | `@put /path` | Method | HTTP-only PUT route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |
  486. | `@patch /path` | Method | HTTP-only PATCH route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |
  487. | `@delete /path` | Method | HTTP-only DELETE route; shown as a web app in Beam, not an MCP tool. Supports `:param` segments |
  488. | `@resource <uri>` | Method | Dynamic MCP resource resolver (canonical form; replaces `@Static`) |
  489. | `@prompt` | Method | MCP prompt template (canonical form; replaces `@Template`) |
  490. | `@webhook` | Method | Expose as HTTP endpoint |
  491. | `@scheduled` | Method | Run on a cron schedule |
  492. | `@locked` | Method | Distributed lock across processes |
  493. | `@autorun` | Method | Auto-execute when selected in Beam |
  494. | `@mcp` | Class | Inject another MCP server as a dependency |
  495. | `@icon` | Class/Method | Set emoji icon |
  496. > See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all 30+ tags with examples.
  497. ---
  498. ## Documentation
  499. **Start here:**
  500. | Guide | |
  501. |---|---|
  502. | [Getting Started](./docs/getting-started.md) | Install, build, and run your first photon in 5 minutes |
  503. | [From Method to Chat App](./docs/tutorials/from-method-to-chat-app.md) | Weather showcase: CLI, Beam, MCP, and embedded app UI from one method |
  504. | [Core Concepts](./docs/concepts.md) | The 6 ideas behind Photon |
  505. | [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) | Public reference for every docblock tag Photon understands |
  506. | [Output Formats](./docs/formats.md) | Visual gallery of every `@format` type |
  507. | [Intent Metadata](./docs/reference/INTENT-METADATA.md) | How comments, schemas, annotations, and formats map to native surfaces |
  508. | [Settings](./docs/GUIDE.md#settings-user-configurable-knobs) | Declare runtime knobs with `protected settings` (the canonical config pattern) |
  509. | [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
  510. **Go deeper:**
  511. | Topic | |
  512. |---|---|
  513. | [Custom UI](./docs/guides/CUSTOM-UI.md) | Build rich interactive interfaces with the photon bridge API |
  514. | [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.0 with Google, GitHub, Microsoft |
  515. | [MCP JWT Auth](./docs/guides/MCP-JWT-AUTH.md) | Secure deployed MCP tool calls with short-lived scoped JWTs |
  516. | [MCP Client Registration](./docs/guides/mcp-client-registration.md) | Register MCP clients with Photon's AS via CIMD or DCR |
  517. | [Observability](./docs/guides/observability.md) | OpenTelemetry traces, metrics, logs, and structured errors |
  518. | [Protocol Features](./docs/guides/PROTOCOL-FEATURES.md) | Capability handshake, structured errors, trace correlation |
  519. | [Multi-target Architecture](./docs/internals/ARCHITECTURE.md#one-execution-model-many-targets) | How one Photon method maps to CLI, MCP, web, webhook, WebSocket, and MCP Tasks |
  520. | [Daemon Pub/Sub](./docs/internals/DAEMON-PUBSUB.md) | Real-time cross-process messaging |
  521. | [Webhooks](./docs/reference/WEBHOOKS.md) | HTTP endpoints for external services |
  522. | [Locks](./docs/reference/LOCKS.md) | Distributed locks for exclusive access |
  523. | [Advanced Patterns](./docs/guides/ADVANCED.md) | Lifecycle hooks, dependency injection, interactive workflows |
  524. | [Marketplace Configuration](./docs/guides/MARKETPLACE-CONFIG.md) | Sharing settings across related photons in one marketplace |
  525. | [Deployment](./docs/guides/DEPLOYMENT.md) | Docker, Cloudflare Workers, AWS Lambda, Systemd |
  526. **Operate:**
  527. | Topic | |
  528. |---|---|
  529. | [The Photon Daemon](./docs/guides/DAEMON.md) | Lifecycle, PHOTON_DIR resolution, resilience, troubleshooting |
  530. | [Security](./SECURITY.md) | Best practices and audit checklist |
  531. | [Marketplace Publishing](./docs/guides/MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |
  532. | [Best Practices](./docs/guides/BEST-PRACTICES.md) | Patterns for production photons |
  533. **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) · [Lifecycle & Ingress](./docs/internals/LIFECYCLE-AND-INGRESS.md) · [PHOTON_DIR & Namespace](./docs/internals/PHOTON-DIR-AND-NAMESPACE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
  534. ---
  535. ## Open Source
  536. Photon is free and open source under the [MIT license](./LICENSE).
  537. The project is still evolving and contributions are welcome.
  538. - Star the repository if the idea resonates: `gh repo star portel-dev/photon`
  539. - [Report issues](https://github.com/portel-dev/photon/issues)
  540. - [Contribute improvements or examples](./CONTRIBUTING.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.