Overmind

Overmind is two things in one package:

• Tracing SDK — drop-in observability for LLM agents. Decorate your code, get structured traces of every LLM call and tool invocation.
• Optimizer client — a thin, agent- and codebase-agnostic executioner. The optimization loop (experiments → iterations → candidates → commands) is configured and driven server-side by the Overmind Console. This repo just registers your machine, leases queued commands, runs them against your repo, and reports results back.

Documentation: Overmind guide

Console: console.overmindlab.ai

Install

uv tool install overmind
# or
pipx install overmind

Tracing

Wire up tracing once at process start, then annotate the functions you want traced:

import overmind

overmind.init(service_name="my-agent", providers=["openai", "anthropic"])  # reads OVERMIND_API_KEY from the environment

@overmind.entry_point()
def run(input_data: dict) -> dict:
    return {"response": handle(input_data)}

@overmind.tool()
def search(query: str) -> list[dict]:
    ...

Available decorators/helpers: entry_point, workflow, tool, function, plus start_span (context manager), set_tag, set_user, and capture_exception for Sentry-style annotations on the current span.

Optimize

Set up and configure the experiment (agent, policy, dataset, iterations) in the Console. Then, from the root of the repo you want optimized:

export OVERMIND_API_KEY=<your-api-key>
overmind optimize

This registers the current machine with the backend and loops forever: it leases queued commands from the experiment you configured in the Console, checks out the iteration's git branch (applying its candidate diff as a commit), runs the shell command against your repo, and reports the result back. Stop it any time with Ctrl-C; re-running is safe and idempotent per iteration branch.

Options / environment variables

Flag	Env var	Default	Description
--api-key	OVERMIND_API_KEY	(required)	Sent as X-Api-Key.
--api-url	OVERMIND_API_URL	https://api.overmindlab.ai	Backend base URL.
--cwd	OVERMIND_CWD	current directory	Repo root to run commands in.
--poll-interval	OPTIMIZER_POLL_INTERVAL	5	Idle poll seconds.
--heartbeat-interval	OPTIMIZER_HEARTBEAT_INTERVAL	60	Idle "still alive" log interval, seconds.
--log-level	OPTIMIZER_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR.

Warning

The Console can hand this client arbitrary shell to run (shell=True, guarded only by a per-command timeout). Only point it at a backend you trust.

Skills

Use these from Cursor, Codex, or Claude Code to scaffold agents and configure telemetry without leaving your coding environment.

overmind skills list --verbose
overmind skills sync <skill-name>

Skill	What it does
Overmind Register Agent	Create or register an Overmind agent entrypoint and bootstrap provider config.
Overmind Generate Agent	Build an agent from scratch using natural language.
Overmind Telemetry	Configure Overmind tracing for your AI project.
Ponytail	Review an optimization report and adjust the policy, eval spec, or dataset.

CLI reference

overmind optimize [OPTIONS]         Register this machine and run the optimization loop
overmind skills list [--verbose]    List installed/available skills
overmind skills sync <name>...      Sync one or more skills to the latest version

Run overmind <command> --help for full flag documentation.