{"id":50370725,"url":"https://github.com/string-os/string","last_synced_at":"2026-05-30T07:01:02.829Z","repository":{"id":356469466,"uuid":"1215449317","full_name":"string-os/string","owner":"string-os","description":"Markdown that runs — one file, any agent.","archived":false,"fork":false,"pushed_at":"2026-05-26T07:41:03.000Z","size":823,"stargazers_count":17,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T09:15:01.439Z","etag":null,"topics":["agent-runtime","agent-skills","ai-agents","cli","commonmark","llm","markdown","mcp"],"latest_commit_sha":null,"homepage":"https://string-os.org","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/string-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"string-os"}},"created_at":"2026-04-19T23:25:48.000Z","updated_at":"2026-05-26T07:41:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/string-os/string","commit_stats":null,"previous_names":["string-os/string"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/string-os/string","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fstring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fstring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fstring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fstring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/string-os","download_url":"https://codeload.github.com/string-os/string/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/string-os%2Fstring/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":["agent-runtime","agent-skills","ai-agents","cli","commonmark","llm","markdown","mcp"],"created_at":"2026-05-30T07:00:31.624Z","updated_at":"2026-05-30T07:01:02.792Z","avatar_url":"https://github.com/string-os.png","language":"TypeScript","funding_links":["https://github.com/sponsors/string-os"],"categories":[],"sub_categories":[],"readme":"# String\n\n\u003e The web gave humans a universal surface for information.\n\u003e SFMD gives AI agents one for work.\n\nAI agents today read web pages designed for humans, parse JSON from per-tool servers, and memorize per-skill protocols. The infrastructure was built for someone else. They cope because they're capable — but the cost is paid in tokens, latency, and security promises that don't hold under pressure.\n\n**SFMD** (String Flavored Markdown) is one Markdown format an agent can both *read* (like documentation) and *execute* (calls APIs, runs CLI tools, navigates pages). **String** is the reference runtime: one tool, one call shape — the entire surface.\n\n\u003e **AI agents reading this:** the [skill](./skill.md) is written for you. Execute it and you'll be using String in a couple of minutes.\n\u003e **Humans:** read on.\n\n---\n\n## What an agent sees\n\nThree commands. Zero prior documentation read. The agent ends up reading a post in a social network app it has never seen.\n\n```bash\n$ string app:moltbook /open\n\u003e Opened. [actions] home, feed, read, comment, post, search, ...\n\u003e next: /act.read @post-N · /act.feed · /act.search \"...\"\n\n$ string app:moltbook /act.feed\n\u003e Feed (hot): 20 posts. @post-1 through @post-20 registered.\n\n$ string app:moltbook /act.read @post-3\n\u003e the curator is the lawmaker — by Starfish in /general\n\u003e (post body)\n\u003e next: /act.upvote @post · /act.comment @post \"...\"\n```\n\nNo SDK installed. No API key in the agent's context. No endpoint memorized. Each response tells the agent what it can do next — the same way a human app does.\n\n## What an author writes\n\nA complete app, in one file:\n\n````markdown\n---\nname: weather\ntype: app\ndefault: now\n---\n\n# Weather\n\nGet current conditions anywhere on Earth.\n\n```act.now\nGET https://wttr.in/{city}?format=%l:+%C+%t+%w\u0026m\n  city, -c: string (required) \"City name\"\n```\n````\n\nInstall and call:\n\n```bash\nnpm install -g @string-os/string\nstring '/install --app ./weather.md'\nstring app:weather '/act.now Seoul'\n# → Seoul: ☀️ +20°C ↘6km/h\n```\n\nA Markdown file declared the API. The runtime called it. The agent got the result. The file is the deliverable.\n\n---\n\n## What you get\n\n**Scales without growing context.** Most tool integrations add to the agent's context with each new tool — docs, schemas, examples. With String, the same small surface (`/open`, `/act`, `/info`) covers every installable app. Adding apps doesn't grow what the agent has to know.\n\n**Credentials kept out of the agent's context.** API keys live in app-scoped environment variables — the agent doesn't see them, so direct exfiltration through prompt injection on the agent isn't a path. (The app running an action still has the key; v0.1 doesn't sandbox an installed app's HTTP/CLI calls — see \"Not yet\" below.)\n\n**Self-discoverable.** Every response carries a `next:` hint. Errors carry `Recovery:` lines. `/info` shows where you are; `/act --help` lists what you can do. Agents onboard onto unknown apps without prior documentation.\n\n**Portable.** The same `.sfmd` file works in any runtime that speaks the format — CLI, MCP server, in-process library, HTTP daemon. Tomorrow, anything that parses CommonMark.\n\n---\n\n## How it works\n\nThree layers, cleanly separated:\n\n```\nString OS         ← execution, navigation, state, trust\n  ↑\nSFMD              ← structure, references, declarations (no execution)\n  ↑\nCommonMark        ← base syntax\n```\n\nThe same shape SFMD wears in HTML's role for the browser. Format and runtime are decoupled — any runtime can read SFMD, just as any browser can render HTML.\n\n**Two verbs.** A small surface that doesn't change with the resource:\n\n- `/open` — see something (document, page, app, URL, shortcut). Pure read.\n- `/act` — do something (call an API, run a CLI tool, submit data). Side effects.\n\nThe separation is load-bearing. `/open` never executes; `/act` always does. An agent reading a feed never accidentally posts. [Full surface →](https://docs.string-os.org/runtime/overview/)\n\n**Same shape, any resource.**\n\n| Resource | Read | Act |\n|---|---|---|\n| Document | `/open file.md` | `/act.\u003cname\u003e` if defined |\n| Installed app | `/open app:weather` | `/act.now --city Seoul` |\n| Web URL | `/open https://docs.example.com` | (link traversal) |\n\nThe agent learns the verbs once and uses them everywhere. New capabilities come from new documents, not new code.\n\n**Shortcuts let authors keep URLs in the runtime.** A markdown link in SFMD can reach the agent as `[Documentation][@docs]` instead of `[Documentation](https://example.com)` — useful when output flows back into the agent's context (e.g. spoofed-domain tricks like `g1thub.com` displayed as `github.com`). It's an authoring pattern, not a runtime invariant: direct `/open \u003curl\u003e` still puts the URL in the agent's view.\n\n---\n\n## Install\n\n**Option A — Claude Code plugin (zero setup)**\n\n```\n/plugin marketplace add string-os/string\n/plugin install string@string-os\n```\n\nTwo lines in Claude Code: registers the `mcp__string__string` tool (the plugin's `.mcp.json` spawns `string` via `npx`, so no separate npm install) and loads a skill that walks Claude through using it. After install, ask Claude something like *\"install gh-kanban from string-os/apps and try it\"* — it'll take it from there.\n\n**Codex CLI plugin** (same idea, parallel `.codex-plugin/` manifest in the same repo):\n\n```bash\ncodex plugin marketplace add string-os/string\ncodex plugin install string@string-os\n```\n\nSkills and MCP config are shared between the two manifests — one source, two runtimes.\n\n**Option B — npm (recommended for CLI use)**\n\n```bash\nnpm install -g @string-os/string\nstring --help\n```\n\nRequires Node.js 20+. The `stringd` daemon launches automatically on first use.\n\n**Option C — from source**\n\nFor contributors, or to run the latest unreleased code. Requires Node.js 20+ and [pnpm](https://pnpm.io).\n\n```bash\ngit clone https://github.com/string-os/string.git\ncd string\npnpm install\npnpm -r --filter \"./packages/*\" build      # build the packages → dist/\n```\n\nRun the built CLI:\n\n```bash\nnode packages/string/dist/cli.js --help\n```\n\nOr run straight from TypeScript, no build step (handy while developing):\n\n```bash\nnpx tsx packages/string/src/cli.ts --help\n```\n\nTo expose it as `string` on your PATH, link the built bin — e.g. `cd packages/string \u0026\u0026 npm link`, or a shim that runs `node /abs/path/to/string/packages/string/dist/cli.js \"$@\"`.\n\n---\n\n## Try it\n\n```bash\nnpm install -g @string-os/string\ngit clone https://github.com/string-os/cookbook.git\ncd cookbook\n\nstring '/install --app ./apps/weather/string.md'\nstring app:weather '/act.now Seoul'\n```\n\nThe cookbook has a dozen runnable examples — Kanban over GitHub Projects, an AI social network, semantic search, code review, k8s helpers — each a single `.sfmd` file you can read end-to-end. These aren't toy demos; they're how real apps look in SFMD.\n\n---\n\n## Four ways to embed\n\n- **CLI** — `string '/open something'`. The default; what you just ran.\n- **MCP server** (Claude Desktop, Cursor, …) — `string --mcp` (stdio) or point a client at `http://localhost:3100/mcp` (HTTP). One MCP tool, `string({topic, cmd})`, wraps the entire command surface.\n- **In-process library** — `import { Browser } from '@string-os/string'`. No daemon, no HTTP.\n- **HTTP daemon + any-language client** — `string --daemon start`. Wire spec at [`stringd` protocol v0.1](https://docs.string-os.org/reference/protocol/); reference TS client in `@string-os/client`.\n\nAdd a feature once — it works in all four paths.\n\n---\n\n## How it compares\n\n| | What it is | What enters the agent's context |\n|---|---|---|\n| **SFMD via String** | Markdown app + small runtime | One surface, regardless of app count |\n| **MCP** | Protocol with per-tool server | Tool list + per-tool schemas (credentials depend on the server's design) |\n| **llms.txt** | Static read-only index | URL list. No execution. |\n| **SKILL.md / agent skills** | Per-runtime instruction file | One instruction set per tool, per runtime |\n\nThe structural differences matter more than the protocol differences:\n\n- **vs MCP.** Many MCP setups end up surfacing credentials or auth'd schemas in the agent's tool context. String apps in String default to app-scoped env vars — credentials don't pass through the agent. The app itself still uses the key, so app trust still matters in v0.1.\n- **vs llms.txt.** Read-only. SFMD declares executable actions as first-class.\n- **vs SKILL.md.** A skill is per-agent-runtime instruction. An SFMD file is a portable app surface — any runtime that speaks SFMD can use it. One surface covers every installable app, not one set of instructions per app per runtime.\n\nThe novelty is the combination: human-readable + AI-readable without HTML parsing + AI-executable + cross-agent portable, in a single Markdown primitive with a small runtime.\n\n---\n\n## v0.1 — what ships now\n\nWorking:\n\n- SFMD parser, runtime, CLI, MCP server, daemon\n- App / tool install from local files or HTTPS\n- Action methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `CLI`\n- `bash:` topics and `/exec` (opt-in)\n- Cookbook with a dozen working apps\n\nNot yet:\n\n- Signed packages — **run SFMD files from trusted sources only**\n- Fine-grained capability permissions — `/exec` and `bash:` topics are opt-in, but an installed app's own HTTP fetches and `CLI` actions run unsandboxed. Inspect before installing.\n\n**Platform.** Tested on Linux. macOS should work (`/bin/bash` available, POSIX shell only) but isn't routinely tested. **Windows is not supported in 0.1.x**: the runtime spawns `/bin/bash` for every CLI action. Use WSL on Windows, or wait for portable execution in v0.2.\n\nTrust model in [`SECURITY.md`](./SECURITY.md). Full spec for parser implementors in the [SFMD spec repo](https://github.com/string-os/sfmd).\n\n---\n\n## Packages\n\n| Package | What |\n|---|---|\n| [`@string-os/core`](./packages/core) | SFMD parser, extractor, utilities |\n| [`@string-os/compiler`](./packages/compiler) | Compiler and validator |\n| [`@string-os/string`](./packages/string) | Runtime — Browser, Session, Loader, daemon (HTTP/SSE + MCP), CLI, stdio MCP shim |\n| [`@string-os/client`](./packages/client) | HTTP/SSE client for `stringd` — zero deps |\n\n---\n\n## The bet\n\nThe web of pages, JS-hydrated SPAs, and per-tool MCP servers — none of it was designed for agents. They use it anyway because models got good enough to brute-force through bad UX. That works until apps multiply, tasks chain, and adversaries probe; then the hidden tax compounds.\n\nSFMD is the bet that agents deserve the same thing humans got: a universal, discoverable surface where the format is the API, the document is the app, and the cost of trying a new thing is one `/open`.\n\n---\n\n## More\n\n- [docs.string-os.org](https://docs.string-os.org) — full guide\n- [Cookbook](https://github.com/string-os/cookbook) — runnable example apps\n- [SFMD spec](https://github.com/string-os/sfmd) — format specification\n- [Skill for AI agents](./skill.md) — written for agent self-onboarding\n\nContributing: [CONTRIBUTING.md](./CONTRIBUTING.md). Security: [SECURITY.md](./SECURITY.md). License: [MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fstring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstring-os%2Fstring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstring-os%2Fstring/lists"}