{"id":50978417,"url":"https://github.com/simular-ai/simulang","last_synced_at":"2026-06-19T11:04:14.004Z","repository":{"id":358310231,"uuid":"1240013465","full_name":"simular-ai/simulang","owner":"simular-ai","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-16T17:43:28.000Z","size":69,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T19:40:40.203Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/simular-ai.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-05-15T17:17:37.000Z","updated_at":"2026-05-16T18:12:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simular-ai/simulang","commit_stats":null,"previous_names":["simular-ai/simulang"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/simular-ai/simulang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simular-ai%2Fsimulang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simular-ai%2Fsimulang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simular-ai%2Fsimulang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simular-ai%2Fsimulang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simular-ai","download_url":"https://codeload.github.com/simular-ai/simulang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simular-ai%2Fsimulang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34528144,"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-06-19T02:00:06.005Z","response_time":61,"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-06-19T11:04:13.868Z","updated_at":"2026-06-19T11:04:13.988Z","avatar_url":"https://github.com/simular-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@simular-ai/simulang`\n\nCLI for running Simulang scripts written in JavaScript or TypeScript, with full access to [`@simular-ai/simulang-js`](https://github.com/simular-ai/simulang-js) and the standard Node runtime.\n\nRequires Node.js **22.18+**.\n\n## Install\n\n```bash\nnpm install -g @simular-ai/simulang\n```\n\nA copy of `@simular-ai/simulang-js` is bundled, so nothing else is needed.\n\n## First run on macOS\n\nmacOS gates the APIs simulang-js drives behind three permissions, granted **per host app** — the terminal or IDE you launch `simulang` from (Terminal, iTerm, Cursor, VS Code, …):\n\n- **Screen Recording** — for `Screen.screenshot()` and any vision-grounded action.\n- **Accessibility** — for the AX tree, AX actions, and window control.\n- **Input Monitoring** — for synthesized mouse and keyboard events to actually reach the foreground app.\n\nRun this once, from the terminal/IDE you'll use:\n\n```bash\nsimulang setup\n```\n\nIt triggers each permission's system prompt one at a time. macOS will pop up a dialog for each, automatically add the requesting host to the corresponding System Settings pane, and offer an **Open System Settings** button — just toggle the entry on. The `setup` command then re-checks and reports what's still pending.\n\nRe-run `simulang setup` any time you switch terminals, upgrade Node, or want to confirm everything is still granted. If a script silently does nothing (clicks not landing, screenshots all-black), missing permissions are almost always the cause — re-run setup.\n\n## First run on Windows\n\nWindows has no system-wide accessibility prompt, but two things can bite on the first run:\n\n- The bundled native `.node` binary may be marked as downloaded and blocked by SmartScreen. If `simulang run` fails with a load error, run PowerShell `Get-ChildItem -Recurse \u003cnode_modules path\u003e | Unblock-File` against the simulang install directory.\n- If your script targets an elevated app, launch your terminal **as Administrator**.\n\n## Usage\n\n```bash\nsimulang run hello.ts           # run a script\nsimulang run --interactive      # Node REPL with simulang-js pre-imported (alias: -i)\nsimulang which hello.ts         # show which simulang-js a script would resolve\nsimulang --version              # prints the CLI version + the bundled simulang-js version\n```\n\nScripts can be `.ts`, `.mts`, `.js`, `.mjs`, or `.simulang` — TypeScript is stripped natively by Node, no build step. The `.simulang` suffix is supported for clarity in workflows that mix shell scripts with simulang scripts, but `.ts` / `.mts` are recommended since editors and `tsc` recognize them out of the box. Example:\n\n```js\nimport { App, FocusPolicy, Visibility } from '@simular-ai/simulang-js'\n\nApp.defaultBrowser().open('https://example.com', FocusPolicy.Steal, Visibility.Show, true)\n```\n\nIn the REPL, every `simulang-js` export (`App`, `Key`, `FocusPolicy`, …) is pre-loaded as a global, and the full namespace is also available as `simulang`.\n\n### Using with Claude Code\n\nRun once to install a Claude Code skill that teaches Claude how to use `simulang`:\n\n```bash\nsimulang init-claude              # user-level, into ~/.claude/skills/simulang/\nsimulang init-claude --project    # project-local, into \u003ccwd\u003e/.claude/skills/simulang/\nsimulang init-claude --check      # report whether the installed skill is up to date\n```\n\nSafe to re-run.\n\n### Picking a `simulang-js` version\n\nThe bundled copy is used by default. To override:\n\n```bash\nsimulang run --simulang-js=0.2.1 \u003cscript\u003e        # specific version (cached after first install)\nsimulang run --simulang-js=latest \u003cscript\u003e       # latest from the registry\nsimulang run --simulang-js=/path/to/simulang-js \u003cscript\u003e   # local checkout\n```\n\nYou can also set `SIMULANG_JS` in the environment, or `npm install @simular-ai/simulang-js` next to your script for a per-project pin. If none of the above is set, the CLI's own bundled copy is used.\n\nUse `simulang which` to see which copy a script resolves to.\n\n## Authentication\n\nScripts that hit hosted services need an OpenRouter API key. Set `OPENROUTER_API_KEY` in your environment before running a script:\n\n```bash\nexport OPENROUTER_API_KEY=...\nsimulang run \u003cscript\u003e\n```\n\n`simulang run` prints a warning to stderr when `OPENROUTER_API_KEY` is unset, but does not refuse to run — scripts that don't hit hosted services work without it.\n\n## Development\n\n```bash\ngit clone https://github.com/simular-ai/simulang\ncd simulang\nnpm install\nnpm run build          # tsc → dist/\nnpm link               # exposes `simulang` on PATH\nsimulang run examples/hello.ts\n```\n\nOther scripts: `npm run typecheck`, `npm run lint`, `npm run format`.\n\nTo test against a local `simulang-js` checkout:\n\n```bash\nsimulang run --simulang-js=/path/to/simulang-js examples/hello.ts\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimular-ai%2Fsimulang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimular-ai%2Fsimulang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimular-ai%2Fsimulang/lists"}