{"id":23527087,"url":"https://github.com/jenslys/sinfonia","last_synced_at":"2026-02-13T22:54:51.391Z","repository":{"id":269624786,"uuid":"908020084","full_name":"jenslys/sinfonia","owner":"jenslys","description":"A beautiful process runner for parallel commands with interactive filtering and real-time output control.","archived":false,"fork":false,"pushed_at":"2025-04-05T10:37:59.000Z","size":88,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T11:29:39.123Z","etag":null,"topics":["bun","process","process-manager","processes"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/sinfonia","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/jenslys.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}},"created_at":"2024-12-24T22:22:33.000Z","updated_at":"2025-04-05T10:38:03.000Z","dependencies_parsed_at":"2025-04-05T11:25:33.257Z","dependency_job_id":"fce09a8a-939f-4fee-af15-d5ac5f7e01eb","html_url":"https://github.com/jenslys/sinfonia","commit_stats":null,"previous_names":["jenslys/sinfonia"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenslys%2Fsinfonia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenslys%2Fsinfonia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenslys%2Fsinfonia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenslys%2Fsinfonia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenslys","download_url":"https://codeload.github.com/jenslys/sinfonia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254120178,"owners_count":22017954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bun","process","process-manager","processes"],"created_at":"2024-12-25T20:11:58.183Z","updated_at":"2026-02-13T22:54:51.386Z","avatar_url":"https://github.com/jenslys.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sinfonia\n\nA modern, interactive process manager for developers.\n\n[![npm version](https://badge.fury.io/js/sinfonia.svg)](https://badge.fury.io/js/sinfonia)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\n![Preview](https://github.com/user-attachments/assets/5fadbe2d-8a22-4c18-af7f-9f8455e73bfa)\n\n\u003e **sinfonia** _(n.)_ - from Italian, meaning \"symphony\": a harmonious combination of elements working together as one, just like an orchestra performing multiple parts in perfect coordination.\n\n## Features\n\n- **Parallel Execution:** Execute and monitor multiple commands concurrently in a single terminal session.\n- **Process Grouping:** Organize related services (e.g., \"frontend\", \"backend\") for bulk control and isolated filtering.\n- **Dependency Management:** Define start orders and wait conditions (e.g., wait for DB port) using a declarative configuration.\n- **Interactive Filtering:** Focus on specific process or group outputs using arrow keys.\n- **Real-time Search:** Search through logs and process names instantly.\n- **Process Control:** Interactively start, stop, and restart individual processes or entire groups.\n- **State Management:** Robust handling of process lifecycles and states.\n- **Configurable Output:** Customize buffer sizes and log file paths.\n- **JSON Schema:** Full IDE support with validation for configuration files.\n\n## Installation\n\n```bash\n# Using bun\nbun install -g sinfonia\n\n# Using npm\nnpm install -g sinfonia\n\n# Using yarn\nyarn global add sinfonia\n```\n\n## Usage\n\nSinfonia supports both quick ad-hoc commands and robust declarative configurations.\n\n### Ad-hoc Execution (CLI)\n\nPerfect for simple usage without dependencies:\n\n```bash\n# Single command\nsinfonia \"web=npm run dev\"\n\n# Multiple commands\nsinfonia \"web=npm run dev\" \"api=npm run server\"\n\n# With groups\nsinfonia \"frontend:web=npm run dev\" \"backend:api=npm run server\"\n```\n\n**CLI Features:**\n- Basic command running (`name=cmd`)\n- Basic grouping (`group:name=cmd`)\n- Buffer size (`-b, --buffer-size`)\n- Log file (`-l, --log-file`)\n- Config file (`-c, --config`)\n\n### Declarative Configuration (sinfonia.json)\n\nFor complex setups with dependencies, use a config file. You can generate a starter config with:\n\n```bash\n# Generate a starter config file (sinfonia.json)\nsinfonia init\n\n# Generate and overwrite existing config\nsinfonia init --force\n```\n\nThen run it with:\n\n```bash\n# Uses sinfonia.json by default\nsinfonia\n\n# Or specify a different config file\nsinfonia -c custom.json\n```\n\n**Config Mode Features:**\n- All CLI features\n- Dependencies between commands (`dependsOn`)\n- Ready patterns for dependencies (`readyPatterns`)\n- Per-command and per-group color customization\n- Reusable configuration\n\nExample config file (`sinfonia.json`):\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/jenslys/sinfonia/main/schema.json\",\n  \"commands\": [\n    {\n      \"name\": \"DB\",\n      \"cmd\": \"docker compose up\",\n      \"color\": \"blue\"\n    },\n    {\n      \"name\": \"API\",\n      \"cmd\": \"npm run api\",\n      \"group\": \"BACKEND\",\n      \"dependsOn\": [\"DB\"],\n      \"readyPatterns\": {\n        \"db\": \"Database system is ready\"\n      }\n    },\n    {\n      \"name\": \"WORKER\",\n      \"cmd\": \"npm run worker\",\n      \"group\": \"BACKEND\",\n      \"dependsOn\": [\"DB\"],\n      \"readyPatterns\": {\n        \"db\": \"Database system is ready\"\n      }\n    },\n    {\n      \"name\": \"WEB\",\n      \"cmd\": \"npm run dev\",\n      \"group\": \"FRONTEND\",\n      \"dependsOn\": [\"API\"],\n      \"readyPatterns\": {\n        \"api\": \"Server started on port\"\n      }\n    }\n  ],\n  \"groups\": [\n    {\n      \"name\": \"BACKEND\",\n      \"color\": \"cyan\"\n    },\n    {\n      \"name\": \"FRONTEND\",\n      \"color\": \"magenta\"\n    }\n  ],\n  \"options\": {\n    \"bufferSize\": 100\n  }\n}\n```\n\nThe config file supports JSON Schema validation for better IDE support and validation. Groups are automatically created from command `group` fields - you only need to define them in the `groups` array if you want to customize their properties (like colors).\n\n### Options\n\n```bash\n# Custom buffer size\nsinfonia -b 200 \"web=npm run dev\" \"api=npm run server\"\n\n# Enable logging to file\nsinfonia -l \"output_{timestamp}.log\" \"web=npm run dev\" \"api=npm run server\"\n\n# Use custom config file (defaults to sinfonia.json)\nsinfonia -c my-config.json\n```\n\n## Controls\n\n| Key      | Action                |\n|----------|----------------------|\n| `↑/↓`    | Navigate processes/groups |\n| `r`      | Restart process/group |\n| `s`      | Stop/Start process/group |\n| `f`      | Search in logs |\n| `j/k`    | Scroll logs up/down |\n| `u/d`    | Page up/down (half screen) |\n| `Space`  | Toggle auto-follow logs |\n| `Ctrl+C` | Exit all processes   |\n\n### Log Navigation\n\nThe log viewer supports both manual and auto-follow modes:\n\n- Use `j/k` for line-by-line scrolling\n- Use `u/d` for faster page-based scrolling\n- Press `Space` to toggle between manual scrolling and auto-follow mode\n- Auto-follow mode automatically shows the latest logs as they arrive\n- Any scroll action automatically switches to manual mode\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenslys%2Fsinfonia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenslys%2Fsinfonia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenslys%2Fsinfonia/lists"}