AI-Powered CLI#
oxo-flow can use AI (DeepSeek, Claude, OpenAI, or Ollama) to help you create, validate, and fix bioinformatics workflows. AI is optional — no AI code runs unless explicitly enabled.
Design principle: Add one line of config. AI activates automatically on all suitable commands.
Quick Start#
1. Configure Your AI Provider#
oxo-flow supports any AI provider with an OpenAI-compatible or Anthropic-compatible API. Set the provider and your API key via environment variables:
# DeepSeek (OpenAI-compatible)
export OXO_FLOW_AI_PROVIDER=deepseek
export DEEPSEEK_API_KEY="sk-<YOUR-KEY>"
# Claude (Anthropic)
export OXO_FLOW_AI_PROVIDER=claude
export ANTHROPIC_AUTH_TOKEN="sk-ant-<YOUR-KEY>"
# OpenAI
export OXO_FLOW_AI_PROVIDER=openai
export OPENAI_API_KEY="sk-<YOUR-KEY>"
# Any OpenAI-compatible service (Groq, Together, Azure, Fireworks, etc.)
export OXO_FLOW_AI_PROVIDER=openai
export OPENAI_BASE_URL="https://api.groq.com/openai/v1"
export OPENAI_API_KEY="gsk_<YOUR-KEY>"
export OPENAI_MODEL="llama-3.1-70b"
# Any Anthropic-compatible service
export OXO_FLOW_AI_PROVIDER=claude
export ANTHROPIC_BASE_URL="https://your-custom-endpoint"
export ANTHROPIC_AUTH_TOKEN="<YOUR-KEY>"
# Local Ollama (no API key needed)
export OXO_FLOW_AI_PROVIDER=ollama
export OXO_FLOW_AI_API_URL="http://localhost:11434"
export OXO_FLOW_AI_MODEL="llama3"
# Zero-config: if OXO_FLOW_AI_PROVIDER is unset and you already export
# ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (gateway) or OPENAI_API_KEY
# (openai-compatible), oxo-flow auto-detects the provider — no extra
# variables needed. See "Environment Variables" below for the exact rules.
Configuration persists to ~/.oxo-flow/ai_config.json after first use (or to the file named by OXO_FLOW_AI_CONFIG, when set).
2. Enable AI in Your Workflow#
Add one section to your .oxoflow file:
That's it. Now all AI-capable commands auto-activate without extra flags:
oxo-flow dry-run workflow.oxoflow # AI analysis runs automatically
oxo-flow validate workflow.oxoflow # AI semantic validation
oxo-flow run workflow.oxoflow # AI error recovery on failure
3. Generate a New Workflow#
4. Override with CLI Flags#
# Force AI on (even without [ai] section)
oxo-flow dry-run workflow.oxoflow --ai
# Force AI off (even with [ai] section)
# (just don't pass --ai — AI is only auto-detected, never forced)
5. Review and Run#
# Review the generated workflow
cat rnaseq_analysis_with.oxoflow
# Validate it
oxo-flow validate rnaseq_analysis_with.oxoflow
# Run it
oxo-flow run rnaseq_analysis_with.oxoflow
Template Command Reference#
Basic Generation#
Examples:
oxo-flow template "DNA variant calling with BWA and GATK" --ai
oxo-flow template "ChIP-seq peak calling with MACS2" --ai
oxo-flow template "metagenomics taxonomic classification with Kraken2" --ai
With Reference Materials#
Use --from-url or --from-file to provide protocol documents or example workflows:
# From a URL (protocol, documentation, paper methods)
oxo-flow template "scRNA-seq analysis" --ai \
--from-url https://satijalab.org/seurat/articles/pbmc3k_tutorial.html
# From a local file
oxo-flow template "custom QC pipeline" --ai \
--from-file my-protocol.md \
--from-file data/example_output.txt
# Both URL and file
oxo-flow template "exome analysis" --ai \
--from-url https://gatk.broadinstitute.org/ \
--from-file data/cohort_info.csv
Set Output Path#
Control AI Behavior#
# Limit correction rounds
oxo-flow template "RNA-seq" --ai --ai-max-retries 5
# Fresh-draw attempts (best-of-N with early exit): attempt 2..N is only paid
# when earlier attempts fail — the deterministic gates decide
oxo-flow template "RNA-seq" --ai --ai-attempts 2
# Opt into the Scientist Team roles (contract + Curator + review)
oxo-flow template "RNA-seq" --ai --ai-team-profile full
Workflow Explanation (ai explain)#
Explain a workflow in plain language — for newcomers reading an inherited pipeline, and for experienced users evaluating one. Three layers:
- Overview — what the workflow does, its assay domains, entry and final rules
- Step-by-step — each rule's tool, purpose, inputs/outputs, and resources
- Scientific review — deterministic, evidence-backed findings (GATK best practices etc.) explained in plain language
oxo-flow ai explain workflow.oxoflow # beginner-level prose (default)
oxo-flow ai explain workflow.oxoflow --step bwa_mem2_align # focus one rule
oxo-flow ai explain workflow.oxoflow --level expert # parameter-level, efficiency-focused
oxo-flow ai explain workflow.oxoflow --json # machine-readable output
ai explain complements dry-run: dry-run shows the mechanism (what will
execute), explain shows the principle (why each step exists). Every fact
in the explanation is computed deterministically from the workflow definition
plus the embedded knowledge bases (tool table, bioSkills, pipeline graph,
scientific preflight). Model prose is advisory and can omit or misstate a
detail; the deterministic skeleton and findings are authoritative. The
deterministic findings are always printed separately (stderr, or the review
array in --json), so consumers must not treat model prose as the evidence
surface.
--json emits the deterministic skeleton (rule metadata, I/O, resources,
matched knowledge, findings) with model-written prose in dedicated fields —
safe for documentation generators. --level defaults to beginner because
the audience cannot be inferred from the workflow itself; experts opt in.
Degraded mode (no model)#
ai explain exits 0 with the deterministic skeleton whenever the model
layer is unavailable — provider errors, quota limits, dead endpoints, or
explicit disable:
OXO_FLOW_AI_PROVIDER=disabledoverrides any saved provider and is pinned after the saved config loads — a~/.oxo-flow/ai_config.jsoncannot re-enable AI. It produces the skeleton with a "disabled" note on stderr; AI calls fail withAI_NOT_CONFIGUREDwithout contacting a provider.- A failed provider call degrades the same way, with the error summarized
in the note; the skeleton and its knowledge-base grounding (bioSkills,
tool table, pipeline graph) are still emitted in full, and
--jsonconsumers still get the JSON contract (prose fields empty).
{
"workflow_name": "wgs-germline-calling",
"level": "beginner",
"domains": ["read-alignment", "variant-calling"],
"steps": [
{
"order": 1,
"name": "fastp_qc",
"depends_on": [],
"inputs": ["raw/{sample}_R1.fastq.gz"],
"outputs": ["trimmed/{sample}_R1.fq.gz"],
"threads": 4,
"tools": ["fastp"],
"explanation": "Trims adapters and low-quality bases..."
}
],
"review": [
{
"code": "SCI-VQSR-COHORT",
"rule": "vqsr_snps",
"message": "VariantRecalibrator trains on the cohort, but only 3 samples are in this run...",
"suggestion": "stop the pilot before VQSR (-t <rule>) or use hard filtering..."
}
],
"provenance": {"model": "deepseek-v4-pro", "bio_skills": 562, "pipeline_graph_nodes": 78}
}
Provider failure handling#
The provider layer classifies common model failures; tool-argument handling is fail-closed end to end:
- Malformed tool-call arguments fail closed: if a model truncates or
mangles a tool call's arguments JSON, the parser passes the payload
through raw and the orchestrator rejects the call before any tool runs —
the model receives a tool-result message carrying the parse error and a
re-emit instruction. Arguments are never "repaired" to
{}behind the caller's back. Wire-format echoes (Anthropictool_use.input, Ollamaarguments) keep a protocol-valid object fallback, but such a call can no longer execute. - Context overflows are classified and recovered: HTTP 400/413 responses
with context-window markers map to
ContextOverflow; the transcript is compressed (system + recent turns kept, middle turns replaced by a marker) and retried once. A second overflow returns readable guidance instead of burning quota. - Tool results are bounded: every tool result entering a transcript is capped at 16 KiB with a UTF-8-safe head+tail truncation marker, so long lookups cannot silently blow up the context window.
- Offline replay for tests: a scripted provider replays serialized completions (tool calls, errors, delays) through the real code path, so CI covers multi-turn tool-calling and error recovery without an API key.
- Ollama tool-calls are parsed, not dropped: the Ollama
backend now surfaces the model's
tool_calls(ids synthesized positionally, object-or-string arguments both accepted), mapsprompt_eval_count/eval_countinto token usage, and echoes assistant tool-call requests plustool-role results back in the native request shape. Support still varies by model/daemon version, so an orchestrator run that pairs Ollama with a non-empty tool registry logs a one-time warning.
Configuration#
Global Config (~/.oxo-flow/ai_config.json)#
Set OXO_FLOW_AI_CONFIG to an explicit file path to redirect this location
for both reads and writes. It is the hermetic knob for tests and CI: while it
is set the legacy ~/.config/oxo-flow/ai_config.json migration fallback is
skipped, so a redirected process cannot touch the user's real config. Unset
(the default) keeps the $HOME path above.
Workflow-Level Config ([ai] section in .oxoflow)#
[ai]
enabled = true
max_retries = 5
auto_fix = "ask" # recovery write mode: "ask" (default) | "always" | "never"
model = "deepseek-v4-flash"
team_profile = "compact" # "compact" | "full"
auto_fix controls what the recovery path may do with an AI-proposed workflow
patch. The mode gates on top of the model's own safety verdict and TOML
validation — it never bypasses either:
ask(default) — prompt y/N before writing on an interactive terminal; non-interactive sessions (CI, scripts) are denied with an explanation, so a headless run can never rewrite the workflow silentlyalways— apply safe fixes automatically (a patch flagged unsafe by the safety assessment is only displayed, never written)never— only report, never modify
Workflow-level provider/model selection is still not guaranteed to reconfigure the CLI runtime — treat that setting as advisory until the remaining audit gates close.
Generation team profiles#
template --ai runs one generation agent with the engine-gate correction
loop (the compact profile, default). The full profile adds three
Scientist Team roles around it:
| Role | Stage | Cost | What it does |
|---|---|---|---|
| Task contract | before generation | one small low-temperature call | standardizes an under-specified intent into an explicit contract (goal, inputs, outputs, decisions) |
| Curator | before generation | zero — deterministic retrieval | assembles Bioconda tool candidates, domain procedures, and pipeline-graph transitions from the embedded knowledge bases, so generation spends no paid rounds on knowledge lookups |
| Independent review | after generation | one small low-temperature call | a fresh evaluator instance judges the artifact against the contract; a request_changes verdict triggers exactly one regeneration pass with the findings |
Enable it per call with template --ai --ai-team-profile full, or per
project with [ai] team_profile = "full". The review pass is engineered to
be unable to regress the outcome (a regeneration replaces the draft only if
it also validates) and approves by default — on the measured ablation it
triggers on ~7% of runs. Full stays slightly below compact on aggregate
gate pass while rescuing scattered hard-tier cells; compact remains the
default and the full measurement record lives in eval/frontier/ in the
repository.
Environment Variables#
| Variable | Description | Default |
|---|---|---|
OXO_FLOW_AI_PROVIDER |
Provider: deepseek, claude, openai, ollama, or disabled. An explicit disabled is pinned: it outranks saved config and, in the web server, refuses the runtime-only AI config endpoint (409 AI_DISABLED_BY_ENV), saves persisted settings without applying them (applied_to_runtime: false), and answers the connectivity test with disabled without dialing out |
unset: auto-detect from credentials; disabled only when none resolve |
OXO_FLOW_AI_API_KEY |
Generic API key (fallback for all providers) | — |
OXO_FLOW_AI_API_URL |
Custom API endpoint URL | (provider default) |
OXO_FLOW_AI_MODEL |
Model name override | (provider default) |
OXO_FLOW_AI_CONFIG |
Explicit AI config file path, used for BOTH reads and writes. When set it is authoritative: the legacy ~/.config/oxo-flow/ai_config.json migration fallback is skipped, so a redirected process can never read or rewrite the $HOME-scoped file. An empty value is ignored; a relative path anchors to the process cwd, and parent directories are created on save. This is the hermetic knob for tests and CI (a web integration test once overwrote the operator's real config) |
$HOME/.oxo-flow/ai_config.json |
OXO_FLOW_AI_SESSION_DIR |
Directory for archived AI sessions (CLI AI commands and web chat/translate agent-loop runs). Empty = unset. Tests and CI set it to a scratch directory for hermetic runs, so a session archive never lands in the operator's real archive | <cwd>/.oxo-flow/ai_sessions when a project-local .oxo-flow exists, else $HOME/.oxo-flow/ai_sessions |
OXO_FLOW_AI_MAX_TOKENS |
Output-token ceiling for the Anthropic Messages backend. Calibrated for thinking-style backends whose reasoning blocks count against max_tokens (e.g. DeepSeek or GLM behind an Anthropic-compatible endpoint) — the old 4096 default truncated before any text was produced |
16384 |
OXO_FLOW_AI_CONTEXT_TOKENS |
Declared context window for Anthropic-compatible third-party proxies fronting a smaller model (e.g. 131072). The Claude backend clamps max_tokens per request: estimated input size (safety-factored) is subtracted from the window before the output budget is sent, floored at 1024. Unset = no clamping (real Anthropic models size the window server-side) |
unset |
OXO_FLOW_AI_TIMEOUT_SECS |
Per-request timeout for AI provider calls. A measured GLM thinking round took 145 s — the old 120 s default killed it mid-round. Raise together with OXO_FLOW_AI_MAX_TOKENS on slower endpoints. Also caps the TOTAL budget of the non-streaming web AI JSON routes (/api/chat/send/json, /api/ai/translate), which answer 504 AI_TIMEOUT when it expires — the route budget sits one second under the provider timeout and timeout-class provider errors map to the same 504 |
300 |
DEEPSEEK_API_KEY |
DeepSeek (OpenAI-compatible) | — |
DEEPSEEK_BASE_URL |
Custom DeepSeek endpoint | https://api.deepseek.com/v1/chat/completions |
ANTHROPIC_AUTH_TOKEN |
Anthropic-compatible API key (the variable Anthropic SDKs and gateway deployments export) | — |
ANTHROPIC_API_KEY |
Alias for ANTHROPIC_AUTH_TOKEN |
— |
CLAUDE_API_KEY |
Alias for ANTHROPIC_AUTH_TOKEN |
— |
ANTHROPIC_MODEL |
Claude model override | claude-sonnet-4-20250514 |
ANTHROPIC_BASE_URL |
Custom Anthropic endpoint | https://api.anthropic.com/v1/messages |
OPENAI_API_KEY |
OpenAI-compatible API key | — |
OPENAI_MODEL |
OpenAI model override | gpt-4o |
OPENAI_BASE_URL |
Custom OpenAI-compatible endpoint | https://api.openai.com/v1/chat/completions |
OLLAMA_HOST |
Ollama server address (explicit opt-in — no key needed) | http://localhost:11434 |
OLLAMA_MODEL |
Ollama model override | llama3 |
Zero-config auto-detection: when OXO_FLOW_AI_PROVIDER is unset (or empty) and no saved config exists, oxo-flow looks for the standard provider credentials in this exact order — ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY / CLAUDE_API_KEY → claude, OPENAI_API_KEY → openai, DEEPSEEK_API_KEY → deepseek, OLLAMA_HOST → ollama. Gateway setups that only export ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL + ANTHROPIC_MODEL therefore work without any oxo-flow-specific configuration. An explicit OXO_FLOW_AI_PROVIDER (including disabled) always wins; a saved Settings config beats auto-detection; setting a provider without any credential resolves to disabled instead of firing doomed requests, and a whitespace-only credential value counts as absent.
How It Works#
The AI agent combines several embedded knowledge sources, all compiled into
the binary at build time. Exact current record counts are exposed by
oxo-flow ai and by knowledge_meta.json; do not hard-code a catalog count
in a manuscript or release claim.
- Tool reference data with resource guidance for common bioinformatics tools.
- Bioconda tool records with versions and descriptions, queried on demand
through
lookup_tool. - bioSkills records with domain procedures, commands, and caveats,
matched by assay type or queried through
lookup_skill. - Pipeline graph transitions queried through
lookup_pipelinefor multi-step topology design. - Skill protocol documents fetched one at a time through
lookup_doc.
Token efficiency: embedded data is never added to the LLM context wholesale. Only on-demand tool queries (~1 KB per result) and domain-matched skill summaries (≤3 per domain) are injected — the rest stays in the binary until needed. The one deliberate exception is lookup_doc, whose full-protocol response is larger by design (roughly 2-5K tokens per fetched doc) and is still strictly on demand — one skill at a time.
The agent:
- Analyzes your intent (assay type, tools mentioned)
- Matches relevant bioSkills domains and injects curated expertise
- Selects tools from the reference table, verifying current versions via the Bioconda database
- Designs a DAG with proper dependencies (optionally consulting the pipeline graph for topology)
- Sets resource allocations based on tool requirements
- Generates valid
.oxoflowTOML - Validates against the engine schema; on failure the errors feed back
into the correction loop (bounded by
--ai-max-retries), so wrong-dialect output is repaired instead of written with a warning (one shared generation persona across CLI and web)
Custom Skills#
User-defined .skill.toml files (discovered from ~/.oxo-flow/skills and
<project>/.oxo-flow/skills) can be activated per workflow via
[ai] skills = [...] — their prompt_additions are appended to the system
prompt. See Custom Skills.
Session Logs#
Agents operating oxo-flow directly should also follow Agent Safety & Workspace Discipline: inputs are read-only, mutations are snapshotted and journaled, and all probing stays in one scratch tree inside the project.
Every AI interaction is logged to .oxo-flow/ai_sessions/ for audit and debugging:
{
"id": "20260809-230000-template-a1b2c3d4",
"command": "template",
"user_intent": "RNA-seq with STAR and DESeq2",
"provider": "deepseek",
"model": "deepseek-v4-pro",
"total_usage": {
"prompt_tokens": 1234,
"completion_tokens": 432,
"cache_read_tokens": 800,
"cache_creation_tokens": 200
},
"outcome": "success",
"confidence": 0.91
}
Archive guarantees#
- Failures are archived too. A run that aborts (provider error, round cap,
cancellation, client disconnect) persists
outcome: "Failed"with anerrorreason and the accumulated transcript/usage — the record you need for a post-mortem instead of an empty directory. Successful runs archiveoutcome: "Success". - Writes are crash-safe. Each session is serialized to a temp sibling in
the same directory and atomically renamed into place, so a concurrent
reader (or
oxo-flow aistatus scan) always sees a complete JSON document, never a partial write. - Fresh archives are never pruned. Retention keeps the newest 200 sessions per directory, but files younger than ten minutes are exempt: a run archived seconds ago — or the session an operator is inspecting — is never rotated out by concurrent writers.
- Test processes do not touch the operator's archive. Unit tests skip
session writes entirely; integration tests point
OXO_FLOW_AI_SESSION_DIRat a scratch directory. Set that variable to relocate archives on shared HPC homes or read-only project trees:
- The
scriptedtest backend cannot be installed in production. Its constructors are compiled out unless the crate is built for tests (cfg(test)) or with thetest-scriptedCargo feature (dev-dependencies only), so a real server can never run a stub provider — theRate limited by scriptedarchive entries from the browser test came from unit tests writing into the real archive, and that path is now closed.
prompt_tokens is the full prompt bill: on caching-enabled
Anthropic-compatible endpoints it includes cache_read_tokens (served from
the provider's prompt cache) and cache_creation_tokens (written to it);
DeepSeek-native and OpenAI-compatible endpoints report the same split under
their own shapes (prompt_cache_hit_tokens and
prompt_tokens_details.cached_tokens respectively, folded into
cache_read_tokens — DeepSeek has no cache-write counter, so
cache_creation_tokens stays 0 there). Token totals stay comparable across
providers while the cache split is preserved for cost estimation — cache
reads bill below the input rate and cache writes above it. Sessions written
before cache accounting carry only the two base counters and still load
unchanged.
Provider Comparison#
| Provider | Model Examples | Cost (per 1M tokens) | Quality | Setup |
|---|---|---|---|---|
| DeepSeek | DeepSeek v4-pro, DeepSeek v4-flash | ~$0.14–$0.28 in, ~$0.55–$1.10 out | High | API key (DEEPSEEK_API_KEY) |
| OpenAI-compatible | Groq LLaMA, Together, Azure | Varies | High | API key |
| Anthropic-compatible | Claude Sonnet 4 | Varies ($3–$15 in) | Best | API key |
| Local | Ollama (llama3, mistral, etc.) | Free | Moderate | Local install |
Recommendation: An OpenAI-compatible provider with high throughput (e.g., DeepSeek, Groq) offers the best cost-quality balance for bioinformatics workflows.
Complete Command Reference#
| Command | AI Flag | Auto-Detect | What It Does |
|---|---|---|---|
oxo-flow ai |
— | — | Quick status: provider, model, endpoint, connectivity, session count |
oxo-flow ai test |
— | — | Full self-test: connectivity + generation + analysis (tests the AI integration itself — not a workflow; for workflow testing use oxo-flow test) |
oxo-flow ai setup |
— | — | Interactive wizard: choose provider, enter key, save config |
oxo-flow ai explain WORKFLOW |
— | — | Three-layer workflow explanation (overview → steps → scientific review) |
oxo-flow ai explain WORKFLOW --step RULE |
— | — | Focus the explanation on one rule |
oxo-flow ai explain WORKFLOW --level beginner\|expert |
— | — | Explanation depth (default beginner) |
oxo-flow ai explain WORKFLOW --json |
— | — | Machine-readable skeleton + prose (stdout is pure JSON) |
oxo-flow template "X" --ai |
required | ❌ | Natural language → .oxoflow file |
oxo-flow template "X" --ai --from-url URL |
required | ❌ | Generate with web page as reference |
oxo-flow template "X" --ai --from-file PATH |
required | ❌ | Generate with local file as reference |
oxo-flow template "X" --ai -o PATH |
required | ❌ | Write output to specific path |
oxo-flow template "X" --ai --ai-max-retries N |
required | ❌ | Override max correction rounds |
oxo-flow env create "X" --ai |
required | ❌ | Natural language → pinned conda environment YAML (or pixi TOML with --backend pixi) |
oxo-flow dry-run WORKFLOW |
optional | ✅ | AI analysis if [ai] enabled=true |
oxo-flow dry-run WORKFLOW --ai |
force | — | Explicit AI override |
oxo-flow validate WORKFLOW |
optional | ✅ | AI semantic validation |
oxo-flow lint WORKFLOW |
optional | ✅ | AI best-practice linting |
oxo-flow debug WORKFLOW |
optional | ✅ | AI command explanation |
oxo-flow run WORKFLOW |
optional | ✅ | AI error recovery on failure |
oxo-flow run WORKFLOW --ai-recover |
force | — | Explicit recovery override |
oxo-flow run WORKFLOW --ai-max-retries N |
optional | — | Max AI recovery attempts when a call fails (default 1) |
oxo-flow resume CHECKPOINT --ai-recover |
required | — | Diagnose + fix on restart |
AI Command Explanation (debug --ai)#
Analyze expanded shell commands with AI:
The AI explains what each command does and flags potential issues like resource mismatches, missing flags, or incorrect parameter usage.
AI Linting (lint --ai)#
Add semantic best-practice checks beyond the deterministic linter:
AI Workflow Analysis (dry-run --ai)#
Validate workflow correctness, safety, and resource allocation before running:
The AI checks:
- Resource allocations vs. tool recommendations
- DAG structure (missing dependencies, invalid edges)
- Safety violations (destructive commands)
- Environment declarations
- Best practice adherence
Output includes severity ratings: [ERROR], [WARNING], [INFO].
AI Semantic Validation (validate --ai)#
Combine schema validation with AI-powered semantic analysis:
AI Error Recovery (run --ai-recover)#
When a workflow fails, the AI diagnoses the error and proposes a fix:
Recovery flow:
- Rule fails → capture error signature
- AI matches against known error patterns (OOM, segfault, missing files, etc.)
- AI proposes a root cause and bounded patch
- The resolved
auto_fixmode decides who may write:ask(the default) prompts y/N on an interactive terminal and is denied in non-interactive sessions,alwaysauto-applies safe fixes,neveronly reports. In every mode the generated TOML must still validate as a complete workflow before it is written; a patch flagged unsafe by the safety assessment is only displayed - A repair is not described as fixed until the complete workflow validates, the applied diff is reviewed, and a rerun verifies its outputs
See the CLI/AI blockers in
docs/superpowers/audits/industrial-scientific-audit-ledger.md.
Embedded Knowledge Freshness#
The knowledge sources are compiled into the binary at build time, so
they only change when the binary is rebuilt. Every data file is documented
by crates/oxo-flow-ai/src/knowledge/knowledge_meta.json — a plain JSON
document listing each source's record count, generation timestamp, and
whether it is auto-updated or manually curated:
{
"sources": {
"bioconda_tools": {
"count": 6688,
"url": "https://conda.anaconda.org/bioconda/channeldata.json",
"excluded": 6225,
"data_file": "bioconda_tools.jsonl",
"generated_at": "2026-11-16T10:44:43Z",
"auto": true
}
},
"generated_at": "2026-11-16T11:04:56Z"
}
count always equals the number of records in data_file — a drift-guard
test fails the build if the two ever diverge.
Seeing freshness#
oxo-flow ai prints a Knowledge freshness section: per-source record
count, generation date, staleness in days, and the auto/manual origin.
Auto-updated sources older than 60 days are flagged STALE. The
lookup_tool tool response likewise appends a freshness note (data date +
record count), so AI agents can weigh how current the embedded database is.
Update cadence and the Knowledge Refresh workflow#
A scheduled GitHub Action — the Knowledge Refresh workflow
(.github/workflows/refresh-knowledge.yml) — runs on the 1st and 16th of
each month at 03:00 UTC, and can be dispatched manually at any time
(Actions → Knowledge Refresh → Run workflow). It re-pulls each upstream
source, rewrites the JSONL data files only when content changed, and opens
a reviewed PR (chore(knowledge): automatic knowledge refresh <date>)
with per-source entry-count changes. A run that finds no data changes
completes green without a PR. A failing upstream source is tolerated — the
other sources still refresh and the failure is reported in the PR body.
Staleness gate#
The release pipeline rejects a dispatch release when any auto: true
source is older than 60 days (twice the 16-day cadence, tolerating one
missed run). The gate lives in ci.yml's version-sync job, so a stale
snapshot is blocked before any version bump or tag is created. Manually
curated sources (auto: false) are exempt — their freshness is the
maintainer's call. If a release is blocked, run the Knowledge Refresh
workflow, merge its PR, and re-dispatch the release.
Troubleshooting#
"AI provider not configured"#
# Check your configuration
oxo-flow ai # Shows provider status and connectivity
echo $OXO_FLOW_AI_PROVIDER # Should not be empty or "disabled"
# Set up any provider
export OXO_FLOW_AI_PROVIDER=<provider>
# then the matching credential:
# deepseek → DEEPSEEK_API_KEY, openai → OPENAI_API_KEY,
# claude → ANTHROPIC_AUTH_TOKEN, ollama → OLLAMA_HOST (no key)
"AI response did not contain valid TOML"#
The AI returned a response without valid .oxoflow TOML content. This is rare — try again with a more specific description.
Rate Limiting#
If you see rate limit errors, wait a few seconds and retry. For production use, consider upgrading your API plan or switching to a provider with higher rate limits.
Roadmap#
| Phase | Features | Status |
|---|---|---|
| Phase 1 | AI template generation | Implemented but unproven |
| Phase 2 | AI dry-run + validate analysis | Implemented but unproven |
| Phase 3 | AI error recovery (--ai-recover) |
Prototype / blocked by partial-file replacement and unverified rerun |
| Phase 4 | Scope-level AI config, AI plugin types (trait surface only — no loader, see oxo_flow_ai::plugin) |
Prototype / workflow-scoped policy is not fully enforced |
| Phase 5 | MCP/Skill ecosystem | Prototype / security trust-boundary work remains |
| Phase 6 | Workflow explanation (ai explain) |
Implemented but unproven |
| Phase 7 | Provider failure handling | Implemented but unproven; malformed tool arguments are fail-closed (AI-07) |
See the full design spec at docs/superpowers/specs/2026-08-09-ai-native-cli-design.md (repository root, not included in the published docs) for architecture details.