agents-live

Take your agents live. agents-live adds safe, local automation to the Claude Code and GitHub Copilot agents you already use - cron and file-watch dispatch, deterministic pre/post processing, safety wrappers, and operations. It does not replace your agents: an agent stays one Markdown file with the same prompt. A few frontmatter fields say when it runs (a cron schedule, a watched directory, or both) and how (the agent CLI, execution mode, optional pre/post scripts):

---
runtime: claude            # unattended execution adapter
mode: plan                 # read-only; a handler script does the writing
watchPath: notes/inbox/    # or schedule: "0 8 * * *", or both
post-processor: file-notes.sh
---
For each new file in notes/inbox/: add frontmatter and tags, fix the
title, decide where it belongs in the vault, and emit JSON:
{ "moves": [{ "from": "...", "to": "...", "content": "..." }] }

Drop a raw note into notes/inbox/ and the watcher fires within seconds; one agent run later the note is cleaned up and filed. The agent thinks, a script acts: the agent decides, but the only thing that touches your files is a deterministic handler you own.

Safe by default

Write access is a ladder with an explicit final rung:

1. plan (the default) - the agent runs read-only and emits JSON; a runner validates it (JSON Schema, size caps, path roots, provenance) and hands it to your deterministic handler.
2. pipeline - the agent's tool surface narrows to a schema-checked put/get side-channel that your pre/post-processors mediate, over a token-protected loopback endpoint that exists only for the duration of one run.
3. write - full write access: the last option, an explicit per-agent opt-in.

This ladder is tool policy, not a sandbox - agents inherit your local account's privileges unless you configure stricter CLI or OS isolation.

Lightweight

No framework to learn, no APIs to call, no daemon to maintain - just things you use every day: git, files, markdown, cron, and scripts. Cron and inotifywait do the triggering; agents-live adds activation, debounce, concurrency, structured logs, and per-run token cost. If you can read a crontab, you can audit the whole system. No application daemons or gateways, no externally reachable inbound ports, no databases (plain-text JSONL logs, aged into monthly Parquet archives). The only persistent processes are one small watcher loop per file-watch agent; cron-only agents need none.

Install

uv tool install agents-live   # or: uv tool install <path-to-wheel>

Generate shell completion from the same command spec as the CLI:

source <(agents-live completions bash)
# zsh: source <(agents-live completions zsh)

On interactive terminal invocations, agents-live checks PyPI for a newer stable release when its shared cached result is missing or one hour old. The result is stored under $XDG_CACHE_HOME/agents-live/ (normally ~/.cache/agents-live/). For ordinary commands, the refresh runs in the background and is skipped for scheduled/internal, quiet, JSON, piped, or redirected invocations. Network and cache failures never affect the command. This request sends only ordinary package-index request metadata; it does not include project or agent data. agents-live doctor is the exception: it always performs a fresh check and updates the cache. Checks never install updates in the background. Run agents-live upgrade to reinstall the uv-managed runtime at the latest stable release without dropping co-installed requirements, converge project-declared plugins, and then refresh managed skill payloads using the newly installed CLI.

Bare agents-live upgrade works outside a project and refreshes the current initialized project plus every available registered repository. An explicit --repo PATH|ALIAS limits payload refresh to that project. Use --runtime-only or --skills-only to run one half of the workflow. Unavailable registered repositories are reported without blocking other refreshes. init remains the first-time project setup command.

Quick start

cd your-repo
agents-live doctor    # verify cron, inotifywait, and agent CLIs
agents-live init      # layout + config marker + skill payload
# copy a starter from .claude/skills/agents-live/templates/ into .claude/agents/
agents-live run my-agent        # test once, in the foreground
agents-live start my-agent      # activate cron/watcher triggers
agents-live status
agents-live logs
agents-live stop my-agent       # deactivate and keep its configuration

Projects that need plugin-provided adapters or registry ownership declare the committed wheel in .agents-live.toml:

[plugins]
example-plugin = { path = "Agents/plugins/example-plugin-1.0.0-py3-none-any.whl", sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }

The path is repository-relative and the optional SHA-256 pins its contents. init, start, and upgrade converge declarations into the host-global uv tool environment. doctor reports missing or broken entry points, while repos add only reports what a later activation will install.

For work across projects, register normalized absolute repository paths in the user configuration ($XDG_CONFIG_HOME/agents-live/config.toml, normally ~/.config/agents-live/config.toml):

agents-live repos add ~/repos/<target-project>   # registered under its directory name
agents-live repos default ~/repos/<target-project> # registers the path if needed
agents-live --repo <target-project> status       # directory name also works
agents-live status --all-repos
agents-live doctor --all-repos
agents-live dashboard --all-repos   # read-only repository selector

Selection precedence is explicit --repo path or registered name, AGENTS_LIVE_REPO, the nearest local marker, markerless-git adoption for run/start, then the configured default. A default never overrides the current project. Aggregate commands are read-only; lifecycle mutations always target one selected repository, and persisted commands pin its absolute path.

Requirements

• Python 3.12+ and uv
• crontab (scheduled agents), inotifywait (file watchers; preflight is trigger-derived, so cron-only setups don't need inotify)
• An agent CLI for agent-backed definitions: claude or copilot

Linux-first: Ubuntu on WSL is the reference platform, Windows support is partial, and macOS is untested. agents-live doctor reports exactly what this host is missing.

Documentation

The /agents-live skill is optional conversational support for the CLI: agents-live init installs it for Claude Code, every flow it drives is an ordinary agents-live command, and the CLI is fully usable without it.

• Overview
• Architecture
• Commands
• Starter templates
• SKILL.md - full reference