@agentevo-cli/agentevo

One-command launcher for the Agentevo CLI — local-first memory for AI agents (skills, guards, regression tests, workflows).

Requirements

• Node.js 18+ (for this launcher)
• Python 3.10+ on PATH as python3.13 … python3.10, python3 or python (Windows: py -3, python or python3), with its standard venv module. The CLI itself runs on Python. Debian and Ubuntu ship venv separately: sudo apt install python3-venv.
• Network access to PyPI on the first run of each launcher version.

The launcher never installs into your system Python. It makes its own virtualenv, so Pythons that refuse a bare pip install (PEP 668: macOS Homebrew, Debian and Ubuntu) work as they are.

This README documents 0.2.9. The commands below require the matching SDK on PyPI and launcher on npm. Source metadata can precede publication: check the repository release record before installing a source checkout's version. The launcher refuses packaging when its consumer lock is unsealed.

Usage

npx @agentevo-cli/[email protected] init
npx @agentevo-cli/[email protected] capture --help

Or install globally:

npm install -g @agentevo-cli/[email protected]
agentevo status

On first run the launcher creates a virtualenv in an isolated, versioned cache and installs the pinned agentevo-sdk into it from PyPI. The pin is exact and equals this package's version (launcher X.Y.Z installs agentevo-sdk==X.Y.Z). Its third-party dependencies (httpx, keyring, cryptography and their own dependencies) come only from the bundled requirements.lock, installed with pip --require-hashes: each file must match a sha256 recorded when the release was audited, so a fresh install never resolves a newer or tampered dependency. pip check then confirms the environment is complete. The cache is ~/.cache/agentevo-cli/<version>/ (under $XDG_CACHE_HOME when set, %LOCALAPPDATA%\agentevo-cli\<version>\ on Windows). AGENTEVO_CACHE_DIR replaces the base directory, giving $AGENTEVO_CACHE_DIR/agentevo-cli/<version>/. Later runs reuse it, and a broken entry is rebuilt. Launcher installation leaves your shell, project and global Python unchanged. The CLI commands you request can create local project and vault files. Ordinary commands return structured JSON results/errors; help, version and stdio MCP use their own formats.

Prefer no Node? uv tool install agentevo-sdk==0.2.9 (or pipx install agentevo-sdk, Python 3.10+) installs the same agentevo CLI directly. npm install -g and a uv or pipx install each put an agentevo command on PATH, so pick one.

Start local memory

In your project, run one command:

npx @agentevo-cli/[email protected] init

No account or model API key is needed. Initialization creates local memory; it does not connect a coding agent or create a learned skill. Use the public setup guide to preview and review the optional host connection. Empty memory is a normal first-run result.

Optional: learn from a completed task

The full manual recipe below is for a project where you have used Claude Code and have working project tests. It includes repeatable setup checks; you do not need all these steps to initialize. Nothing below uploads to AgentEvo. capture --latest picks the newest Claude Code session for the current directory, and initialized project identity binds latest selection and default local recall:

npx @agentevo-cli/[email protected] skills install
npx @agentevo-cli/[email protected] init
npx @agentevo-cli/[email protected] doctor
npx @agentevo-cli/[email protected] capture --latest
npx @agentevo-cli/[email protected] compile --latest
npx @agentevo-cli/[email protected] verify --latest --local --workdir .
npx @agentevo-cli/[email protected] promote --latest --to Verified --local
npx @agentevo-cli/[email protected] recall "fix flaky test" --capabilities Bash,Edit,Read
npx @agentevo-cli/[email protected] report

Commands

| Command | What it does | |---|---| | login / logout / status | Check and store / remove / show your cloud PAT (keychain; presence only, never printed) | | skills | List or install the bundled agent skills (install writes SKILL.md files; existing files are kept unless --force) | | capture | Ingest transcripts into the local vault (--latest: newest Claude Code session here) | | compile | Turn a captured session into Candidate skills, guards and regression tests | | verify / promote | Verify and promote (--local on this machine, or in the cloud); --latest acts on the last compile | | recall | Project-local advice by default after init; --cloud is explicit authenticated recall | | experience read | Read one eligible local historical implementation as untrusted data for current validation; no execution or cloud fallback | | guard | Evaluate a proposed action (ALLOW, DENY, REQUIRE_APPROVAL, …) | | sync / job | Push to / pull from the managed plane; poll async jobs | | usage | Show quota usage | | report | Report observed activity, signed historical reuse estimates and missing value evidence |

init / doctor set project labels and read-only status. Retain its key; explicit Claude setup/profile/review commands are separate from CLI installation. Inspect verification JSON, because interactive zero exit does not prove passing replay or task correctness. Strict CI needs a reviewed pinned manifest; workflows run only their explicitly reviewed bounded family. Actual net savings need real matched charges/outcomes and remain unknown.

Each workspace (default: default, the one every console account starts with) keeps its own vault under ~/.agentevo/workspaces/. Explicit cloud commands (login, sync, recall --cloud) talk to the hosted API, https://api.agentevo.sh, unless --base-url or AGENTEVO_BASE_URL points elsewhere.

Validated repeat reuse

SDK 0.2.9 includes experience.read and the opt-in Python try_reuse adapter. A trusted host must supply its existing current-contract sandbox validator and normal action permissions before skipping generation. Installing or initializing the CLI alone does not enable that orchestration. Use existing working files first; a recall hit alone is not proof of money saved. Inspect agentevo experience read --help and the SDK's integration requirements before adopting the new read path.

Privacy

Raw prompts, outputs, and code stay on your machine by default. Searchable sync sends sanitized templates and fingerprints and identifies the machine by a random device id. An explicit implementation read returns C3 code to the calling host, which may forward it to its model provider; review that host's handling before using the read. The CLI does not upload that body or grant execution permission. See agentevo.sh.

License

Apache-2.0