Skip to content

Add ncc utility skill: host operational and health CLI#2971

Open
zivisaiah wants to merge 1 commit into
nanocoai:mainfrom
zivisaiah:skill/ncc-operational-cli
Open

Add ncc utility skill: host operational and health CLI#2971
zivisaiah wants to merge 1 commit into
nanocoai:mainfrom
zivisaiah:skill/ncc-operational-cli

Conversation

@zivisaiah

Copy link
Copy Markdown

Type of Change

  • Feature skill - adds a channel or integration (source code changes + SKILL.md)
  • Utility skill - adds a standalone tool (code files in .claude/skills/<name>/, no source changes)
  • Operational/container skill - adds a workflow or agent skill (SKILL.md only, no source changes)
  • Fix - bug fix or security fix to source code
  • Simplification - reduces or simplifies source code
  • Documentation - docs, README, or CONTRIBUTING changes only

Description

Adds ncc (NanoClaw Control), a host-side operational and health CLI, as a sibling to ncl. Where ncl does central-DB entity CRUD (agent groups, wirings, roles), ncc covers the operational surface ncl does not: host service lifecycle, a component health scan, and visibility into scheduled work.

Why. There is no shipped tool for host service control or health inspection. Service management is documented only as raw launchctl/systemctl commands, and /debug is instruction-only with no executable scanner. ncc fills that gap.

How it works. A standalone Python 3 script (standard library only). It reads the session and central SQLite DBs directly and shells out to launchctl/systemctl/docker, so it keeps working even when the host service is down, which is when health and service start matter most. Cross-platform: launchd on macOS, systemd (--user) on Linux, both auto-detected (the unit is discovered, not hardcoded). It mirrors ncl's UX: subcommands, --json, table output, exit codes.

Commands:

  • ncc service status|start|stop|restart
  • ncc health [--json] scans the service, Docker daemon, central DB integrity, host disk, the OneCLI gateway, each agent container (autocompact thrashing, zombie processes, heartbeat freshness), recent permanent delivery failures, and overdue scheduled tasks. Exits 2 on a hard FAIL, 0 otherwise (WARN is advisory).
  • ncc tasks [--json] running containers plus pending ad-hoc tasks
  • ncc crons [--json] recurring scheduled tasks
  • ncc --version, ncc --help, ncc <command> --help

How it was tested. Installed via the SKILL.md steps on macOS (launchd) against a live install and exercised every subcommand, confirmed the --json output parses, and verified the health exit codes (0 on OK/WARN, 2 on FAIL) and that the symlinked binary resolves the checkout from any working directory. The Linux/systemd path was validated in a Python 3.12 Linux container: platform detection, unit discovery, status parsing, correct systemctl invocation, and the SQLite/disk/heartbeat reads. Real-daemon validation on a live systemd host is still pending. On Linux the service is a systemctl --user unit, so ncc must be run as the service's owning user; this is documented in the skill's troubleshooting.

Usage. ncc health, ncc service restart, ncc crons --json. Install steps are in the SKILL.md.

For Skills

  • SKILL.md contains instructions, not inline code (code goes in separate files)
  • SKILL.md is under 500 lines
  • I tested this skill on a fresh clone

ncc is a host-side operational and health CLI, a sibling to ncl. It covers
what ncl does not: host service lifecycle (launchd on macOS, systemd --user on
Linux, auto-detected), a component health scan (exit 2 on hard fail), and
visibility into scheduled/cron tasks. Standalone Python 3 stdlib script, so it
works even when the host service is down; reads the SQLite DBs directly and
shells to launchctl/systemctl/docker. Mirrors ncl's UX (subcommands, --json,
table output, exit codes).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

follows-guidelines PR was created using the current contributing template PR: Skill Skill package or skill-related changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant