{"id":50371559,"url":"https://github.com/string-os/cookbook","last_synced_at":"2026-05-30T07:03:55.844Z","repository":{"id":356499590,"uuid":"1215449331","full_name":"string-os/cookbook","owner":"string-os","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-08T09:42:55.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T11:37:19.155Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/string-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2026-04-19T23:25:50.000Z","updated_at":"2026-05-08T09:42:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/string-os/cookbook","commit_stats":null,"previous_names":["string-os/cookbook"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/string-os/cookbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fcookbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fcookbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fcookbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fcookbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/string-os","download_url":"https://codeload.github.com/string-os/cookbook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fcookbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33682998,"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-05-30T02:00:06.278Z","response_time":92,"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-05-30T07:03:54.731Z","updated_at":"2026-05-30T07:03:54.954Z","avatar_url":"https://github.com/string-os.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# String Cookbook\n\n**Markdown is the content. `/command` is the interaction. Together they are an AI-native standard for exploring the web and using apps.**\n\n`string` is the runtime for that standard — a browser for markdown that talks back, and the beginning of an OS built on the same idea.\n\n---\n\n## The whole idea, in one screen\n\nAn SFMD app is a markdown file (or several). It declares what it is and what it can do. A running `string` parses it, renders it for the reader, and dispatches commands against it.\n\nA complete working app:\n\n````markdown\n---\ntitle: Weather\nname: weather\ntype: app\n---\n\n```act.now\nGET https://wttr.in/{city}?format=%l:+%C+%t+%w\u0026m\n  city: string (required) \"City name\"\n```\n````\n\nInstall it, then call its action:\n\n```bash\n$ string file:setup '/install --app ./apps/weather/index.md'\nInstalled app:weather\n\n$ string app:weather '/open app:weather'\n# Weather\nA three-action weather app, backed by wttr.in and Nominatim...\n[actions] /act.now --city \u003cstring\u003e | /act.forecast --city \u003cstring\u003e | /act.search --q \u003cstring\u003e\n\n$ string app:weather '/act.now --city Seoul'\nseoul: Sunny +20°C ↘6km/h\n```\n\nNo server is running. No tool schema was registered. The markdown file declared an action block; `string` parsed it; the agent invoked it. That is the entire shape.\n\n(The outputs above are lightly trimmed for readability — when you run the commands, each response is wrapped in a short framing envelope the CLI prints so callers can tell runtime output apart from noise. Chapter 00 shows it in full; chapter 03 explains how the client library parses it away so agent code never sees it.)\n\n---\n\n## Apps and Tools\n\nSFMD documents come in two flavors:\n\n- **App** — has its own view and session. The AI enters it with `/open app:name` and explores pages, runs actions, navigates with shortcuts. Think: a website.\n- **Tool** — no view. The AI calls it with `/tool:name` from its current context and reads the result back. Think: a shell command.\n\nBoth are `.md` files with action blocks. The difference is how they're accessed. This cookbook focuses on apps; the [tools guide](https://github.com/string-os/string/blob/main/docs/runtime/13-tools.md) covers the other side.\n\n---\n\n## Two ways an AI uses `string`\n\n### Path 1 — the CLI, no code changes\n\nAny agent that can run shell commands can use `string` today. The agent runs `string \u003ctopic\u003e '\u003ccmd\u003e'` and reads the payload back from stdout. That's the whole integration:\n\n```bash\n$ string app:weather '/act.now --city Seoul'\n\u003c𝒞=string:app:weather\u003e\nseoul: Sunny +20°C ↘6km/h\n\u003c/𝒞\u003e\n```\n\nThe `\u003c𝒞=string:app:weather\u003e` … `\u003c/𝒞\u003e` pair is the default output framing — opening tag, payload, closing tag. The agent reads the payload between them. (A `--json` flag is also available for callers that strongly prefer a JSON envelope; the frame form is the default.)\n\nWorks in OpenClaw, Hermes Agent, or any framework with a shell tool. Zero integration work, zero code changes. This is how `string` should be used on first contact. Chapter [00](./00-weather.md) walks it through end to end with the weather app.\n\n### Path 2 — the client library (recommended for agent builders)\n\nIf you're building an agent framework, embed [`@string-os/client`](https://www.npmjs.com/package/@string-os/client). Your code calls `string` by function, gets back structured results, and exposes **one tool** to the LLM that dispatches to every installed SFMD app — weather, calendar, wiki, anything.\n\nSee chapter [03 — Client library](./03-client-library.md) for the API, the single-tool pattern, and the daemon lifecycle.\n\n---\n\n## Chapters\n\n| # | Chapter | What you'll see |\n|---|---------|-----------------|\n| 00 | [**Weather app, end to end**](./00-weather.md) | Install the app, drive it from a terminal, then watch an AI use it via the CLI. Start here. |\n| 01 | [**Anatomy of an SFMD app**](./01-anatomy.md) | What the `weather` app is made of — frontmatter, action blocks, field schemas, shell-safe substitution — and how larger apps compose multiple files. |\n| 02 | [**Why markdown + /command**](./02-compare.md) | The same weather capability built as an MCP server and as a function-calling tool, side by side with the SFMD version. |\n| 03 | [**Client library**](./03-client-library.md) | Embedding `@string-os/client` in an agent framework. API reference and the single-tool pattern. |\n| 04 | [**Porting Nano Banana Pro**](./04-porting-nano-banana-pro.md) | Worked example: take a real Codex skill (image generation via Gemini 3 Pro Image) and port it to a single-file SFMD app. The recipe transfers to any HTTP-based skill. |\n\nFive chapters. The cookbook is deliberately narrow — its job is to make one thing viscerally clear: **the agent-facing interface is markdown plus a small set of commands, and most of the tools an AI needs fit that shape.**\n\n---\n\n## Who this is for\n\n- **Developers building AI agents** in OpenClaw, Hermes Agent, or any framework with shell access or Node.js interop. You get a zero-integration tool today (Path 1) and a cleaner integration tomorrow (Path 2).\n- **End users running those agents** who want to understand what their AI is actually doing. Chapter 01 is enough to read any SFMD app your agent installs.\n- **Anyone evaluating a protocol for agent tools.** Chapter 02 is the comparison.\n\n---\n\n## Example apps\n\nThis cookbook ships four working apps:\n\n| App | Pattern | API | Auth? |\n|-----|---------|-----|-------|\n| [**Weather**](./apps/weather/) | GET actions | wttr.in + Nominatim | No |\n| [**Nano Banana Pro**](./apps/nano-banana-pro/) | POST + binary save | Gemini 3 Pro Image | `GEMINI_API_KEY` |\n| [**Moltbook**](./apps/moltbook/) | Browse pattern | moltbook.com | `MOLTBOOK_API_KEY` |\n| [**Moltbook (single-page)**](./apps/moltbook-single/) | Action pattern | moltbook.com | `MOLTBOOK_API_KEY` |\n\n**Weather** is the simplest — no auth, two GET actions, one response template. Start here.\n\n**Nano Banana Pro** shows POST body templates, `{field|base64file}` modifiers, and binary response extraction (save/decode/to). See chapter [04](./04-porting-nano-banana-pro.md) for the porting walkthrough.\n\n**Moltbook** wraps moltbook.com's REST API. Two variants show the two main patterns for building SFMD apps:\n\n- **Browse pattern** (`moltbook` — main): Multi-page app (`string.md`, `communities.md`, `profile.md`, `messages.md`). Each action that returns a list registers inline shortcuts (`{@post} = {p.id}`) and ends with a `next:` line listing the follow-up actions, parameterized with `@post-N`. Drill-in is `/act.read @post-3` (action on same page) and cross-page navigation is `/open communities.md` (separate verb). **Use this as the reference moltbook app.**\n- **Action pattern** (`moltbook-single`): Single-page app where feed shows post IDs inline. The agent reads posts with `/act.read --id \u003cid\u003e`. All interaction stays on the app page. Simpler, self-contained, good for tool-like workflows.\n\n---\n\n## Status: v0.1 preview\n\n### Implemented today\n\n- **Runtime:** parser, renderer, dispatcher, loader, env-store. [`string-os/string`](https://github.com/string-os/string).\n- **Commands:** `/open`, `/nav`, `/back`, `/refresh`, `/close`, `/info`, `/ls`, `/source`, `/act`, `/tool`, `/exec`, `/write`, `/append`, `/edit`, `/verify`, `/undo`, `/set`, `/install`, `/uninstall`, `/session`, `/help`.\n- **Topic types:** `file:`, `app:`, `web:`, `bash:`.\n- **`string` CLI** — the zero-code integration path. Auto-starts the daemon on first use. Default output wraps payloads in `\u003c𝒞=string:topic\u003e` frames; `--json` flag is available for callers that prefer a JSON envelope.\n- **`stringd` daemon** — long-lived process, loopback HTTP/SSE. See [`stringd-protocol-v0.1.md`](https://github.com/string-os/string/blob/main/docs/stringd-protocol-v0.1.md).\n- **`@string-os/client`** — TypeScript client library, the recommended integration path for agent builders. ~185 lines, zero dependencies. See chapter 03.\n- **SFMD core format** — frontmatter, action blocks, tool blocks, nav menus, shortcuts, includes. See [`string-os/sfmd`](https://github.com/string-os/sfmd).\n- **`@string-os/compiler`** — multi-file SFMD composition via `[!include:]`.\n- **HTML fallback** — any HTTPS URL can be opened; non-SFMD HTML is converted to markdown.\n- **MCP bridge** (`@string-os/string-mcp`) — a third integration path for MCP hosts you don't control.\n\n### Planned for v0.2 and beyond\n\n- **`stringhub`** — a marketplace for installable SFMD apps.\n- **Hosted reference sites** — [`string-os.org`](https://string-os.org), the company homepage, a shared wiki, all built as SFMD and browseable with `string`.\n- **Signed packages** with provenance metadata, fine-grained capabilities, audit logging.\n- **More language clients** — Python client in progress. Other languages welcome.\n- **OS-scale features** — session persistence across devices, capability broker, multi-user scoping, skill search. These land as the runtime grows past \"browser\" toward \"OS.\"\n- **ChanFlow** — the multi-channel protocol `string`'s client library prototypes. To be released separately once it is ready to stand on its own.\n\nThe scope stays honest: what is implemented today is enough to run the full cookbook against real code.\n\n## License\n\nMIT. Copy any part of this cookbook into your own project without attribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fcookbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstring-os%2Fcookbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fcookbook/lists"}