agentevo-sdk

Client SDK, agentevo CLI, and agent adapters (Claude Code, Codex) for Agentevo — CI/CD for agent intelligence.

Run this in a project where you have used Claude Code. The first line installs the agentevo CLI; pipx install agentevo-sdk works too (Python 3.10+). A bare pip install is refused by macOS Homebrew and Debian/Ubuntu system Pythons (PEP 668), so use it only inside a virtualenv. Every line is copy-safe (no ids to paste between commands), and nothing below talks to the cloud:

uv tool install agentevo-sdk
agentevo capture --latest
agentevo compile --latest --tenant your-org --project web
agentevo verify --latest --local
agentevo promote --latest --to Verified --local
agentevo recall "fix flaky test" --capabilities Bash,Edit,Read

• capture --latest captures the newest Claude Code session for the current directory. It reads $CLAUDE_CONFIG_DIR/projects, else ~/.claude/projects. If no session exists for this directory, the error lists every folder it looked in. You can also pass files, one or many: agentevo capture <file.jsonl>, or --adapter codex for Codex transcripts.
• compile --latest compiles the session captured last. verify --latest and promote --latest --to <Verified|Trusted> act on every object version that compile created, and each result lists them under acted_on. Re-running is safe: versions already in the requested state are listed under unchanged. The explicit forms keep working: agentevo verify <object-id> <version> --local and agentevo promote <object-id> <version> Verified --local.
• Everything lands in the workspace default (the one every console account starts with), in ~/.agentevo/workspaces/default/vault.db. --workspace (or AGENTEVO_WORKSPACE) picks another workspace, with its own vault. A vault an earlier release kept at ~/.agentevo/vault.db keeps working for the workspace it was created with (demo was the old default: pass --workspace demo).
• Vault keys live in your OS keychain. On a machine without one (SSH boxes, containers, CI), set AGENTEVO_VAULT_KEY first, for example export AGENTEVO_VAULT_KEY=$(openssl rand -hex 32), and keep it: the vault opens only with that key. Without either, capture stops and says so; no vault is written.
• recall returns Verified and Trusted objects that share at least half of the query's words. It checks the object and the prompt of the session it came from. An unrelated query returns nothing plus a hint. --capabilities must cover the tools a skill uses (recall reports filtered_by_capabilities and a hint otherwise).
• Trusted needs 3 independent passing runs (5 for destructive skills). One run is never enough, however often it is re-verified.
• Global flags (--workspace, --vault, --base-url, --key-provider, --device-id) go before the subcommand: agentevo --workspace acme capture --latest. Put one after it and the usage error prints the corrected command.

See what it saved you

agentevo report --json

report --json prints one JSON object (schema: agentevo.report/v1) built from this workspace's vault audit log; plain agentevo report writes the same numbers to an HTML file. Every number is labelled:

• measured: counts Agentevo recorded. Sessions captured, secrets redacted before storage (redactions_stored, by detector), objects by state and type, time from the first capture to the first Verified skill, recalls served and the recall hit rate, sessions that reused a skill, guard decisions and repeat mistakes caught (a learned guard stopped the change it was learned from). A recall hit only means recall returned something; whether it helped shows in reuse.after_recall. definitions spells out each measured number.
• estimated: a stated formula applied to measured counts, never presented as measured. Tool calls saved is, over reuse sessions that succeeded, max(0, tool calls of the session the skill was learned from minus tool calls of the reuse session). Active minutes saved is the same difference over active time (gaps of at most 10 minutes between events). Guard tool calls avoided is, per catch, the tool calls the guard's source session spent from the guarded change to the failure it caused. Each formula is repeated under estimated.formula.

compile records reuse and lists it under reused. A session reuses a skill when it repeats the skill's edits and test runs in order (at least 2 of them, covering at least 60%) after the skill reached Verified or a recall returned it, or when it names the skill. To name it, run agentevo recall "<task>" --use <object-id> before or during the session (up to 30 minutes before its first event), or put agentevo:use <object-id> in the prompt. A skill never counts as reused by the session it was learned from.

Recall, guard, capture and compile write these audit entries locally and send nothing anywhere. They hold object ids, versions, states, decisions, counts, ranks and relevance scores, plus a keyed digest of the recall query. They never hold the query, prompts, commands, paths or tool output.

Raw data stays local by default. The cloud is opt-in:

agentevo login
agentevo sync mode --set searchable --terms-version 2026-09-21 --yes
agentevo sync push
agentevo recall "fix flaky test" --capabilities Bash,Edit,Read --cloud

login asks for a key from the console (API keys) and checks it against the cloud before storing it in your OS keychain; set AGENTEVO_PAT instead to skip the prompt (on a machine without an OS keychain, such as CI, the variable is all the CLI needs and login only checks it). login reports "stored": true only when the key reads back from the keychain; a keyring that keeps nothing (the null backend) gets "stored": false and a note that AGENTEVO_PAT is the key's source. The CLI talks to the hosted API, https://api.agentevo.sh; point --base-url (or AGENTEVO_BASE_URL) at a self-hosted server instead. sync push queues locally, and says so, when the cloud is unreachable. Pushing from a second or fresh vault lists versions the cloud already holds under already_present (exit 0). In a local_only workspace (the default, or after an owner downgrades it) sync push sends nothing and exits 1 with FORBIDDEN. The message names the exact consent command to run, and details.consent_command holds it too. Reading the workspace's sync mode is a billable request, so sync push and sync pull read it at most once every 10 minutes and remember it in the vault (a local_only workspace is read on every sync). sync mode --set makes the next sync read it again. The cloud checks the mode on every push: when an owner changed it elsewhere, the cloud refuses the push and stores nothing, and sync push reads the mode again and pushes once more.

Objects pulled onto another machine arrive as Candidates, because trust never transfers between machines. sync pull says so. recall withholds them, but counts matching ones under withheld_pulled_candidates, lists them under pulled_candidates, and gives the commands to run from your checkout: agentevo verify <object-id> <version> --local --workdir . replays the object's test command there, then agentevo promote <object-id> <version> --to Verified --local. Without --workdir the verify is inconclusive and says why: the evidence stays on the machine that pushed it.

Searchable sync sends sanitized step templates and fingerprints only. File contents, diffs, command output, prompts and absolute paths stay on your machine. Opaque Relay sends the full steps, end-to-end encrypted under a workspace key the cloud never sees: create it once, on the first machine, with agentevo sync key --init, and carry it to each other machine with sync key --export FILE there and sync key --import FILE (machines that share AGENTEVO_VAULT_KEY already share it). Sync identifies your machine by a random device id that the vault creates once; your username and hostname are never sent. --tenant your-org is only a label while you work offline: sync push sends a workspace's objects to the tenant you are logged in to and lists the ones it relabeled. Cloud rows show cloud_state. The managed copy reaches Trusted only with independent evidence from a device. One run is never enough for Trusted. See agentevo.sh for more.

License

Apache License 2.0 — see the LICENSE file shipped with this package.