oxen-team 0.1.1

A lightweight framework for managing AI research experiments with Claude Code

ox

A lightweight framework for managing AI research experiments with Claude Code at the heart of the workflow.

Like a good ox: strong work ethic, no tangles. Think of it as a yak that went to finishing school.

Install

uv add oxen-team

Quick Start

# Create a project
ox init my-research
cd my-research
uv sync

# Create a study
ox new study "learning rate schedules"

# Create an experiment
ox new experiment learning-rate-schedules "cosine-baseline" --tag lr --tag cosine

# Check what a script accepts
ox config-schema src/my_research/scripts/train.py

# Run it
ox run src/my_research/scripts/train.py \
  --config studies/learning-rate-schedules/experiments/cosine-baseline/config.yaml \
  --experiment cosine-baseline

# Query results
ox ls --study learning-rate-schedules
ox query "status = 'completed' ORDER BY updated_at DESC"
ox show cosine-baseline

How It Works

Write a training script with two conventions:

from pydantic import BaseModel
from ox import Tracker

class Config(BaseModel):
    lr: float = 1e-3
    batch_size: int = 32
    epochs: int = 10

def main(config: Config, tracker: Tracker) -> None:
    for epoch in range(config.epochs):
        loss = train_epoch(model, config)
        tracker.log({"loss": loss, "epoch": epoch}, step=epoch)

No argparse. No decorators. No registration. The Config class is your argument spec — ox generates CLI flags from the Pydantic model automatically.

Philosophy

• Get out of the agent's way. Claude Code is the orchestrator. Ox provides composable primitives.
• Convention over configuration. A Config class and a main function. That's it.
• Everything in the repo. Experiments, configs, notes — all in version control.
• Framework-agnostic. Use PyTorch, JAX, whatever. Ox handles config and tracking.
• Skills over scaffolding. Complex workflows are Claude Code skills, not framework code.

Project Structure

After ox init, you get:

my-research/
├── CLAUDE.md                 # Master prompt for Claude Code
├── .claude/skills/           # Claude skill files (yours to customize)
├── ox.yaml                   # Project config
├── studies/                  # Research studies and experiments
├── src/my_research/scripts/  # Training entrypoints
└── .ox/metrics/              # Local tracker output (gitignored)

CLI Commands

Command	Description
ox init <name>	Scaffold a new project
ox new study <name>	Create a study
ox new experiment <study> <name>	Create an experiment
ox run <script> [--config PATH] [--experiment ID]	Run a training script
ox ls [--study S] [--status S] [--tag T]	List experiments
ox query <expression>	SQL query over experiments
ox show <id>	Show experiment details
ox status	Show running experiments
ox config-schema <script>	Print config JSON schema

Tracker

Metrics are logged via the Tracker interface:

tracker.log({"loss": 0.5, "acc": 0.9}, step=10)

Backends:

• local (default) — JSONL files in .ox/metrics/
• wandb — Weights & Biases (uv add 'oxen-team[wandb]')

Configure in ox.yaml:

tracker:
  backend: local
  output_dir: .ox/metrics

License

MIT