{"id":51441571,"url":"https://github.com/toadharvard/starloom","last_synced_at":"2026-07-05T12:01:43.850Z","repository":{"id":352509970,"uuid":"1215413306","full_name":"toadharvard/starloom","owner":"toadharvard","description":"Starlark workflow orchestrator for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-19T22:26:50.000Z","size":280,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T00:27:53.149Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/toadharvard.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-19T21:58:42.000Z","updated_at":"2026-04-19T22:26:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toadharvard/starloom","commit_stats":null,"previous_names":["toadharvard/starloom"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/toadharvard/starloom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toadharvard%2Fstarloom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toadharvard%2Fstarloom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toadharvard%2Fstarloom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toadharvard%2Fstarloom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toadharvard","download_url":"https://codeload.github.com/toadharvard/starloom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toadharvard%2Fstarloom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35153109,"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-07-05T02:00:06.290Z","response_time":100,"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-07-05T12:01:43.029Z","updated_at":"2026-07-05T12:01:43.833Z","avatar_url":"https://github.com/toadharvard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starloom\n\nStarloom runs deterministic [Starlark](https://github.com/bazelbuild/starlark) workflows that orchestrate groups of AI coding agents. You describe *what should happen* — which agents run, in what order, what each one sees, how results combine — as a `.star` file; Starloom executes it as a persisted, inspectable, resumable session.\n\n```python\n# examples/simple_agent.star\ndef main():\n    result = call_agent(\"Say hello in one word\", flags=\"--model haiku\")\n    output(result)\n\nmain()\n```\n\n```bash\nstarloom session create examples/simple_agent.star\n```\n\nEvery run is a session on disk: graph, events, costs, stdout — all replayable. You can attach to a live run, resume a stopped one, patch a node's prompt or flags and re-run, or gate execution at workflow-authored checkpoints.\n\n---\n\n## Why Starlark?\n\nStarlark gives you a real, hermetic scripting language — conditionals, loops, functions, parallel fan-out — without the non-determinism of letting an LLM decide control flow. The orchestration is deterministic code. The work inside each agent call is the only place the model gets to improvise.\n\n---\n\n## Install the CLI\n\nRequires Python 3.11+ and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude`) on `$PATH`.\n\n**With [`uv`](https://docs.astral.sh/uv/) (recommended)** — installs `starloom` as a standalone tool on `$PATH`:\n\n```bash\nuv tool install git+https://github.com/toadharvard/starloom.git\n```\n\n**With `pip`**:\n\n```bash\npip install git+https://github.com/toadharvard/starloom.git\n```\n\n**From a clone** (if you want the `examples/` directory locally):\n\n```bash\ngit clone https://github.com/toadharvard/starloom.git\ncd starloom\nuv pip install -e .        # or: pip install -e .\n```\n\nVerify:\n\n```bash\nstarloom --help\n```\n\n---\n\n## Shell completions\n\nPick your shell and add the one-liner to your shell's rc file:\n\n```bash\n# bash — append to ~/.bashrc\neval \"$(_STARLOOM_COMPLETE=bash_source starloom)\"\n```\n\n```zsh\n# zsh — append to ~/.zshrc\neval \"$(_STARLOOM_COMPLETE=zsh_source starloom)\"\n```\n\n```fish\n# fish — append to ~/.config/fish/config.fish\n_STARLOOM_COMPLETE=fish_source starloom | source\n```\n\nRun `starloom completions {bash|zsh|fish}` to re-print the snippet for your shell.\n\nFor faster shell startup, generate the script once and source it:\n\n```bash\n_STARLOOM_COMPLETE=zsh_source starloom \u003e ~/.starloom-complete.zsh\n# then in ~/.zshrc:\nsource ~/.starloom-complete.zsh\n```\n\n---\n\n## Install the Claude Code plugin\n\nThe repo ships a Claude Code plugin (`claude-plugin/`) with two skills:\n\n- **starloom-cli-operator** — drives `starloom` from inside Claude Code: creates sessions, attaches, patches nodes, resolves checkpoints.\n- **starloom-workflow-implementer** — writes clean `.star` files from an already-approved architecture.\n\nClone the repo and symlink the plugin into Claude Code's plugins directory:\n\n```bash\ngit clone https://github.com/toadharvard/starloom.git\nmkdir -p ~/.claude/plugins\nln -s \"$(pwd)/starloom/claude-plugin\" ~/.claude/plugins/starloom\n```\n\nRestart Claude Code. The skills become available automatically when the model detects a matching task.\n\n---\n\n## Core primitives\n\nAvailable inside a `.star` file:\n\n| Primitive | What it does |\n| --- | --- |\n| `call_agent(prompt, *, flags=\"\")` | Run one agent, block, return its final text. |\n| `agent(prompt, *, flags=\"\")` | Return an agent *spec* (not yet run). Pass specs to `parallel_map` to run concurrently. |\n| `parallel_map(fn, items)` | Apply `fn` (returning an `agent(...)` spec) over `items` and run all specs in parallel. |\n| `output(text)` | Emit a workflow output block. Print-like: one per call, all are preserved. |\n| `checkpoint(question)` | Pause the workflow and wait for a human answer via `starloom checkpoint answer`. |\n| `fail(reason)` | Abort the workflow with an error. |\n| `param(name, *, type, default)` | Declare a parameter (supplied via `-p KEY=VALUE`). |\n\nExample of parallel fan-out:\n\n```python\ndef main():\n    results = parallel_map(\n        lambda topic: agent(\"Write one sentence about \" + topic, flags=\"--model haiku\"),\n        [\"cats\", \"dogs\", \"birds\"],\n    )\n    output(\"\\n\".join(results))\n\nmain()\n```\n\nSee `examples/` for more: pipelines, refinement loops, review workflows, nested sub-workflows.\n\n---\n\n## CLI at a glance\n\n```\nstarloom session create \u003cfile.star\u003e [-p K=V ...]   Run a workflow\nstarloom session attach [SESSION_ID]               Watch live or replay\nstarloom session resume [SESSION_ID]               Restart a stopped session\nstarloom session list [--status ...]               List sessions\nstarloom session stop [SESSION_ID]                 Halt a running session\nstarloom session delete SESSION_ID | --all         Cleanup\n\nstarloom node list [-s SESSION_ID]                 Show the graph\nstarloom node patch NODE_ID [--prompt \"...\"] [--flags \"...\"]   Edit and re-run\nstarloom node stop NODE_ID                         Halt one running node\n\nstarloom checkpoint answer CHECKPOINT_ID \"text\"    Answer a workflow pause\nstarloom checkpoint approve CHECKPOINT_ID          Approve a backend tool call\nstarloom checkpoint reject CHECKPOINT_ID           Reject a backend tool call\n\nstarloom explain [TOPIC]                           Built-in concept help\nstarloom completions {bash|zsh|fish}               Shell completions\n```\n\nSession selection for any command that takes an optional `SESSION_ID`:\nexplicit argument → `$STARLOOM_SESSION` → last-used session.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/toadharvard/starloom.git\ncd starloom\nuv pip install -e '.[dev]'\nuv pip install --group dev\n\npre-commit install\npytest\nruff check .\nmypy starloom\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoadharvard%2Fstarloom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoadharvard%2Fstarloom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoadharvard%2Fstarloom/lists"}