claude-supervisor 0.1.0__tar.gz

claude_supervisor-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF in the repository across platforms.
+* text=auto eol=lf
+
+# Explicitly text
+*.py    text eol=lf
+*.pyi   text eol=lf
+*.toml  text eol=lf
+*.yaml  text eol=lf
+*.yml   text eol=lf
+*.md    text eol=lf
+*.cfg   text eol=lf
+py.typed text eol=lf

claude_supervisor-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Bug report
+description: Something didn't work as expected
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for trying Claude Supervisor (alpha). The single most useful thing
+        you can attach is a **`--capture` transcript** from the run — it records
+        exactly what Claude printed and what the supervisor detected.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command you ran
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: capture
+    attributes:
+      label: Capture transcript
+      description: |
+        Re-run with `--capture run.txt` and paste or attach the file. For any
+        detection problem (a prompt not answered, a limit not detected, a run
+        that didn't stop), this is the most important field.
+      render: text
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: "OS, `python --version`, `claude --version`, `claude-supervisor version`"
+      placeholder: "Windows 11, Python 3.12.5, claude 1.x, claude-supervisor 0.1.0"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs (optional)
+      description: "Output of `claude-supervisor logs -n 80`, if relevant."
+      render: shell

claude_supervisor-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/OnamSharma/claude-supervisor/security/advisories/new
+    about: Please report vulnerabilities privately — see SECURITY.md, not a public issue.

claude_supervisor-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do that's hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? Alternatives you've considered?
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      description: Claude Supervisor never bypasses limits, auth, or subscriptions, and never modifies Claude.
+      options:
+        - label: This request stays within that scope.
+          required: true

claude_supervisor-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+# What & why
+
+<!-- What does this change, and why? Link any related issue. -->
+
+# Checklist
+
+- [ ] Tests added/updated; `pytest` is green and coverage stays ≥ 90%
+- [ ] `ruff check .`, `black --check .`, and `mypy src` are clean
+- [ ] Docs and `CHANGELOG.md` updated where relevant
+- [ ] Detection wording changes go in `parser/rules/claude.yaml` (not code) where possible
+- [ ] Stays within scope: no bypassing limits/auth/subscriptions, no modifying Claude

claude_supervisor-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+    labels: ["dependencies"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies", "ci"]

claude_supervisor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install (with dev + platform PTY backend)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Format check (black)
+        run: black --check .
+
+      - name: Type check (mypy)
+        run: mypy src
+
+      - name: Test (with coverage; real-PTY integration included)
+        run: pytest
+
+  build:
+    name: build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Verify metadata
+        run: |
+          python -m pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

claude_supervisor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Publishes to PyPI when a version tag (v*) is pushed. Uses PyPI Trusted
+# Publishing (OIDC) — no API token secret required once the publisher is
+# configured on PyPI. See docs/RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build + check
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

claude_supervisor-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Runtime state (logs, database)
+*.log
+*.db
+*.sqlite3
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

claude_supervisor-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+# Install once with:  pre-commit install
+# Run on all files:   pre-commit run --all-files
+# (mypy runs in CI rather than here to keep commits fast.)
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black

claude_supervisor-0.1.0/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-12
+
+First public alpha.
+
+### Validated
+
+- **Runs against real Claude Code** (CLI 2.x). Confirmed end-to-end on Windows:
+  the supervisor launches `claude -p`, runs a task, detects the clean-exit
+  completion, and records the session. Live testing drove the fixes below.
+
+### Changed
+
+- **A clean process exit (code 0) now counts as completion in every mode.** Real
+  headless `claude -p` prints its answer and exits 0 with no "done" marker, so a
+  clean exit *is* success; only a non-zero exit is an unexpected exit. The
+  strict/heuristic distinction now governs only *idle* detection.
+
+### Fixed
+
+- Default `resume_command` corrected from the invalid `claude resume` to
+  `claude --continue` (the real Claude Code flag for continuing a session).
+- A failed process launch (e.g. `claude` not on PATH, or a wrong
+  `claude_command`) now raises a clear `TerminalError` with an actionable hint
+  and exits non-zero, instead of dumping a `FileNotFoundError` traceback.
+- An explicitly provided `--config` path that does not exist now errors clearly
+  instead of being silently ignored (a typo'd path used to fall back to
+  defaults). A missing *default* location still uses defaults, as before.
+
+### Added
+
+- **`claude-supervisor init`** writes a starter config using the validated
+  headless recipe (`claude -p --permission-mode acceptEdits`), so unattended
+  runs work out of the box.
+- **`doctor` now checks for the `claude` CLI** on your PATH (informational),
+  with an install hint if it's missing.
+- **Claude Code integration.** A `claude-supervisor statusline` command feeds a
+  live one-liner (`🛡 3 runs · 1 resume · 2.1h saved`) into Claude Code's status
+  bar, plus a `/supervisor` slash command — see
+  [docs/CLAUDE_CODE_INTEGRATION.md](docs/CLAUDE_CODE_INTEGRATION.md). The status
+  line forces UTF-8 output and is fully defensive so it can never disrupt the UI.
+- **Release automation** (`.github/workflows/release.yml`): tag `vX.Y.Z` builds,
+  `twine check`s, and publishes to PyPI via Trusted Publishing. See
+  [docs/RELEASING.md](docs/RELEASING.md).
+- **Contributor tooling:** `.pre-commit-config.yaml` (ruff/black/basic hooks)
+  and Dependabot for pip + GitHub Actions updates.
+- **Public-readiness:** README badges (CI/license/Python/status), an honest
+  "Project status" section (alpha; not yet validated against live Claude),
+  a `status` demo, GitHub issue forms (bug report asks for a `--capture`
+  transcript) and a PR template, and CI stabilization (auto-retry the
+  timing-sensitive real-PTY tests).
+- **Run capture / transcript** (`start --capture <file>`). Writes every
+  (ANSI-stripped) line Claude prints to a file, tagging the ones that triggered
+  a detected event. Makes a real run self-document exactly what Claude output
+  and what the supervisor saw — the fastest way to reconcile parser rules
+  against real Claude Code wording. Backed by a `LineListener` hook on the
+  parser and a `TranscriptWriter`; survives resumes.
+- **Unattended task mode.** `claude-supervisor start --task "<task>"` runs a
+  task without you attached: it survives usage-limit resets, auto-answers the
+  repetitive prompts, detects completion, and reports. Task delivery is
+  configurable (`task_delivery`): `argument` appends it to the command
+  (`claude -p "<task>"` style, default) or `input` types it into an interactive
+  session. `--auto-approve` opts a single run into answering prompts
+  (active-task scope). Validated end-to-end on a real PTY for both modes.
+- **Idle / prompt-return completion detection.** In heuristic completion mode,
+  a live-but-silent session (no output for `idle_completion_seconds`, default
+  30s) is treated as a finished turn — Claude idling at the prompt — so the
+  supervisor stops and hands control back. This covers the common case where
+  there is no literal "completed" marker. Strict mode (the default) is
+  unchanged. Idle time is accrued from read intervals (deterministic, no
+  busy-poll), and `ScriptedTerminal` gained a `TIMEOUT` marker to test it.
+
+- **Storage** (`storage/`): a `Storage` protocol and `SqliteStorage` backend
+  persisting sessions and per-run events, plus a `Statistics` aggregate
+  (completed sessions, resumes, approvals, average runtime/wait, hours saved).
+  The layer speaks only primitives — it never imports the orchestration layer.
+- **Session** (`session/`): `SessionManager` bridges a run onto storage —
+  records `RunStats`, logs every state transition as an event, and exposes
+  latest/recent sessions plus statistics.
+- **CLI**: `status` (latest session + aggregate statistics) and `logs` (tail of
+  the log file) are now live. `start`/`resume` persist each run automatically.
+- `RunStats` gained `total_wait_seconds` (unattended waiting absorbed), the
+  basis for the "hours saved" statistic.
+
+- **Terminal** (`terminal/`): `TerminalManager` abstraction with a
+  timeout-capable `read`; a process-free `ScriptedTerminal`; a `ThreadedTerminal`
+  base that pumps blocking PTY reads on a background thread (event-driven, no
+  busy-polling); `pexpect` (POSIX) and `pywinpty` (Windows) backends, lazily
+  imported with a clear install hint; platform-aware `create_terminal` /
+  `terminal_factory`.
+- **Permissions** (`permissions/`): `PermissionDecision`, a `PermissionEngine`
+  protocol, and `ActiveTaskPermissionEngine` — v1 approves repetitive prompts
+  only when the user opted in *and* a task is active; it never auto-rejects.
+- **Resume** (`resume/`): an interruptible `Clock` (`RealClock` waits on an
+  event; `ManualClock` for deterministic tests) and a `ResumePlanner` that
+  prefers a parsed reset delay, then the last-known interval, then the default.
+- **Core** (`core/`): the `Supervisor` run loop tying the subsystems together,
+  plus `RunStats`. Enforces the safety invariants structurally (completion is
+  terminal; waits are interruptible; auto-answer is scoped).
+- **CLI**: `start` and `resume` are now live, with SIGINT-safe shutdown and a
+  run-summary table.
+
+### Fixed
+
+- Parser now emits at most one event per event type per line, so a single
+  usage-limit line can never trigger a duplicate resume.
+- **Real-PTY hardening (found by integration testing against a live pseudo-
+  terminal):**
+  - The parser now strips ANSI/VT escape sequences before matching, so
+    detection is robust against Claude's coloured TUI output (`strip_ansi`).
+  - `send_line` now terminates input with a carriage return (`\r`), the actual
+    "Enter" key on a terminal. Previously it sent `\n`, which a Windows ConPTY
+    does not treat as Enter, leaving a child blocked on input forever.
+
+### Changed
+
+- **Permission answers are now configurable and menu-aware.** Real Claude Code
+  shows a numbered menu ("Do you want to proceed? / 1. Yes / …"), not a `(y/N)`
+  prompt. Terminals gained a raw `send(data)` (send arbitrary key sequences;
+  `send_line` is now `send(line + "\r")`), and `approve_response` /
+  `reject_response` config controls what is sent — defaulting to `"1\r"`
+  (select "Yes") and `"\x1b"` (Escape). Default detection patterns now match the
+  menu wording, keeping `(y/N)` support for classic prompts.
+
+### Tests
+
+- Added real-PTY integration tests (`tests/integration/`) that spawn an actual
+  subprocess in a pseudo-terminal via the platform backend, covering the full
+  usage-limit → wait → resume → permission → completion flow. Skipped cleanly
+  when no PTY backend is installed.
+
+### Foundation (initial build)
+
+The tested, dependency-light core.
+
+### Added
+
+- **Configuration** (`config/`): pydantic-validated `SupervisorConfig` loaded
+  from YAML, with backward-compatible flat spec keys (`log_level`, etc.) and
+  safe defaults (`auto_permissions` defaults to `false`).
+- **Logging** (`logging/`): Rich console handler plus an optional rotating file
+  handler, behind an idempotent `configure_logging`.
+- **Parser** (`parser/`): a streaming `ClaudeOutputParser` driven by an external
+  YAML **compatibility layer** (`PatternSet`), a small stable `EventType` set,
+  and reset-time extraction (relative `Try again in 4h 51m` and absolute
+  `Try again after 15:30`).
+- **State machine** (`state_machine/`): explicit states and a validated
+  transition table with observers. Enforces the safety rule that
+  `TASK_COMPLETED` can only lead to `STOPPED`.
+- **CLI** (`cli/`): `version`, `config`, and `doctor` commands; `start`,
+  `resume`, `status`, `logs` are declared as clear "not yet implemented" stubs.
+- Test suite across all modules and project docs (README, ARCHITECTURE,
+  ROADMAP, SECURITY, CONTRIBUTING, CODE_OF_CONDUCT).
+
+[Unreleased]: https://github.com/OnamSharma/claude-supervisor/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/OnamSharma/claude-supervisor/releases/tag/v0.1.0

claude_supervisor-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement. All complaints
+will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

claude_supervisor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to Claude Supervisor
+
+Thanks for your interest! This project aims to be a clean, well-tested,
+production-quality tool. Contributions of all sizes are welcome.
+
+## Ground rules
+
+1. **Stay within scope.** Contributions must not bypass usage limits,
+   authentication, or subscriptions, or modify/patch/impersonate Claude. See
+   [ROADMAP.md](ROADMAP.md) non-goals and [SECURITY.md](SECURITY.md).
+2. **Safety over automation.** When behavior is uncertain, choose the safest
+   option and make the riskier one opt-in and logged.
+3. **State-driven.** Lifecycle logic goes through the state machine, not ad-hoc
+   boolean flags.
+
+## Development setup
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Requires Python 3.12+.
+
+Optionally install the git hooks so formatting/lint run on every commit:
+
+```bash
+pre-commit install
+```
+
+## Before you open a PR
+
+Run the full local check suite:
+
+```bash
+ruff check .
+black --check .
+mypy src
+pytest
+```
+
+- **Tests are required** for new behavior. Keep total coverage ≥ 90%.
+- **Type hints and docstrings** on all public functions/classes (Google style).
+- Keep modules single-responsibility and independently testable.
+- Update [docs/TODO.md](docs/TODO.md), `CHANGELOG.md`, and relevant docs.
+
+## Detection rules
+
+Parser wording changes usually belong in
+`src/claude_supervisor/parser/rules/claude.yaml`, **not** in Python. Prefer
+under-matching over over-matching, especially for `permission` patterns — a
+false permission match could auto-answer something.
+
+## Commit / PR style
+
+- Small, focused PRs aligned with a roadmap iteration are easiest to review.
+- Describe the *why*, not just the *what*.
+- Reference the iteration/issue you're addressing.
+
+## Code of Conduct
+
+Participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).

claude_supervisor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claude Supervisor contributors
+
+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.