taskswarm-cli 0.1.0__tar.gz

taskswarm_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.venv-freshinstall/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/

taskswarm_cli-0.1.0/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.

taskswarm_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,182 @@
+# 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/examples/01-basic-server/run.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""
+Boots a real TaskSwarm server on an ephemeral port, reports a session
+through queued -> running -> done using the GenericAdapter, reads back live
+session state, and confirms a local notification fired on the transition
+into 'done' (one of the four states TaskSwarm's notification layer watches
+for). Run it directly:
+
+    python3 examples/01-basic-server/run.py
+"""
+import json
+import tempfile
+from pathlib import Path
+
+from taskswarm.adapters import GenericAdapter
+from taskswarm.client.api_client import get_sessions, post_event
+from taskswarm.notifications import NotifyOptions
+from taskswarm.server.config import TaskSwarmConfig, generate_token
+from taskswarm.server.server import start_server
+
+
+def main() -> None:
+    fired = []
+
+    def on_notify(title: str, message: str) -> None:
+        fired.append((title, message))
+
+    # An ephemeral, isolated home dir -- this example never touches your
+    # real ~/.taskswarm.
+    home = tempfile.mkdtemp(prefix="taskswarm-example-")
+    print(f"Using TASKSWARM_HOME={home}")
+
+    config = TaskSwarmConfig(token=generate_token(), port=0, host="127.0.0.1")
+    running = start_server(
+        config=config,
+        log_path=str(Path(home) / "events.jsonl"),
+        notify_options=NotifyOptions(os_notifier=on_notify),
+    )
+    print(f"Server listening at {running.url}")
+
+    adapter = GenericAdapter()
+
+    for status in ("queued", "running", "done"):
+        event_input = adapter.to_event_input(
+            {"session_id": "example-task", "repo": "./demo-repo", "status": status, "agent_type": "generic"}
+        )
+        event = post_event(running.config.to_dict(), event_input)
+        print(f"reported: {event['session_id']} -> {event['status']}")
+
+    sessions = get_sessions(running.config.to_dict())
+    print("\ncurrent session state:")
+    print(json.dumps(sessions, indent=2))
+
+    print(f"\nnotifications fired: {len(fired)}")
+    for title, message in fired:
+        print(f"  [{title}] {message}")
+
+    assert len(fired) == 1, "expected exactly one notification, for the 'done' transition"
+    running.close()
+    print("\nOK: server started, event reported, notification fired, server closed cleanly.")
+
+
+if __name__ == "__main__":
+    main()

taskswarm_cli-0.1.0/examples/02-ci-gate/gate.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Demonstrates the CI-gate pattern documented in docs/integrations/ci.md:
+report a task's outcome, poll session state, and exit non-zero if anything
+failed -- the shape a real CI step would use, minus the real CI system.
+
+Boots its own ephemeral server so this is runnable standalone. In a real
+pipeline, drop the `start_server()` call and point `config` at an
+already-running server's `~/.taskswarm/config.json` instead (see
+`taskswarm.load_or_create_config()`).
+
+    python3 examples/02-ci-gate/gate.py
+"""
+import sys
+import tempfile
+from pathlib import Path
+
+from taskswarm.adapters import GenericAdapter
+from taskswarm.client.api_client import get_sessions, post_event
+from taskswarm.notifications import NotifyOptions
+from taskswarm.server.config import TaskSwarmConfig, generate_token
+from taskswarm.server.server import start_server
+
+
+def run_ci_gate(config: dict) -> int:
+    """Returns the process exit code a real CI step would use: 0 if no
+    tracked session ended in 'failed', 1 otherwise."""
+    sessions = get_sessions(config)
+    failed = [s for s in sessions if s["latest"]["status"] == "failed"]
+    if failed:
+        for session in failed:
+            reason = session["latest"].get("blocked_reason", "no reason given")
+            print(f"FAILED: {session['session_id']} ({reason})", file=sys.stderr)
+        return 1
+    print(f"{len(sessions)} session(s) tracked, none failed.")
+    return 0
+
+
+def main() -> None:
+    home = tempfile.mkdtemp(prefix="taskswarm-example-")
+    config = TaskSwarmConfig(token=generate_token(), port=0, host="127.0.0.1")
+    running = start_server(
+        config=config,
+        log_path=str(Path(home) / "events.jsonl"),
+        notify_options=NotifyOptions(os_notifier=lambda title, message: None),
+    )
+
+    adapter = GenericAdapter()
+    # Simulate an agent task that failed partway through.
+    post_event(
+        running.config.to_dict(),
+        adapter.to_event_input(
+            {
+                "session_id": "flaky-test-fix",
+                "repo": "./demo-repo",
+                "status": "failed",
+                "agent_type": "generic",
+                "blocked_reason": "test suite still red after the agent's fix",
+            }
+        ),
+    )
+
+    exit_code = run_ci_gate(running.config.to_dict())
+    running.close()
+    print(f"\nCI gate would exit with code {exit_code}")
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

taskswarm_cli-0.1.0/examples/03-claude-code-hook/relay.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+The agent-native use case: feeds a real Claude Code hook payload shape
+(the same JSON shape Claude Code writes to a hook's stdin) through
+ClaudeCodeAdapter in-process -- no CLI subprocess, no server needed for
+this part -- and inspects the resulting event input plus the
+notification-dedup decision (should_notify) directly.
+
+    python3 examples/03-claude-code-hook/relay.py
+"""
+import json
+
+from taskswarm.adapters import ClaudeCodeAdapter
+from taskswarm.notifications import should_notify
+
+# A realistic 'Notification' hook payload -- the shape Claude Code writes
+# to stdin when a permission prompt appears mid-session.
+permission_prompt_payload = {
+    "session_id": "claude-session-42",
+    "cwd": "/Users/demo/projects/api",
+    "hook_event_name": "Notification",
+    "notification_type": "permission_prompt",
+}
+
+# A 'Stop' payload -- fires when Claude Code finishes responding to a turn.
+stop_payload = {
+    "session_id": "claude-session-42",
+    "cwd": "/Users/demo/projects/api",
+    "hook_event_name": "Stop",
+}
+
+
+def main() -> None:
+    adapter = ClaudeCodeAdapter()
+
+    print("Permission-prompt hook -> event input:")
+    permission_event = adapter.to_event_input(permission_prompt_payload)
+    print(json.dumps(permission_event, indent=2))
+
+    print("\nStop hook -> event input:")
+    stop_event = adapter.to_event_input(stop_payload)
+    print(json.dumps(stop_event, indent=2))
+
+    # Notification-dedup: a first 'needs-review' with no prior status
+    # notifies. A second, identical-reason 'needs-review' right after does
+    # not (it's a repeat). A third 'needs-review' with a *different*
+    # blocked_reason (a different permission prompt) notifies again, even
+    # though the status itself hasn't changed.
+    print("\nNotification-dedup walkthrough:")
+    decisions = [
+        ("first permission prompt", should_notify("needs-review", None, permission_event["blocked_reason"], None)),
+        (
+            "identical repeat",
+            should_notify(
+                "needs-review", "needs-review", permission_event["blocked_reason"], permission_event["blocked_reason"]
+            ),
+        ),
+        (
+            "a second, different prompt",
+            should_notify("needs-review", "needs-review", "a different reason entirely", permission_event["blocked_reason"]),
+        ),
+    ]
+    for label, decision in decisions:
+        print(f"  {label}: should_notify = {decision}")
+
+    assert decisions[0][1] is True
+    assert decisions[1][1] is False
+    assert decisions[2][1] is True
+    print("\nOK: dedup decisions matched the documented rule (docs/concepts.md).")
+
+
+if __name__ == "__main__":
+    main()