OS-adjacent agent runtime — detect, watch, coalesce/debounce/queue, FUSE, mesh, thermal.

Backbone-2 graphite palette · brand SVG ships in `sharecli-iconset` worktree (Backbone-2 source-of-truth) · visual identity demo

sharecli is an OS/kernel-adjacent agent runtime for hosts running many coding agents at once. It does not wrap vendor agent binaries (for example Claude Code). It discovers agents by scanning processes and matching known patterns, watches CPU / memory / network / FDs and syscall-relevant IO, and under contention speculatively coalesces redundant concurrent work across agents (read coalesce, lock-wait cache, thermal gate). An agent mesh coordinates that shared substrate.

Core crates:

Harbor / agent-eval soft harness lives outside this repo: suite-facing stubs in phenotype-tooling/crates/benchora (harbor-soft/); Harbor fork/env in portage-temp (standing home while portage awaits GH restore). See ADR 0002.

The CLI also ships a declarative supervisor surface (TOML config, hot-reload, HTTP health/metrics, tray/dashboard, plugins) for process lifecycle on top of that hypervisor stack.

Install sharecli with one of the following methods:

# Install from source via crates.io
cargo install sharecli

# Install a prebuilt binary via cargo-binstall
cargo binstall sharecli

Homebrew formula lives at Formula/sharecli.rb (version tracks Cargo.toml / latest tag v0.3.0). Bottle sha256 is filled for v0.3.0 darwin — see docs/ops/brew-bottle.md and docs/deploy.md.

brew install --HEAD Formula/sharecli.rb
# or from tap when published:
brew install sharecli

Remove local config/state after uninstalling the binary:

sharecli uninstall              # package-manager guidance + path listing
sharecli uninstall --purge-data # delete ~/.config/sharecli and state dirs

Container (non-root + /healthz healthcheck):

podman build -f Containerfile -t sharecli .
podman run --rm -p 9000:9000 sharecli

Same capability set on every host: CLI + serve, process verbs, tray/menubar (or WSL bridge), dashboard at http://127.0.0.1:9000/ (macOS also native window). Details: docs/deploy/FINALITY.md.

cargo binstall sharecli
# or: gh release download <tag> -p 'sharecli-*-apple-darwin.tar.gz'
# tray/desktop: sharecli-desktop-macos-*.tar.gz from the same release

# CLI zip from GitHub Releases: sharecli-*-pc-windows-msvc.zip
# Tray: sharecli-tray-windows-*.zip (beta; unsigned)
# Dashboard: start `sharecli serve` then http://127.0.0.1:9000/

# gh release download <tag> -p 'sharecli-*-unknown-linux-gnu.tar.gz'
# tray: sharecli-tray-linux-*.tar.gz
cargo binstall sharecli   # CLI alternative

# Inside WSL (same Linux CLI artifact):
sharecli serve --bind 0.0.0.0:9000
# From Windows: http://127.0.0.1:9000/  or ShareCLITray → that port
# Optional: WSLg + sharecli-tray-linux
just wsl-parity-check

Deploy surface matrix: docs/deploy.md.
Finality + OS parity: docs/deploy/FINALITY.md.

Remove the binary for your install method, then optionally delete local data:

# crates.io / cargo-binstall
cargo uninstall sharecli

# Homebrew (once tapped)
brew uninstall sharecli

# Manual / from-source install
rm -f "$(command -v sharecli)"
# or: rm -f /usr/local/bin/sharecli ~/.local/bin/sharecli ~/.cargo/bin/sharecli

Optional data cleanup (config, pane map, runtime lock):

rm -rf ~/.config/sharecli
# Windows PowerShell: Remove-Item -Recurse -Force "$env:APPDATA\sharecli"

• Agent detect / watch / coalesce — proc-pattern discovery (no vendor-bin wrap), resource watch, thermal gate, CoalesceCache + optional FUSE IO share (sharecli-core / fuse / ipc / fleet).
• Config hot-reload — uses notify to watch the config file and apply changes to the running supervisor in place (no restart required).
• Health-check scheduler — runs periodic HTTP/TCP/exec probes against each managed process and tracks pass/fail history.
• Schema validation — every config is validated against a strict JSON Schema before reload, so a typo never crashes the running supervisor.
• Desktop + webhook notifications — surface state transitions (started, crashed, unhealthy, recovered) to the OS notification daemon and to arbitrary HTTP webhooks with HMAC-SHA256 signatures.
• Shell completions — generates bash, zsh, fish, and powershell completions from the live CLI definition.
• proc-compose integration — discovers and supervises the services declared in a proc-compose.toml alongside the main config.
• Prometheus metrics — exposes counters, gauges, and histograms for process state, restarts, health checks, and request latency at /metrics/prometheus.
• Plugin registry — discover, install, and run executable plugins that extend sharecli with new subcommands (see sharecli plugin).

cargo install sharecli

This installs the sharecli binary into ~/.cargo/bin.

Download a release archive from the releases page and extract the binary somewhere on your PATH:

tar -xzf sharecli-<target>.tar.gz
sudo install -m 0755 sharecli /usr/local/bin/sharecli

Note: tags v0.1.0–v0.3.0 currently have no attached assets. The release workflow matrix builds sharecli-x86_64-unknown-linux-gnu.tar.gz and sharecli-aarch64-apple-darwin.tar.gz for future publishes.

git clone https://github.com/KooshaPari/sharecli.git
cd sharecli
cargo build --release
./target/release/sharecli --version

1. Drop a config file at ./sharecli.toml:

   [server]
   bind = "127.0.0.1:9090"
   
   [[process]]
   name = "echo"
   command = ["sh", "-c", "while true; do echo tick; sleep 5; done"]
   
   [process.healthcheck]
   kind = "tcp"
   port = 0
   interval = "10s"

2. Start the supervisor:

   sharecli serve

3. Inspect managed processes from the CLI:

   sharecli proc-compose status

4. Generate shell completions (example for zsh):

   sharecli completions zsh > "${fpath[1]}/_sharecli"
   # restart your shell, or: autoload -U compinit && compinit

Other shells: sharecli completions bash, sharecli completions fish, sharecli completions powershell.

The full config schema is documented at docs/configuration.md; the minimal shape is:

# sharecli.toml

[server]
bind          = "127.0.0.1:9090"
log_level     = "info"        # trace | debug | info | warn | error
config_path   = "./sharecli.toml"

[notifications]
desktop       = true
webhook_url   = "https://example.com/sharecli-hook"
webhook_secret = "env:SHARECLI_WEBHOOK_SECRET"  # HMAC-SHA256 signing key

[healthcheck]
default_interval = "10s"
default_timeout   = "2s"

[[process]]
name     = "api"
command  = ["./bin/api", "--port", "8080"]
cwd      = "./"
env      = { RUST_LOG = "info" }
restart  = "on-failure"        # no | always | on-failure
backoff  = { initial = "1s", max = "30s", multiplier = 2.0 }

[process.healthcheck]
kind     = "http"
url      = "http://127.0.0.1:8080/healthz"
interval = "5s"
timeout  = "1s"

Secrets prefixed with env: are resolved from the process environment at start time and never written to disk.

sharecli serve exposes the following endpoints on the configured bind address (default 127.0.0.1:9090). All endpoints respond with JSON unless noted; non-200 responses include a {"error": "..."} body.

A request that targets an unknown process can append ?name=<process-name> to /health/processes.

Dual-licensed under MIT or Apache 2.0, at your option. See LICENSE and LICENSE-APACHE.