Octoscript

https://octoscript.org/docs
Admin
Octoscript is a domain-specific language designed for LLMs and agents to compose tools, data...
Tokens:22,262
Snippets:183
Trust Score:2.5
Update:1 day ago
Show doc for...
Tokens:
Raw
### Setup native workspace with Design Flow tools

Source: https://octoscript.org/docs/octosense-apps/

Run these commands from the Design Flow checkout to prepare the repositories and build prerequisites. The --check flag verifies the setup. These commands have not been executed as part of website checks.

```bash
python3 tools/setup-native.py
python3 tools/setup-native.py --check
```

--------------------------------

### Octoscript text.echo tool call example

Source: https://octoscript.org/docs/why-octoscript/

Demonstrates the repository's demonstration tool: registers text.echo, produces source, and the application supplies the implementation. The program calls the tool with a task string and returns the result.

```octoscript
use mod.tool
let task = "prepare release notes"
let result = tool.call("text.echo", task)
result
```

--------------------------------

### Call a tool with Octoscript (tool_workflow.octoscript)

Source: https://octoscript.org/

Example Octoscript source that imports the tool module, defines a task string, calls the text.echo tool with the task, and returns the result. The expected output is the string "prepare release notes".

```octoscript
use mod.tool

let task = "prepare release notes"
let result = tool.call("text.echo", task)
result

```

--------------------------------

### Complete L0 Card Example with State, Events, and View

Source: https://octoscript.org/docs/language-profiles/

A complete L0 card that declares local Boolean state and translated vocabulary. The host resolves sys.locale() and tapping the Chip toggles the declared cell. This example demonstrates the core L0 syntax for sources, state, events, copy, and view composition.

```L0
# ledger preferences@1.0.0
# level: L0
source env.locale sys.locale()
state updates { shape: bool, initial: false }
event flip { updates: toggle }
copy title { class: vocabulary, en: "Preferences", zh: "偏好设置" }
copy option { class: vocabulary, en: "Updates", zh: "接收更新" }
view root Surface {
    Col {
        TextTitle(text: copy.title)
        Chip(text: copy.option, active: updates, on_tap: flip)
    }
}
```

--------------------------------

### Expected output for text.echo tool call

Source: https://octoscript.org/

The expected output of the text.echo tool call in the Octoscript example, which is the string "prepare release notes".

```text
"prepare release notes"
```

--------------------------------

### Plan a run with custom project paths using bash tools/image-to-appcard-flow.sh

Source: https://octoscript.org/docs/design-to-app/

Use this command to propose a run with your own project paths. The `plan` subcommand prints the stages and arguments without executing them. The repository guide describes preparation, compilation, evidence, and packaging.

```bash
bash tools/image-to-appcard-flow.sh plan \
  --project /path/to/service-project \
  --manifest /path/to/service-project/image-to-appcard-flow.json
```

--------------------------------

### Splash UI object tree example

Source: https://octoscript.org/docs/splash-a2app/

Shows a basic Splash UI object tree with a View containing a Label and Button. Uses properties like width, height, flow, and spacing. This is a UI-body excerpt for a host with registered widgets, not a standalone workflow CLI program.

```splash
View {
    width: Fill
    height: Fit
    flow: Down
    spacing: 12
    title := Label { text: "Ready to build" }
    launch := Button { text: "Run workflow" }
}
```

--------------------------------

### Build OctoSense card host and app hub

Source: https://octoscript.org/docs/octosense-apps/

Run from the App Hub sibling directory to compile the octosense-card-host and octosense-app-hub packages in release mode.

```bash
cargo build --release -p octosense-card-host -p octosense-app-hub
```

--------------------------------

### Combined workflow example: function, record, conditional, fallback

Source: https://octoscript.org/docs/language-profiles/

Shows a complete Octoscript workflow combining a function, record, conditional value, and fallback. Requires a registered and authorized text.echo; a catch cannot issue permission or undo a side effect.

```octoscript
use mod.tool
fn prepare(title) {
    return {title: title, ready: true}
}
let draft = prepare("Release notes")
let summary = if draft.ready {
    draft.title
} else {
    "Not ready"
}
let result = try tool.call("text.echo", summary) catch "Unavailable"
result
```

--------------------------------

### Run a contained app locally with tools/octo

Source: https://octoscript.org/docs/octosense-apps/

Return to Design Flow and use a new destination directory and a free port. The run command takes the bundle path as a positional argument; with --detach it returns after the UI is exposed and a frame is rendered, otherwise it waits for exit. The default development run stamps the manifest, so use an unsigned working copy.

```bash
tools/octo doctor
tools/octo new /tmp/octosense-notes --id walkthrough.notes --name "Notes"
tools/octo run /tmp/octosense-notes/bundle --hidden --detach --port 8141
tools/octo shot 8141 /tmp/octosense-notes/first-frame.png
curl -s http://127.0.0.1:8141/quit
```

--------------------------------

### Run makepad-script and makepad-regex tests

Source: https://octoscript.org/docs/shared-vm/

Commands to run the test suites for the makepad-script and makepad-regex crates, resolved from the pinned checkout. These tests are run explicitly as part of the bumping process.

```bash
cargo test -p makepad-script
cargo test -p makepad-regex
```

--------------------------------

### Terminal: Clone, check, and run Octoscript CLI

Source: https://octoscript.org/

Commands to clone the Octoscript repository, change into its root, validate the tool_workflow.octoscript file with the checker, and run it with the --allow-echo flag. Requires Rust and Cargo; run from the repository root.

```bash
git clone https://github.com/OctoSense-org/Octoscript.git
cd Octoscript

cargo run --locked -p octoscript-cli -- \
  check examples/tool_workflow.octoscript

cargo run --locked -p octoscript-cli -- \
  run --allow-echo examples/tool_workflow.octoscript

```

--------------------------------

### Workflow draft approval pipeline

Source: https://octoscript.org/docs/why-octoscript/

Execution pipeline from draft decoding to execution. Call hints help a reviewer but do not resolve aliases, control flow, or computed names, and may be truncated. Approval and reservation-time enforcement must constrain actual calls together.

```text
WorkflowDraft::from_json  → decode bounded data; reject extra fields
review                   → effect-free syntax + direct call hints
engine.plan_draft        → engine-owned plan; record Planned only
host selects policies    → allowed tools, argument policy and budgets
engine.approve…          → bind host approval to the plan
engine.execute           → check every actual call at reservation
```

--------------------------------

### Octoscript generation loop pipeline

Source: https://octoscript.org/docs/why-octoscript/

Shows the conceptual pipeline from profile, tool catalog, and user intent through generated source, effect-free check, repair, host approval, execution, and auditable state. Emphasizes that a parseable program is not authorized.

```text
profile + tool catalog + user intent
  → generated source / workflow draft
  → effect-free check and review
  → repair diagnostics
  → host approval + bounded capabilities
  → execute / yield / resume
  → results and auditable state
```
Tokens:
Raw