{"_id":"@awfixerai/swarm-extension","name":"@awfixerai/swarm-extension","dist-tags":{"latest":"0.0.1-rc.1"},"versions":{"0.0.1-rc.1":{"type":"module","name":"@awfixerai/swarm-extension","version":"0.0.1-rc.1","description":"Swarm orchestration extension for omp","homepage":"https://agent.awfixer.codes","license":"MIT","repository":{"type":"git","url":"git+https://github.com/awfixers-stuff/awfixer-agent.git","directory":"packages/swarm-extension"},"bugs":{"url":"https://github.com/awfixers-stuff/awfixer-agent/issues"},"keywords":["swarm","orchestration","agent","extension"],"bin":{"omp-swarm":"src/cli.ts"},"scripts":{"check":"biome check . && bun run check:types","check:types":"tsgo -p tsconfig.json --noEmit","lint":"biome lint .","fix":"biome check --write --unsafe .","fmt":"biome format --write ."},"dependencies":{"@awfixerai/utils":"0.0.1-rc.1"},"devDependencies":{"@types/bun":"^1.3.14"},"peerDependencies":{"@awfixerai/agent":"^13"},"engines":{"bun":">=1.3.14"},"omp":{"extensions":["./src/extension.ts"]},"_id":"@awfixerai/swarm-extension@0.0.1-rc.1","_integrity":"sha512-rV/U+UbatKRWkMnyG6JbM+m+TGoij1rgYOfoEG1NvDKb2mkS/4HUfyUMFXjEhnxz6SDfwQ96MPDAM0+v85av7A==","_nodeVersion":"24.3.0","_npmVersion":"10.8.3","shasum":"300711b18c368d1c12bbabb4d0cc1a5205ebdefe","dist":{"integrity":"sha512-rV/U+UbatKRWkMnyG6JbM+m+TGoij1rgYOfoEG1NvDKb2mkS/4HUfyUMFXjEhnxz6SDfwQ96MPDAM0+v85av7A==","shasum":"300711b18c368d1c12bbabb4d0cc1a5205ebdefe","tarball":"https://registry.npmjs.org/@awfixerai/swarm-extension/-/swarm-extension-0.0.1-rc.1.tgz","fileCount":12,"unpackedSize":53762,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDyRj21KbzHrBQIxDEpx4h8IKMxfgvsgZQaq4eiR42HmgIhAK2O0NAE7gR7jaRN64O5A7pvdnzEDKQczsha1IQZpQGA"}]},"_npmUser":{"name":"awfixer","email":"wise.jet2897@fastmail.com"},"directories":{},"maintainers":[{"name":"awfixer","email":"wise.jet2897@fastmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/swarm-extension_0.0.1-rc.1_1783015042124_0.07694216445298463"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T17:57:21.944Z","0.0.1-rc.1":"2026-07-02T17:57:22.282Z","modified":"2026-07-02T17:57:22.527Z"},"maintainers":[{"name":"awfixer","email":"wise.jet2897@fastmail.com"}],"description":"Swarm orchestration extension for omp","homepage":"https://agent.awfixer.codes","keywords":["swarm","orchestration","agent","extension"],"repository":{"type":"git","url":"git+https://github.com/awfixers-stuff/awfixer-agent.git","directory":"packages/swarm-extension"},"bugs":{"url":"https://github.com/awfixers-stuff/awfixer-agent/issues"},"license":"MIT","readme":"# Swarm Extension\n\nMulti-agent orchestration for awfixer-agent. Define agent workflows in YAML — pipelines, parallel fan-outs, sequential chains, or any DAG — and run them unattended until completion.\n\nEach agent is a full awfixer-agent subagent with access to every tool: bash, python, read, write, edit, grep, find, fetch, web_search, browser. The orchestrator manages lifecycle and ordering; agents communicate through the shared workspace filesystem.\n\nUse it for anything: research pipelines, code generation, data processing, content creation, analysis workflows, CI-like automation — any multi-step task that benefits from specialized agents working in coordination.\n\n## Setup\n\n```bash\ncd packages/swarm-extension\nbun install\n```\n\n## Running\n\n### Standalone (recommended for long-running work)\n\n```bash\n# Foreground — runs until complete, no timeout:\nomp-swarm path/to/swarm.yaml\n\n# Background — survives terminal close:\nnohup omp-swarm path/to/swarm.yaml \\\n  > pipeline.log 2>&1 & disown\n```\n\nThe standalone runner has no timeout. It runs iteration after iteration until the pipeline finishes or you kill it.\n\n### Inside awfixer-agent (TUI)\n\nRegister the extension in your config (`~/.agent/config.json` or `.omp/config.json`):\n\n```json\n{\n\t\"extensions\": [\"packages/swarm-extension\"]\n}\n```\n\nThen:\n\n```\n/swarm run path/to/swarm.yaml\n/swarm status <name>\n/swarm help\n```\n\n## Monitoring\n\nState persists to `<workspace>/.swarm_<name>/` while the pipeline runs:\n\n```\n.swarm_<name>/\n  state/pipeline.json    # Live pipeline + per-agent status\n  logs/orchestrator.log  # Wave transitions, iteration progress\n  logs/<agent>.log       # Per-agent timestamps and errors\n  context/               # Agent session artifacts\n```\n\nCheck on a running pipeline:\n\n```bash\n# Quick status\ncat workspace/.swarm_mypipeline/state/pipeline.json | python -m json.tool\n\n# Watch the orchestrator log\ntail -f workspace/.swarm_mypipeline/logs/orchestrator.log\n```\n\n---\n\n## YAML Reference\n\nEvery swarm is a single YAML file with a top-level `swarm` key:\n\n```yaml\nswarm:\n  name: my-pipeline # Identifier (state stored in .swarm_<name>/)\n  workspace: ./workspace # Working directory (relative to YAML file location)\n  mode: pipeline # pipeline | parallel | sequential\n  target_count: 10 # Iterations (pipeline mode only, default: 1)\n  model: claude-opus-4-6 # Default model for agents without an override (optional)\n\n  agents:\n    first_agent:\n      role: short-role-name\n      task: |\n        Full instructions for this agent.\n      extra_context: |\n        Optional additional system prompt text.\n      reports_to:\n        - downstream_agent\n      waits_for:\n        - upstream_agent\n      model: claude-sonnet-4-5 # Optional per-agent override\n```\n\n### Top-Level Fields\n\n| Field          | Required | Default         | Description                                                                    |\n| -------------- | -------- | --------------- | ------------------------------------------------------------------------------ |\n| `name`         | yes      | —               | Pipeline identifier. State directory is `.swarm_<name>/`                       |\n| `workspace`    | yes      | —               | Shared working directory. Relative paths resolve from YAML file location       |\n| `mode`         | no       | `sequential`    | Execution mode (see below)                                                     |\n| `target_count` | no       | `1`             | How many times to repeat the full pipeline. Only meaningful in `pipeline` mode |\n| `model`        | no       | session default | Default model for agents that do not set `agents.<name>.model`                |\n\n### Agent Fields\n\n| Field           | Required | Description                                                             |\n| --------------- | -------- | ----------------------------------------------------------------------- |\n| `role`          | yes      | Short role identifier — becomes the agent's system prompt               |\n| `task`          | yes      | Complete instructions sent as user prompt. Use YAML `\\|` for multi-line |\n| `extra_context` | no       | Additional text appended to system prompt                               |\n| `model`         | no       | Model override for this agent only                                      |\n| `reports_to`    | no       | List of agent names that depend on this agent                           |\n| `waits_for`     | no       | List of agent names this agent depends on                               |\n\n### Execution Modes\n\n**`pipeline`** — Repeat the full agent graph `target_count` times. Each iteration runs all waves in order. Use for accumulative work: \"find 50 things, one per iteration.\"\n\n**`sequential`** — Run agents once, chained by declaration order (unless explicit dependencies override). The default mode.\n\n**`parallel`** — Run all agents simultaneously (unless explicit dependencies impose ordering).\n\n### Dependency Resolution\n\nThe orchestrator builds a DAG from `waits_for` and `reports_to`, then groups agents into **waves** using topological sort. Agents in the same wave run in parallel; waves execute in sequence.\n\n- `waits_for: [a, b]` — this agent won't start until both `a` and `b` finish\n- `reports_to: [x]` — equivalent to `x` having `waits_for: [this_agent]`\n- No explicit deps + `pipeline`/`sequential` mode — agents chain by YAML declaration order\n- No explicit deps + `parallel` mode — all agents run in one wave\n- Cycles are detected and rejected before execution\n\n---\n\n## Patterns\n\n### Pipeline: Iterative Accumulation\n\nRun the same agent chain N times. Each iteration builds on the previous one's output. Good for: research collection, data gathering, batch processing, iterative refinement.\n\n```yaml\nswarm:\n  name: research-collector\n  workspace: ./workspace\n  mode: pipeline\n  target_count: 25\n  model: claude-opus-4-6\n\n  agents:\n    finder:\n      role: researcher\n      task: |\n        Find ONE new source on the topic defined in workspace/topic.md.\n\n        1. Read processed.txt to see what's already been found\n        2. Use web_search to find a new, high-quality source\n        3. Append the URL to processed.txt\n        4. Write the URL to signals/finder_out.txt: FOUND:<url>\n\n    analyzer:\n      role: analyst\n      task: |\n        Read signals/finder_out.txt for the URL.\n        Fetch the page and extract key findings.\n        Read tracking/count.txt, increment it, write back.\n        Write analysis to analyzed/item_<N>.md\n        Write to signals/analyzer_out.txt: DONE:<N>\n\n    compiler:\n      role: technical-writer\n      task: |\n        Read signals/analyzer_out.txt for the item number.\n        Read analyzed/item_<N>.md.\n        Append a summary to output/report.md under a new section.\n```\n\nAfter 25 iterations: 25 sources found, analyzed, and compiled into a single report.\n\n### Fan-In: Parallel Specialists\n\nMultiple agents work independently, one synthesizer combines results. Good for: multi-perspective analysis, parallel code review, comprehensive audits.\n\n```yaml\nswarm:\n  name: codebase-audit\n  workspace: ./workspace\n\n  agents:\n    security:\n      role: security-auditor\n      task: |\n        Audit all code in src/ for security vulnerabilities.\n        Write findings to reports/security.md with severity ratings.\n      reports_to:\n        - lead\n\n    performance:\n      role: performance-analyst\n      task: |\n        Profile and analyze src/ for performance bottlenecks.\n        Write findings to reports/performance.md with benchmarks.\n      reports_to:\n        - lead\n\n    architecture:\n      role: architecture-reviewer\n      task: |\n        Review src/ for architectural issues, coupling, and tech debt.\n        Write findings to reports/architecture.md with refactoring suggestions.\n      reports_to:\n        - lead\n\n    lead:\n      role: engineering-lead\n      task: |\n        Read all reports in reports/.\n        Create a prioritized action plan in output/action_plan.md.\n        Rank issues by impact and effort.\n      waits_for:\n        - security\n        - performance\n        - architecture\n```\n\nExecution: security + performance + architecture run in parallel (wave 1), lead starts after all three complete (wave 2).\n\n### Sequential Chain: Staged Handoff\n\nLinear progression through distinct phases. Good for: content pipelines, multi-stage processing, review chains.\n\n```yaml\nswarm:\n  name: blog-post\n  workspace: ./workspace\n  mode: sequential\n\n  agents:\n    researcher:\n      role: researcher\n      task: |\n        Research the topic in topic.md using web_search.\n        Write raw findings and source links to research/notes.md\n\n    writer:\n      role: technical-writer\n      task: |\n        Read research/notes.md.\n        Write a complete blog post draft to drafts/post.md.\n        Include code examples where relevant.\n\n    editor:\n      role: editor\n      task: |\n        Read drafts/post.md.\n        Fix grammar, improve flow, tighten prose.\n        Rewrite to drafts/post.md.\n\n    reviewer:\n      role: senior-reviewer\n      task: |\n        Read drafts/post.md.\n        Check technical accuracy against research/notes.md.\n        Add an editorial note at top if issues found, otherwise\n        copy to output/final.md.\n```\n\nExecution: researcher -> writer -> editor -> reviewer, one after another.\n\n### Diamond: Fan-Out Then Fan-In\n\nOne planner, parallel workers, one integrator. Good for: divide-and-conquer, modular code generation, multi-file refactors.\n\n```yaml\nswarm:\n  name: feature-implementation\n  workspace: ./workspace\n\n  agents:\n    planner:\n      role: architect\n      task: |\n        Read the feature spec in spec.md.\n        Break it into independent implementation tasks.\n        Write the plan to plan.md with file assignments.\n      reports_to:\n        - api\n        - ui\n        - tests\n\n    api:\n      role: backend-developer\n      task: |\n        Read plan.md for your assigned files.\n        Implement the API layer. Write to src/api/.\n      reports_to:\n        - integrator\n\n    ui:\n      role: frontend-developer\n      task: |\n        Read plan.md for your assigned files.\n        Implement the UI components. Write to src/ui/.\n      reports_to:\n        - integrator\n\n    tests:\n      role: test-engineer\n      task: |\n        Read plan.md for the full feature scope.\n        Write integration tests to tests/.\n      reports_to:\n        - integrator\n\n    integrator:\n      role: tech-lead\n      task: |\n        Read plan.md and review all code in src/ and tests/.\n        Wire everything together. Fix any integration issues.\n        Run the tests and fix failures.\n        Write status to output/done.md.\n```\n\nExecution: planner (wave 1) -> api + ui + tests in parallel (wave 2) -> integrator (wave 3).\n\n### Hybrid: Mixed Dependencies\n\nAny DAG is valid. Combine patterns freely.\n\n```yaml\nswarm:\n  name: data-pipeline\n  workspace: ./workspace\n  mode: pipeline\n  target_count: 10\n\n  agents:\n    scraper_a:\n      role: web-scraper\n      task: |\n        Scrape data source A. Write to raw/source_a.json\n      reports_to:\n        - transformer\n\n    scraper_b:\n      role: web-scraper\n      task: |\n        Scrape data source B. Write to raw/source_b.json\n      reports_to:\n        - transformer\n\n    transformer:\n      role: data-engineer\n      task: |\n        Read raw/source_a.json and raw/source_b.json.\n        Clean, normalize, merge. Write to processed/merged.json\n      reports_to:\n        - loader\n        - validator\n\n    validator:\n      role: qa-analyst\n      task: |\n        Read processed/merged.json.\n        Validate schema, check for anomalies.\n        Write report to qa/validation.md\n\n    loader:\n      role: data-engineer\n      task: |\n        Read processed/merged.json.\n        Append to output/dataset.jsonl\n```\n\nExecution per iteration: scraper_a + scraper_b (wave 1) -> transformer (wave 2) -> loader + validator (wave 3).\n\n---\n\n## Writing Agent Tasks\n\n### What Agents Can Do\n\nEach agent is a full awfixer-agent session. It can:\n\n- **bash/python**: Run commands, scripts, install packages, process data\n- **read/write/edit**: Create and modify files in the workspace\n- **grep/find**: Search the workspace (or anywhere on disk)\n- **web_search**: Search the internet (via configured provider)\n- **fetch**: Download web pages, APIs, documents\n- **browser**: Navigate websites, scrape dynamic content, take screenshots\n\n### Inter-Agent Communication\n\nThe orchestrator starts and stops agents in the right order. It does **not** pass data between them. Agents communicate through files in the shared workspace.\n\nDesign your own protocol. Common patterns:\n\n**Signal files** — lightweight status flags an agent writes when done:\n\n```\nsignals/finder_out.txt    -> \"FOUND:https://example.com\"\nsignals/analyzer_out.txt  -> \"DONE:42\"\nsignals/reviewer_out.txt  -> \"APPROVED\" or \"REJECTED:reason\"\n```\n\n**Structured output** — detailed results other agents read:\n\n```\nanalyzed/item_1.md        -> Full analysis document\nresults/report.json       -> Machine-readable data\noutput/final.docx         -> Accumulated deliverable\n```\n\n**Tracking files** — prevent duplicate work across pipeline iterations:\n\n```\nprocessed.txt             -> Items already handled (one per line)\ntracking/count.txt        -> Current item counter\ntracking/status.json      -> Cumulative state\n```\n\n### Tips for Reliable Agents\n\n- **Be explicit about paths.** Agents start fresh each iteration — they don't remember previous runs. Tell them exactly where to read input and write output.\n- **Check existing state.** In pipeline mode, tell agents to read tracking files before doing work: \"Read processed.txt to avoid duplicates.\"\n- **Use numbered outputs.** `item_1.md`, `item_2.md` etc. so iterations don't clobber each other.\n- **Handle failure.** Tell agents what to do when things go wrong: \"If the source lacks depth, write SKIP to signals/out.txt and explain why.\"\n- **Keep signal files simple.** One line, parseable format. Complex data goes in structured output files.\n- **Scope the task tightly.** An agent that tries to do five things will do zero well. One clear objective per agent.\n\n---\n\n## Models\n\nAny model configured in agent works. Set a swarm default and optionally override per agent:\n\n```yaml\nswarm:\n  model: claude-opus-4-6\n  agents:\n    writer:\n      role: technical-writer\n      task: |\n        Write the draft.\n    reviewer:\n      role: reviewer\n      model: claude-sonnet-4-5\n      task: |\n        Review the draft.\n```\n\nPrecedence: `agents.<name>.model` → `swarm.model` → session default. Check `packages/ai/src/models.json` for available model IDs.\n\n---\n\n## Architecture\n\n```\nsrc/extension.ts      TUI entry point (registers /swarm command)\nsrc/cli.ts   Standalone runner (no TUI, no timeout)\nsrc/swarm/\n  schema.ts           YAML parsing + validation\n  dag.ts              Dependency graph, cycle detection, topological sort\n  executor.ts         Spawns agents via awfixer-agent's runSubprocess\n  pipeline.ts         Iteration loop + wave controller\n  state.ts            Filesystem state persistence\n  render.ts           Progress display formatting\n```\n","readmeFilename":"README.md","_rev":"1-0cbf381798766cfe24c60af10a240410"}