@string-os/string

String runtime — an OS for AI agents, built on SFMD. HTML for humans, SFMD for agents.

Browse documents, install apps, execute actions, navigate the web — all through Markdown. Drives a long-running daemon (stringd) so multiple agent calls share session state, history, and authentication.

Install

npm install -g @string-os/string

This installs three things:

• string — CLI you call from a shell or an agent's shell tool
• stringd — daemon that backs the CLI (auto-started; manage with string --daemon)
• a Node library if you want to embed the runtime instead of shelling out

CLI

The basic shape is string <topic> '<command>'. A topic is one of:

• a bare name (main, notes, setup) — a free-form session for ad-hoc work
• app:<pkg>[:<config>] — an installed app session (e.g. app:weather)
• bash:<name> — a persistent shell session (each name = its own pty)
• app, bash, tool, system — hub topics that aggregate / manage their kind

# Install an app from a local file or URL
string setup '/install --app ./apps/weather/string.md'

# Open the app and call its actions
string app:weather '/open app:weather'
string app:weather '/act.now Seoul'
string app:weather '/act.forecast Tokyo'

# Open a web page in a free-form tab (rendered as Markdown)
string docs '/open https://developer.mozilla.org'

# Bash session
string bash:dev 'cd ~/work && ls'

# Hub view — aggregates installed apps, current sessions, etc.
string app

# REPL mode — drop the command argument
string app:weather

Output is wrapped in a short envelope so a calling program can tell runtime output apart from shell noise:

<𝒞=string:app:weather>
seoul: Sunny +20°C ↘6km/h
</𝒞>

Use --json for {ok, code, content, meta} JSON instead.

Daemon

The daemon starts automatically on first call. Manage it explicitly with:

string --daemon start
string --daemon status
string --daemon stop

Default port is 3100 (override with STRINGD_PORT). Sessions, env vars, and installed apps live under ~/.string/users/{user}/.

Library

import { Browser } from '@string-os/string';

const browser = new Browser({ home: process.cwd() });
const result = await browser.exec('/open ./README.md');
console.log(result.ok, result.content);

For talking to an already-running daemon from another language or process, use @string-os/client instead — it's lighter and has zero runtime dependencies.

Using from an agent

Any agent framework with a shell tool (Claude Code, OpenClaw, etc.) can drive string with no custom integration. One paragraph in the prompt is enough:

You have string installed. It's a Markdown browser with installable apps. Call it as string <topic> '<command>'. Output sits between <𝒞=string:topic> and </𝒞>. To find what an app can do: /open app:<name>. Currently installed: weather.

For richer integration, install the MCP server: @string-os/string-mcp.

Environment

| Variable | Default | Purpose | |---|---|---| | STRINGD_PORT | 3100 | Daemon listen port | | STRINGD_USER | default | User identity (multi-user daemons) | | STRINGD_HOME | ~/.string/users/{user} | Per-user data root (config, apps, env vars) |

/set $VAR = "value" persists vars to disk under the current scope (global, app, or app:config). Apps declare what they need with requires: in frontmatter; missing values surface as a hint at /open time.

Documentation

• Source and full docs
• SFMD spec
• Cookbook (apps and tutorials)

Related

• @string-os/core — SFMD parser
• @string-os/client — daemon HTTP/SSE client
• @string-os/compiler — SFMD validator and compiler
• @string-os/string-mcp — MCP server

License

MIT