ccmon 0.5.4__tar.gz

ccmon-0.5.4/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Ruff lint
+        run: uv run ruff check --output-format github
+      - name: Ruff format check
+        run: uv run ruff format --check
+      - name: Type check (pyright)
+        run: uv run pyright
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Run tests
+        run: uv run pytest -q --tb=short --no-header --cov=ccmon --cov-fail-under=70

ccmon-0.5.4/.github/workflows/publish.yml

@@ -0,0 +1,108 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  update-homebrew:
+    name: Update Homebrew formula
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    steps:
+      - name: Fetch tarball SHA256 from PyPI
+        id: pypi
+        run: |
+          VERSION="${{ github.ref_name }}"
+          # Strip leading 'v' from tag to get bare version number
+          PKG_VERSION="${VERSION#v}"
+          PYPI_JSON=$(curl -s "https://pypi.org/pypi/ccmon/${PKG_VERSION}/json")
+          SHA256=$(echo "$PYPI_JSON" | jq -r '
+            .urls[]
+            | select(.packagetype == "sdist" and (.filename | endswith(".tar.gz")))
+            | .digests.sha256
+          ')
+          if [ -z "$SHA256" ] || [ "$SHA256" = "null" ]; then
+            echo "ERROR: Could not find sha256 for ccmon ${PKG_VERSION} on PyPI"
+            exit 1
+          fi
+          echo "version=${PKG_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "sha256=${SHA256}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout homebrew-tap
+        uses: actions/checkout@v4
+        with:
+          repository: einerlei/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: homebrew-tap
+
+      - name: Update Formula/ccmon.rb
+        run: |
+          FORMULA="homebrew-tap/Formula/ccmon.rb"
+          VERSION="${{ steps.pypi.outputs.version }}"
+          SHA256="${{ steps.pypi.outputs.sha256 }}"
+
+          # Update url line (replace version in the PyPI tarball URL)
+          python3 - <<'PYEOF'
+          import re, os, sys
+
+          formula_path = os.environ.get("FORMULA", "homebrew-tap/Formula/ccmon.rb")
+          version      = os.environ.get("VERSION")
+          sha256       = os.environ.get("SHA256")
+
+          with open(formula_path) as f:
+              content = f.read()
+
+          # Replace url line
+          content = re.sub(
+              r'(url\s+"https://files\.pythonhosted\.org/packages/source/c/ccmon/ccmon-)[^"]+(")',
+              rf'\g<1>{version}.tar.gz\g<2>',
+              content,
+          )
+
+          # Replace sha256 line (first occurrence — the top-level package sha256)
+          content = re.sub(
+              r'(sha256\s+")[a-f0-9]+"',
+              rf'\g<1>{sha256}"',
+              content,
+              count=1,
+          )
+
+          with open(formula_path, "w") as f:
+              f.write(content)
+
+          print(f"Updated {formula_path} to version {version} sha256 {sha256[:16]}…")
+          PYEOF
+        env:
+          FORMULA: homebrew-tap/Formula/ccmon.rb
+          VERSION: ${{ steps.pypi.outputs.version }}
+          SHA256: ${{ steps.pypi.outputs.sha256 }}
+
+      - name: Commit and push
+        run: |
+          cd homebrew-tap
+          git config user.name "einerlei"
+          git config user.email "31n34731@gmail.com"
+          git add Formula/ccmon.rb
+          git commit -m "chore: bump ccmon to ${{ steps.pypi.outputs.version }}"
+          git push

ccmon-0.5.4/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Poetry
+# poetry.lock is intentionally tracked for reproducible installs
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Claude Code
+.claude/
+
+# Env files
+.env
+.env.*
+!.env.example

ccmon-0.5.4/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: poetry run pyright
+        language: system
+        types: [python]
+        pass_filenames: false

ccmon-0.5.4/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Releasing a new version
+
+1. Update `version` in `pyproject.toml`
+2. Update `__version__` in `ccmon.py`
+3. Add release notes under a new `## [X.Y.Z] - YYYY-MM-DD` section below
+4. Commit: `git commit -m "chore: release vX.Y.Z"`
+5. Tag: `git tag vX.Y.Z`
+6. Push: `git push && git push --tags`
+
+---
+
+## [Unreleased]
+
+## [0.5.4] - 2026-05-10
+
+### Changed
+- Migrated build tooling from Poetry to uv (hatchling build backend, PEP 735 dependency groups)
+
+## [0.5.3] - 2026-05-10
+
+### Added
+- Token usage display: each agent pane shows its cumulative output-token count; the status bar shows the session-wide total
+
+## [0.5.2] - 2026-05-10
+
+### Added
+- `-a` as a short alias for `--all`
+
+## [0.5.1] - 2026-05-10
+
+### Fixed
+- `--all` now shows sessions that are idle (waiting for user input); previously they disappeared after 5 seconds because Claude's last response was mistaken for a completed/expired agent
+
+## [0.5.0] - 2026-05-05
+
+### Changed
+- Renamed package and command from `cctop` to `ccmon`
+
+## [0.4.0] - 2026-05-04
+
+### Added
+- Positional `DIR` argument: `cctop .` or `cctop /path/to/project` filters to that directory
+- `-p` short alias for `--project`
+- Bare `cctop` (no arguments) defaults to the current working directory
+
+### Changed
+- `--all` and `--project`/`-p`/positional DIR are now explicitly mutually exclusive with a clear error message
+
+## [0.3.6] - 2026-05-04
+
+### Changed
+- `make install` uses `pipx` (the standard for CLI tools); removed redundant `make install-pipx` target
+
+## [0.3.5] - 2026-05-04
+
+### Changed
+- `make install` now uses `pip install .`; `make install-pipx` added for pipx-based installs
+- Removed `/delegate` skill reference from `CLAUDE.md` (it is a custom skill, not a Claude built-in)
+
+## [0.3.4] - 2026-05-04
+
+### Fixed
+- `make install` now gives a clear error if `pipx` is not installed instead of a cryptic make failure
+- `make test` coverage target corrected from `--cov=dashboard` to `--cov=cctop`
+
+## [0.3.3] - 2026-05-04
+
+### Fixed
+- CI venv cache key now includes `pyproject.toml` so adding/changing dev dependencies (e.g. `pyright`) reliably invalidates the cache
+
+## [0.3.2] - 2026-05-04
+
+### Changed
+- Renamed main module from `dashboard.py` to `cctop.py` to align with CLI and project name
+
+## [0.3.1] - 2026-05-04
+
+### Fixed
+- Ensured `pyright` is resolvable via `poetry run pyright` in CI by confirming it is
+  declared in the `[tool.poetry.group.dev.dependencies]` section; recreating the
+  virtual environment resolves stale-venv cache misses that caused "Command not found"
+
+## [0.3.0] - 2026-05-04
+
+### Changed
+- **Renamed** project to `cctop`; CLI entrypoint is now `cctop`
+- Empty state message updated: "No active Claude Code session" (was "No subagents for project")
+- App title updated to "Claude Code Monitor"
+
+### Added
+- `Makefile` with `lint`, `format`, `check`, and `test` targets for developer convenience
+- `pytest-cov` with 70% coverage floor enforced in CI
+- `pyright` type-checking step in CI lint job
+- `.pre-commit-config.yaml` with ruff and pyright hooks
+- 16 new unit tests covering `_render_output`, `_build_agent_type_lookup`, `_last_skill_call`
+
+### Refactored
+- Extracted `_status_display` helper; eliminated duplicated markup logic in `AgentPane`
+
+## [0.2.1] - 2026-05-03
+
+### Added
+- Main Claude Code session pane: the parent session now appears alongside its
+  subagents, rendered with `◈` symbol and a cyan border (`pane--main` CSS class)
+
+## [0.2.0] - 2026-05-03
+
+### Added
+- Test suite with pytest (unit tests for data layer and CLI)
+- GitHub Actions CI workflow (lint + test on push/PR to main)
+- `__version__` constant in `cctop.py`
+- Expanded README with architecture overview, dev setup, and contributing guide
+
+### Changed
+- Code quality improvements based on review (type annotations, error handling)
+
+## [0.1.0] - 2026-04-01
+
+### Added
+- Initial release: terminal TUI for monitoring Claude Code subagents
+- Real-time auto-refresh (0.5s interval)
+- Session filtering by project directory (`--project`, `--all` flags)
+- Status tracking: running, completed, interrupted, unknown
+- Stale agent expiry (10-minute timeout for non-running agents)
+- 2-column grid layout with Rich-styled message history per agent

ccmon-0.5.4/CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md — Project instructions for Claude Code
+
+## Version bumps
+
+Every workflow that produces user-facing or tooling changes **must** include a version
+bump. Use semantic versioning:
+
+- Breaking change (renamed CLI, removed feature) → minor bump (0.x.0)
+- New feature or behaviour change → minor bump (0.x.0)
+- Bug fix or internal refactor only → patch bump (0.x.x)
+
+Update both `pyproject.toml` (`version =`) and `ccmon.py` (`__version__ =`), and add a
+`## [X.Y.Z] - YYYY-MM-DD` entry to `CHANGELOG.md` following the Keep a Changelog format.
+
+## Smoke-test after changes
+
+After any code change, verify the app starts:
+
+```bash
+poetry run ccmon --help
+```
+
+Unit tests passing is not sufficient — always run the CLI entrypoint too.

ccmon-0.5.4/Makefile

@@ -0,0 +1,28 @@
+.PHONY: lint format check test install release
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff format .
+
+check:
+	uv run ruff check . && uv run ruff format --check . && uv run pyright
+
+test:
+	uv run pytest -q --tb=short --no-header --cov=ccmon --cov-fail-under=70
+
+install:
+	@which pipx >/dev/null 2>&1 || { echo "pipx not found. Install with: brew install pipx"; exit 1; }
+	pipx install . --force
+	pipx ensurepath
+	@if ! echo "$$PATH" | grep -q "$$HOME/.local/bin"; then \
+		echo ""; \
+		echo "  ccmon is installed but not yet in your PATH."; \
+		echo "  Run: source ~/.zshrc"; \
+	fi
+
+release:
+	@test -n "$(VERSION)" || (echo "Usage: make release VERSION=x.y.z"; exit 1)
+	git tag v$(VERSION)
+	git push && git push --tags

ccmon-0.5.4/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: ccmon
+Version: 0.5.4
+Summary: Terminal monitor for Claude Code sessions and subagents
+Project-URL: Homepage, https://github.com/einerlei/ccmon
+Project-URL: Repository, https://github.com/einerlei/ccmon
+Project-URL: Changelog, https://github.com/einerlei/ccmon/blob/main/CHANGELOG.md
+Author-email: einerlei <31n34731@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: textual<9.0.0,>=8.2.5
+Description-Content-Type: text/markdown
+
+# ccmon
+
+Terminal monitor for Claude Code sessions and subagents in real time. Run `ccmon` to watch your agents.
+
+## Features
+
+- **Real-time monitoring** — watch subagent status, output, and activity as they run
+- **Session filtering** — view agents from the current project, a specific project, or all projects
+- **Status tracking** — running, completed, interrupted, or unknown states with visual indicators
+- **Auto-refresh** — updates every 0.5 seconds without manual intervention
+- **Stale expiry** — completed/interrupted agents are automatically removed after 10 minutes of inactivity
+- **Manager agent visibility** — shows which specialised agent is currently running in manager-type agents
+
+## Requirements
+
+- Python 3.11+
+- Poetry
+
+## Install
+
+### Homebrew (macOS, recommended)
+
+```bash
+brew install einerlei/tap/ccmon
+```
+
+### pipx (cross-platform)
+
+```bash
+pipx install ccmon
+```
+
+### pip
+
+```bash
+pip install ccmon
+```
+
+### Development setup
+
+```bash
+git clone https://github.com/einerlei/ccmon.git
+cd ccmon
+poetry install
+poetry run ccmon
+```
+
+## Usage
+
+```bash
+ccmon
+ccmon --project /path/to/project
+ccmon --all
+```
+
+## Key bindings
+
+| Key | Action |
+|-----|--------|
+| `r` | Manual refresh |
+| `q` | Quit |
+
+## Architecture
+
+The monitor is a single-file Python application using the Textual TUI framework.
+
+**Data sources:**
+- Sessions: `~/.claude/sessions/*.json` — contains PID, working directory, and session ID
+- Subagents: `~/.claude/projects/{project-dir}/{session-id}/subagents/` — per-agent metadata and message logs
+
+**How it works:**
+1. Loads active sessions from the sessions directory, filtering by project if specified
+2. For each live session, discovers subagents and reads their `.meta.json` (metadata) and `.jsonl` (messages)
+3. Infers agent status by analysing message history and checking process liveness
+4. Expires completed/interrupted agents after 10 minutes without activity
+5. Renders a two-column grid of agent panes with scrolling output
+6. Refreshes every 0.5 seconds to keep the view current
+
+## Development
+
+```bash
+# Install with dev dependencies
+poetry install
+
+# Run tests
+poetry run pytest -q
+
+# Lint and format
+poetry run ruff check
+poetry run ruff format --check
+
+# Run the monitor
+ccmon
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+All code must pass `ruff check` and `ruff format --check`. Add tests for new functionality.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)

ccmon-0.5.4/README.md

@@ -0,0 +1,108 @@
+# ccmon
+
+Terminal monitor for Claude Code sessions and subagents in real time. Run `ccmon` to watch your agents.
+
+## Features
+
+- **Real-time monitoring** — watch subagent status, output, and activity as they run
+- **Session filtering** — view agents from the current project, a specific project, or all projects
+- **Status tracking** — running, completed, interrupted, or unknown states with visual indicators
+- **Auto-refresh** — updates every 0.5 seconds without manual intervention
+- **Stale expiry** — completed/interrupted agents are automatically removed after 10 minutes of inactivity
+- **Manager agent visibility** — shows which specialised agent is currently running in manager-type agents
+
+## Requirements
+
+- Python 3.11+
+- Poetry
+
+## Install
+
+### Homebrew (macOS, recommended)
+
+```bash
+brew install einerlei/tap/ccmon
+```
+
+### pipx (cross-platform)
+
+```bash
+pipx install ccmon
+```
+
+### pip
+
+```bash
+pip install ccmon
+```
+
+### Development setup
+
+```bash
+git clone https://github.com/einerlei/ccmon.git
+cd ccmon
+poetry install
+poetry run ccmon
+```
+
+## Usage
+
+```bash
+ccmon
+ccmon --project /path/to/project
+ccmon --all
+```
+
+## Key bindings
+
+| Key | Action |
+|-----|--------|
+| `r` | Manual refresh |
+| `q` | Quit |
+
+## Architecture
+
+The monitor is a single-file Python application using the Textual TUI framework.
+
+**Data sources:**
+- Sessions: `~/.claude/sessions/*.json` — contains PID, working directory, and session ID
+- Subagents: `~/.claude/projects/{project-dir}/{session-id}/subagents/` — per-agent metadata and message logs
+
+**How it works:**
+1. Loads active sessions from the sessions directory, filtering by project if specified
+2. For each live session, discovers subagents and reads their `.meta.json` (metadata) and `.jsonl` (messages)
+3. Infers agent status by analysing message history and checking process liveness
+4. Expires completed/interrupted agents after 10 minutes without activity
+5. Renders a two-column grid of agent panes with scrolling output
+6. Refreshes every 0.5 seconds to keep the view current
+
+## Development
+
+```bash
+# Install with dev dependencies
+poetry install
+
+# Run tests
+poetry run pytest -q
+
+# Lint and format
+poetry run ruff check
+poetry run ruff format --check
+
+# Run the monitor
+ccmon
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+All code must pass `ruff check` and `ruff format --check`. Add tests for new functionality.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)