taskswarm-cli 0.1.0__py3-none-any.whl

taskswarm_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: taskswarm-cli
+Version: 0.1.0
+Summary: Self-hosted event server that pushes a notification the instant a parallel coding-agent session blocks, needs review, fails, or finishes.
+Project-URL: Homepage, https://github.com/RudrenduPaul/taskswarm
+Project-URL: Repository, https://github.com/RudrenduPaul/taskswarm
+Project-URL: Bug Tracker, https://github.com/RudrenduPaul/taskswarm/issues
+Project-URL: Changelog, https://github.com/RudrenduPaul/taskswarm/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/RudrenduPaul/taskswarm/blob/main/docs/getting-started.md
+Project-URL: Author - Rudrendu Paul, https://github.com/RudrenduPaul
+Project-URL: Author - Sourav Nandy, https://github.com/Sourav-nandy-ai
+Author: Rudrendu Paul, Sourav Nandy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,coding-agent,dashboard,event-server,multi-agent,notifications,orchestration,self-hosted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.0; extra == 'dev'
+Requires-Dist: pytest<9,>=7.0; extra == 'dev'
+Requires-Dist: twine<7,>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# taskswarm (Python)
+
+Self-hosted event server that pushes a notification the instant a parallel
+coding-agent session blocks, needs review, fails, or finishes.
+
+[![PyPI version](https://img.shields.io/pypi/v/taskswarm.svg)](https://pypi.org/project/taskswarm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/RudrenduPaul/taskswarm/blob/main/LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskswarm.svg)](https://pypi.org/project/taskswarm/)
+[![CI](https://github.com/RudrenduPaul/taskswarm/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/taskswarm/actions/workflows/ci.yml)
+
+## Why this exists
+
+Running three or four coding-agent sessions in parallel turns into a
+tab-switching problem: nothing pushes state to you, so you find out a
+session has been sitting on a permission prompt for ten minutes only by
+polling terminals by eye. TaskSwarm closes that gap: every agent session
+reports its state to a small local HTTP server, and the instant one
+transitions to `blocked`, `needs-review`, `failed`, or `done`, TaskSwarm
+fires a local OS notification and updates a live status page over
+Server-Sent Events. No polling, no account, no cloud dependency by default.
+
+This package is the **Python distribution** of TaskSwarm -- a genuine,
+independent port of the server, CLI, event schema, and notification logic,
+not a wrapper around the Node binary. It has zero runtime dependencies: no
+HTTP framework, no schema-validation library, nothing beyond the Python
+standard library.
+
+## Install
+
+Live on PyPI as `taskswarm`:
+
+```bash
+pip install taskswarm
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add taskswarm
+```
+
+The complementary JS/TS distribution is already live on npm as
+`taskswarm-cli` (`npm install -g taskswarm-cli`, or `npx taskswarm-cli
+start` with no install step) -- see the
+[project README](https://github.com/RudrenduPaul/taskswarm#readme) for
+that package. Both are first-class and maintained together; neither is a
+replacement for the other.
+
+## Quickstart
+
+```bash
+# Terminal 1: start the server
+taskswarm start
+# TaskSwarm server listening on http://127.0.0.1:4173
+# Live status page: http://127.0.0.1:4173/?token=<your-token>
+
+# Terminal 2: report a session's status as it works
+taskswarm agent report-status --task my-fix --repo ./api --state running
+taskswarm agent report-status --task my-fix --repo ./api --state done
+```
+
+Open the live status page URL printed by `start`. The row for `my-fix`
+updates the instant each `report-status` call lands, no refresh.
+
+Or call the library directly, in-process, without a subprocess:
+
+```python
+from taskswarm import start_server
+from taskswarm.adapters import GenericAdapter
+from taskswarm.client.api_client import post_event
+
+running = start_server()
+adapter = GenericAdapter()
+event_input = adapter.to_event_input(
+    {"session_id": "my-fix", "repo": "./api", "status": "done", "agent_type": "generic"}
+)
+event = post_event(running.config.to_dict(), event_input)
+print(event["session_id"], "->", event["status"])
+running.close()
+```
+
+## What it does
+
+- **Event server, not a board you have to keep open.** `taskswarm start`
+  boots an HTTP+SSE server (stdlib `http.server`, no framework dependency)
+  that accepts `POST /events`, serves `GET /events` for current session
+  state, and streams new events over `GET /live` (Server-Sent Events) to
+  the bundled live status page.
+- **Push notification on the four states that mean "look at this now."**
+  The moment a session's status transitions to `blocked`, `needs-review`,
+  `failed`, or `done`, TaskSwarm fires a native OS notification
+  (`osascript` on macOS, a terminal-bell console fallback elsewhere).
+  Notification dedup keys on the `(status, blocked_reason)` pair, so a
+  second, different permission prompt still notifies even though the
+  status (`needs-review`) didn't change.
+- **A wrapper-script adapter for any agent.**
+  `taskswarm agent report-status --task <id> --repo <path> --state <state>`
+  is the one primitive every integration is built on -- callable from any
+  script wrapping any CLI agent (Codex, Cursor, or anything else).
+- **A Claude Code hooks adapter**, ported with the same behavior as the npm
+  package's: `taskswarm hooks install claude-code` writes `Stop` and
+  `Notification` hook entries into `.claude/settings.json`, pointed at the
+  exact, already-installed console script on disk (never a floating PATH
+  lookup re-resolved on every hook fire).
+- **A bearer-token-gated local API, bound to loopback by default.**
+  `POST /events` and the live page both require the token TaskSwarm
+  generates on first run (`~/.taskswarm/config.json`, written `0600`).
+  Rotate it with `taskswarm token rotate`.
+- **Agent-native by design.** Every subcommand ships a `--json` flag with a
+  stable schema, including error output.
+- **ntfy.sh is opt-in, never default.** The only notification channel that
+  leaves your machine, and it's off unless you configure it in
+  `~/.taskswarm/config.json`.
+
+## CLI reference
+
+| Command                             | Description                                                                                                    | Key options                                                                                                                                                                                                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `taskswarm start`                   | Start the TaskSwarm server and print the live status page URL                                                  | `--json`                                                                                                                                                                                                                                                                 |
+| `taskswarm task add`                | Register a new task                                                                                            | `--title <title>` (required), `--repo <path>` (required), `--json`                                                                                                                                                                                                       |
+| `taskswarm task list`               | List tracked tasks, enriched with live status when the server is reachable                                     | `--json`                                                                                                                                                                                                                                                                 |
+| `taskswarm agent report-status`     | Report a status transition for a task/session to the local server                                              | `--task <id>` (required), `--repo <path>` (required), `--state <state>` (required, one of `queued\|running\|blocked\|needs-review\|done\|failed`), `--blocked-reason <text>`, `--agent-type <type>` (`claude-code\|codex\|cursor\|generic`, default `generic`), `--json` |
+| `taskswarm token rotate`            | Generate a new bearer token, invalidating the old one                                                          | `--json`                                                                                                                                                                                                                                                                 |
+| `taskswarm hooks install <adapter>` | Install hooks for an agent integration (currently `claude-code`)                                               | `--scope <project\|local\|user>` (default `project`), `--project-dir <path>`, `--json`                                                                                                                                                                                   |
+| `taskswarm hooks claude-code-relay` | Internal: reads a hook payload from stdin and relays it. Installed automatically; not meant to be run by hand. | none                                                                                                                                                                                                                                                                     |
+
+`taskswarm --version` prints `taskswarm 0.1.0`. The `taskswarm-cli` console
+script installed by this package is an identical alias, matching both `bin`
+entries the npm package ships.
+
+## How it works
+
+```
+agent session / hook / wrapper script
+        |
+        v
+POST /events (bearer token required)  -> event schema validation
+        |
+        v
+EventStore (in-memory + append-only JSONL log at ~/.taskswarm/events.jsonl)
+        |
+        +--> notify() -- fires on a transition into blocked/needs-review/failed/done
+        |         |
+        |         +--> local OS notification (always on)
+        |         +--> ntfy.sh (opt-in only)
+        |
+        +--> GET /live (Server-Sent Events) -> live status page
+```
+
+Full data model and the exact notification-dedup rule are in
+[docs/concepts.md](https://github.com/RudrenduPaul/taskswarm/blob/main/docs/concepts.md).
+
+## Security
+
+The local API is gated by a bearer token generated on first run and stored
+`0600` at `~/.taskswarm/config.json`; the server binds to `127.0.0.1` by
+default. Token comparison uses `hmac.compare_digest` (constant-time,
+avoiding timing side-channels), the same property the TypeScript version
+gets from `crypto.timingSafeEqual`. See
+[SECURITY.md](https://github.com/RudrenduPaul/taskswarm/blob/main/SECURITY.md)
+for the full posture, including what this server does **not** protect
+against (it is a local developer tool, not designed to be exposed on a
+shared or public network). **Honest note**: this project does not currently
+publish SLSA provenance, Sigstore signatures, or an SBOM, and has no
+OpenSSF Scorecard badge -- none of that infrastructure exists yet for
+either distribution, so it isn't claimed here.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/RudrenduPaul/taskswarm/blob/main/CONTRIBUTING.md)
+for the full guide, covering both the TypeScript and Python codebases.
+
+```bash
+cd python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/RudrenduPaul/taskswarm/blob/main/LICENSE).

taskswarm_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+taskswarm/__init__.py,sha256=YKU8D5Ojv2GkYuH6lKwLc29qzcYlSp5FvQtEe5rjz2E,1947
+taskswarm/cli.py,sha256=l9xY2VVdwmm-9bQHmC5z2ZnvL1vcHyHDby-_tWjdhOk,12160
+taskswarm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskswarm/adapters/__init__.py,sha256=otjh_TU2gWSAUOLH_LU55tpJ1Id0xQM8R2-pxeJDutc,323
+taskswarm/adapters/claude_code_adapter.py,sha256=uuAD4SMAoht_TqUeyWoUw0gbkY18vyj3BmBWmDO_v4k,9837
+taskswarm/adapters/generic_adapter.py,sha256=UGG7rZ8Tt1w2dYqNvFOwkJH-wlFK3Qg-bGPQq-EoTX4,1927
+taskswarm/adapters/types.py,sha256=3GonzdISwccugOQSMWt1DqdPzZ8k8SnOjkiHYe7GoiE,801
+taskswarm/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskswarm/client/api_client.py,sha256=IBlmOditARXPG_e2clGCVALaDlnxtEJxENMFiEowQVI,2422
+taskswarm/client/tasks_registry.py,sha256=kIY90Ee1HctlWzKy_hPLceMB-5wtzNnJMXS4wDXIfpI,4029
+taskswarm/notifications/__init__.py,sha256=o7OzCZn2ZhSEO4maHXfc9d5K_E9kT0QhkkC8C56lwm0,115
+taskswarm/notifications/dispatch.py,sha256=7ZzlQrM8MBDxLSMbeWT-DExhadsGCbDjyWQqudTS2Wc,3641
+taskswarm/notifications/ntfy.py,sha256=yj0Dylf1u-y6giSrVemdNsdaYer47GUd0yvr5KYaa0M,2622
+taskswarm/notifications/os_notify.py,sha256=Cv1wkgGlMJJbHeOsY3o27qrDwpKQa7ZuMFjw8xL-sfI,2324
+taskswarm/schema/__init__.py,sha256=cyWQUq_bTQ0QUl9wAHygmjSreJ9skLwy25lWHVsgO0o,463
+taskswarm/schema/events.py,sha256=1y7xL943s-MWGpSmgclEdly9YKV4sAvl2cCn0d7d2h0,8494
+taskswarm/server/__init__.py,sha256=pvxFZ9Q66KshNDMQ7emTj7hjwz2J7VosJrLXhmTPY1U,720
+taskswarm/server/auth.py,sha256=HoyGEBUlqRhjr6qxBDHFdlvVUKLx2GQLkrWhRabUv9o,1015
+taskswarm/server/config.py,sha256=sgbAaNtMG7OaOcg8XT0V_nCV06qwu9X3pcCZ4FHaXy4,5130
+taskswarm/server/event_store.py,sha256=Na7sUBy7DlIQ4TlgJuhSQMiy9j5FdVaYpXtt6U6uiBY,5942
+taskswarm/server/http_server.py,sha256=r6ZigVXkLf38vOrFYoIuveXD0COJCB0hpxmC5jHByAE,9679
+taskswarm/server/server.py,sha256=jkHOhKyEkjk-Rv8OGY8vYBI9_4dWDcIcdQf8wNs6Ot0,2818
+taskswarm/ui/index.html,sha256=_pA-s0HLPOxDRV7N6a7k4bSdXQ5xDhiA_sUs2MVHTQ8,6596
+taskswarm/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskswarm/util/sync_sleep.py,sha256=QrMEpagV5bjdzfs-UC4PkNDYRimUw0zWY9VVbNcZn-0,673
+taskswarm_cli-0.1.0.dist-info/METADATA,sha256=uzpjCOY8ZlANh_z17kfXQBPNlwdpOssBR87D_Ee9xrQ,12693
+taskswarm_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+taskswarm_cli-0.1.0.dist-info/entry_points.txt,sha256=bev456K-eZwGlQ_BEKgSn508VXTrG8-msjhXYTL4SZs,84
+taskswarm_cli-0.1.0.dist-info/licenses/LICENSE,sha256=BfVFjPafHBvDFGiOExHmSA9zx3abipLGkjV1O2MZj9Y,1070
+taskswarm_cli-0.1.0.dist-info/RECORD,,

taskswarm_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

taskswarm_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+taskswarm = taskswarm.cli:main
+taskswarm-cli = taskswarm.cli:main

taskswarm_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rudrendu Paul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.