{"id":47599226,"url":"https://github.com/cosmix/loom","last_synced_at":"2026-04-16T04:01:58.520Z","repository":{"id":329652657,"uuid":"1119193962","full_name":"cosmix/loom","owner":"cosmix","description":"A Rust-based agent orchestrator enabling a swarm of Claude Code instances building software.","archived":false,"fork":false,"pushed_at":"2026-04-11T11:09:37.000Z","size":5843,"stargazers_count":39,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-11T12:26:04.632Z","etag":null,"topics":["agentic-coding","agents","claude","claude-code","skills"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cosmix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-12-18T22:33:20.000Z","updated_at":"2026-04-11T11:09:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cosmix/loom","commit_stats":null,"previous_names":["cosmix/claude-code-setup","cosmix/loom"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cosmix/loom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Floom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Floom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Floom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Floom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cosmix","download_url":"https://codeload.github.com/cosmix/loom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Floom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"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":["agentic-coding","agents","claude","claude-code","skills"],"created_at":"2026-04-01T18:36:45.265Z","updated_at":"2026-04-16T04:01:58.475Z","avatar_url":"https://github.com/cosmix.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Loom\n\nLoom is an agent orchestration system for Claude Code. It coordinates AI agent sessions across git worktrees, enabling parallel task execution with crash recovery, context handoffs, and structured verification.\n\n## What Loom Solves\n\n- Context exhaustion in long agent sessions\n- Lost execution state when sessions crash or end\n- Manual handoff/restart overhead\n- Weak coordination across multi-stage work\n\n## Key Capabilities\n\n- Persistent orchestration state in `.work/`\n- Git worktree isolation for parallel stage execution\n- Stage-aware signals and recovery flows\n- Goal-backward verification (`artifacts`, `wiring`, `wiring_tests`, `dead_code_check`)\n- Plan-level and stage-level sandbox controls\n- Optional agent teams guidance in stage signals\n\n## Platform Support\n\n- Linux: primary development and full CI test runs\n- macOS: supported for build/terminal integration, CI does build-only verification\n- Windows: not supported (WSL may work but is best-effort)\n\n## Quick Start\n\nLoom is under active development and not yet published to GitHub Releases. You need to build locally with the Rust toolchain installed.\n\n### 1. Install Loom\n\n```bash\ngit clone https://github.com/cosmix/loom.git\ncd loom\nbash ./dev-install.sh\n```\n\n`dev-install.sh` builds the release binary (`cargo build --release`) and runs `install.sh`, which installs `loom-*` prefixed agents and skills (non-destructively, preserving user customizations), hooks, and configuration into `~/.claude/` and the CLI binary to `~/.local/bin/loom`. Orchestration rules are written directly to `~/.claude/CLAUDE.md` (existing file is backed up).\n\n### 2. Write a Plan\n\nPlans are how loom knows what to build. Open Claude Code in your target project and use the `/loom-plan-writer` skill to create one:\n\n```bash\ncd /path/to/project\nclaude  # start Claude Code CLI\n```\n\nInside the Claude Code session:\n\n1. Enter plan mode (`/plan`)\n2. Load the plan-writing skill by typing `/loom-plan-writer`\n3. Describe what you want to build and discuss with Claude\n4. Claude will write the plan to `doc/plans/PLAN-\u003cname\u003e.md`\n\n### 3. Run Loom\n\nOnce your plan is written:\n\n```bash\nloom init doc/plans/PLAN-\u003cname\u003e.md\nloom run\nloom status --live\nloom stop\n```\n\n`loom init` parses the plan, creates stage state, and installs/configures project hook wiring automatically. For an existing repo that is missing Claude Code hook setup, run `loom repair --fix`.\n\n### What Gets Installed\n\n| Location | Contents |\n| --- | --- |\n| `~/.claude/agents/loom-*.md` | Specialized subagents (per-item, non-destructive) |\n| `~/.claude/skills/loom-*/` | Domain knowledge modules (per-item, non-destructive) |\n| `~/.claude/hooks/loom/` | Session lifecycle hooks |\n| `~/.claude/CLAUDE.md` | Orchestration rules |\n| `~/.local/bin/loom` | Loom CLI |\n\n## Core Workflow\n\n1. Open Claude Code, enter plan mode (`/plan`), and use `/loom-plan-writer` to write a plan to `doc/plans/`.\n2. Run `loom init \u003cplan-path\u003e` to parse metadata and create stage state.\n3. Run `loom run` to start daemon + orchestrator.\n4. Track progress with `loom status --live`.\n5. Recover, verify, merge, or retry stages as needed.\n\n## CLI Reference\n\n### Primary Commands\n\n```bash\nloom init \u003cplan-path\u003e [--clean]\nloom run [--manual] [--max-parallel N] [--foreground] [--watch] [--no-merge]\nloom status [--live] [--compact] [--verbose]\nloom stop\nloom resume \u003cstage-id\u003e\nloom check \u003cstage-id\u003e [--suggest]\nloom diagnose \u003cstage-id\u003e\n```\n\n### Stage Commands\n\n```bash\nloom stage complete \u003cstage-id\u003e [--session \u003cid\u003e] [--no-verify] [--force-unsafe --assume-merged]\nloom stage block \u003cstage-id\u003e \u003creason\u003e\nloom stage reset \u003cstage-id\u003e [--hard] [--kill-session]\nloom stage waiting \u003cstage-id\u003e\nloom stage resume \u003cstage-id\u003e\nloom stage hold \u003cstage-id\u003e\nloom stage release \u003cstage-id\u003e\nloom stage skip \u003cstage-id\u003e [--reason \u003ctext\u003e]\nloom stage retry \u003cstage-id\u003e [--force] [--context \u003cmessage\u003e]\nloom stage merge [stage-id] [--resolved]\nloom stage verify \u003cstage-id\u003e [--no-reload] [--dry-run]\nloom stage human-review \u003cstage-id\u003e [--approve|--force-complete|--reject \u003creason\u003e]\nloom stage dispute-criteria \u003cstage-id\u003e \u003creason\u003e\n```\n\n### Stage Outputs\n\n```bash\nloom stage output set \u003cstage-id\u003e \u003ckey\u003e \u003cvalue\u003e [--description \u003ctext\u003e]\nloom stage output get \u003cstage-id\u003e \u003ckey\u003e\nloom stage output list \u003cstage-id\u003e\nloom stage output remove \u003cstage-id\u003e \u003ckey\u003e\n```\n\n### Knowledge / Memory\n\n```bash\nloom knowledge show [file]\nloom knowledge update \u003cfile\u003e \u003ccontent\u003e\nloom knowledge init\nloom knowledge list\nloom knowledge check [--min-coverage N] [--src-path \u003cpath\u003e] [--quiet]\nloom knowledge gc [--max-file-lines N] [--max-total-lines N] [--quiet]\nloom knowledge bootstrap [--model \u003cname\u003e] [--skip-map] [--quick]\n\nloom memory note \u003ctext\u003e [--stage \u003cid\u003e]\nloom memory decision \u003ctext\u003e [--context \u003cwhy\u003e] [--stage \u003cid\u003e]\nloom memory change \u003ctext\u003e [--stage \u003cid\u003e]\nloom memory question \u003ctext\u003e [--stage \u003cid\u003e]\nloom memory query \u003csearch\u003e [--stage \u003cid\u003e]\nloom memory list [--stage \u003cid\u003e] [--entry-type \u003ctype\u003e]\nloom memory show [--stage \u003cid\u003e] [--all]\n```\n\n`loom knowledge bootstrap` launches a Claude-driven exploration session that populates `doc/loom/knowledge/`. By default it runs a deep `loom map` pass first, then starts Claude with permission to update knowledge files via `loom knowledge update`.\n\n### Other Commands\n\n```bash\nloom sessions list\nloom sessions kill \u003csession-id...\u003e | --stage \u003cstage-id\u003e\nloom worktree list\nloom worktree remove \u003cstage-id\u003e\nloom graph\nloom map [--deep] [--focus \u003carea\u003e] [--overwrite]\nloom repair [--fix]\nloom clean [--all|--worktrees|--sessions|--state]\nloom self-update\nloom completions [\u003cshell\u003e] [--install] [--migrate]\n```\n\n## Plan Format\n\nPlans live in `doc/plans/` with metadata in fenced YAML between loom markers.\n\n````markdown\n# PLAN-0001: Feature Name\n\n\u003c!-- loom METADATA --\u003e\n```yaml\nloom:\n  version: 1\n  sandbox:\n    enabled: true\n  stages:\n    - id: implement-api\n      name: Implement API\n      description: Add endpoint + tests\n      working_dir: \".\"\n      stage_type: standard\n      dependencies: []\n      acceptance:\n        - \"cargo test\"\n        - command: \"cargo test api_integration::returns_200\"\n          stdout_contains: [\"test result: ok\"]\n      files:\n        - \"loom/src/**/*.rs\"\n      artifacts:\n        - \"loom/src/api/*.rs\"\n      wiring:\n        - source: \"loom/src/main.rs\"\n          pattern: \"mod api;\"\n          description: \"API module registered\"\n      execution_mode: team\n\n    - id: integration-verify\n      name: Integration Verify\n      working_dir: \".\"\n      stage_type: integration-verify\n      dependencies: [\"implement-api\"]\n      acceptance:\n        - \"cargo test --all-targets\"\n        - command: \"cargo test api_integration::returns_200\"\n          stdout_contains: [\"test result: ok\"]\n```\n\u003c!-- END loom METADATA --\u003e\n````\n\n### Stage Fields\n\n| Field | Required | Notes |\n| --- | --- | --- |\n| `id` | Yes | Stage identifier |\n| `name` | Yes | Human-readable title |\n| `working_dir` | Yes | Relative execution directory (`.` allowed) |\n| `description` | No | Optional summary |\n| `dependencies` | No | Upstream stage IDs |\n| `acceptance` | Conditionally required | Shell criteria (strings or extended objects with stdout_contains etc.) |\n| `setup` | No | Setup commands |\n| `files` | No | File glob scope |\n| `stage_type` | No | `standard` (default), `knowledge`, `integration-verify` |\n| `artifacts` / `wiring` | Conditionally required | Required for `standard` and `integration-verify` (acceptance OR goal-backward) |\n| `wiring_tests` / `dead_code_check` | No | Extended verification |\n| `context_budget` | No | Context threshold (%) for handoff |\n| `sandbox` | No | Per-stage sandbox override |\n| `execution_mode` | No | `single` (default) or `team` hint |\n\n### Stage Type Behavior\n\n- `knowledge`: knowledge/bootstrap work, different verification expectations\n- `standard`: implementation stage; must define goal-backward checks\n- `integration-verify`: final quality gate combining code review and functional verification; must define goal-backward checks\n\n## Verification Model\n\n`loom check \u003cstage-id\u003e` validates outcomes, not just compilation/tests:\n\n- `acceptance`: shell criteria (simple strings or extended objects with `stdout_contains`, `exit_code`, etc.)\n- `artifacts`: real implementation files exist\n- `wiring`: critical integration links exist\n- `wiring_tests`: runtime integration checks\n- `dead_code_check`: detect unused code via command output patterns\n\nFor `standard` and `integration-verify` stages, acceptance criteria or at least one goal-backward check must be defined.\n\n## Sandbox Configuration\n\nLoom supports plan-level defaults plus stage-level overrides.\n\n```yaml\nloom:\n  version: 1\n  sandbox:\n    enabled: true\n    auto_allow: true\n    excluded_commands: [\"loom\"]\n    filesystem:\n      deny_read:\n        - \"~/.ssh/**\"\n        - \"~/.aws/**\"\n        - \"../../**\"\n        - \"../.worktrees/**\"\n      deny_write:\n        - \"../../**\"\n        - \"doc/loom/knowledge/**\"\n      allow_write:\n        - \"src/**\"\n    network:\n      allowed_domains: [\"github.com\", \"crates.io\"]\n      additional_domains: []\n      allow_local_binding: false\n      allow_unix_sockets: []\n```\n\nNote: knowledge file writes are intentionally protected by sandbox defaults; knowledge updates should be done via `loom knowledge ...` commands.\n\n## Agent Teams (Experimental)\n\nLoom enables agent teams in spawned sessions (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) and injects team-usage guidance into stage signals.\n\nUse teams when work needs coordination/discussion across agents (multi-dimension review, exploratory analysis). Use subagents for independent, concrete file-level tasks.\n\n## State Layout\n\n```text\nproject/\n├── .work/\n│   ├── config.toml\n│   ├── stages/\n│   ├── sessions/\n│   ├── signals/\n│   └── handoffs/\n├── .worktrees/\n└── doc/plans/\n```\n\n## Shell Completions\n\nLoom provides context-aware tab completions for all commands, subcommands, flags, and dynamic values (stage IDs, plan files, session IDs, knowledge files).\n\n### Quick Install\n\n```bash\nloom completions --install\n```\n\nAuto-detects your shell from `$SHELL` and writes completions to the standard location:\n\n| Shell | Install Path |\n| --- | --- |\n| Bash | `~/.local/share/bash-completion/completions/loom` |\n| Zsh | `~/.zfunc/_loom` |\n| Fish | `~/.config/fish/completions/loom.fish` |\n\nFollow the printed post-install instructions to activate (e.g., for zsh, ensure `fpath=(~/.zfunc $fpath)` appears before `compinit` in `~/.zshrc`).\n\n### Manual Setup\n\nYou can also write the completion script to a file yourself:\n\n```bash\n# bash\nloom completions bash \u003e ~/.local/share/bash-completion/completions/loom\n\n# zsh — ensure ~/.zfunc is in fpath (add before compinit in ~/.zshrc):\n#   fpath=(~/.zfunc $fpath)\n#   autoload -Uz compinit \u0026\u0026 compinit\nmkdir -p ~/.zfunc\nloom completions zsh \u003e ~/.zfunc/_loom\n\n# fish\nloom completions fish \u003e ~/.config/fish/completions/loom.fish\n```\n\n### Migrating from Older Versions\n\nOlder versions of loom used `clap_complete` and required an `eval` line in your shell RC file that ran a subprocess on every shell startup. The new system writes a static script to disk and only calls `loom` at actual tab-completion time, which means faster shell startup and completions that work even before `loom` is in your `PATH`.\n\nTo check whether you need to migrate:\n\n```bash\nloom completions --migrate\n```\n\nThis scans for two things:\n\n1. **`eval` lines** in RC files (`.bashrc`, `.zshrc`, etc.) like `eval \"$(loom completions zsh)\"` — these should be removed\n2. **Stale completion files** containing old `clap_complete` markers — these need to be regenerated\n\nIf issues are found, follow the printed instructions. Typically: remove the `eval` line from your RC file, then run `loom completions --install` to write the new file-based completion script.\n\n### What's Completed\n\n- Commands and subcommands (`loom stage \u003cTAB\u003e` shows all stage subcommands)\n- Flags (`loom run --\u003cTAB\u003e` shows available flags)\n- Stage IDs with smart filtering (`loom stage complete \u003cTAB\u003e` shows only executing stages)\n- Plan files, session IDs, knowledge files (including aliases like `deps`, `tech`)\n- Model names, trigger types, and more\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmix%2Floom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosmix%2Floom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmix%2Floom/lists"}