Skip to content

Ox-Agent quickstart

  1. Install the binary:

    Terminal window
    curl -fsSL \
    https://github.com/oxidean/Ox-Agent/releases/latest/download/install.sh \
    | bash

    It lands in ~/.local/bin — the only thing you install globally. Windows uses install.ps1; Install covers platforms, pinning, and update.

  2. From the repository you want to manage:

    Terminal window
    ox-agent init --integrate
    ox-agent doctor

    init materializes skills, workflows, and contracts into .ox-agent/ and refuses to overwrite an existing one. --integrate wires AGENTS.md and .agents/skills (plus .claude/skills) so your agent harness discovers the materialized skills. doctor validates the setup — it warns when no integration is detected, and fails when a git rule would keep .ox-agent/ out of source control.

  3. Open the repository in your agent and invoke a skill:

    > /brainstorm add a health-check endpoint

    Skills are how you talk to the system: /brainstorm for divergent options, /specify for the spec, /multi-stage-plan for the staged implementation plan. Using skills maps the bundled set to the lifecycle stages they serve.

  4. Answer when it asks. A skill that needs a decision files a durable request instead of blocking your chat:

    Terminal window
    ox-agent input list
    ox-agent input respond IN-0001 --by <you> --answer "..."
  5. Watch the trail:

    Terminal window
    ox-agent status # active work items
    ox-agent events WI-0001 # the journal so far

Every skill invocation runs the same contract. ox-agent run compiles a bounded packet — context, constraints, output — and dispatches it through the configured harness adapter; the agent writes output.json; run collect schema-validates it, journals the result, and applies next_action (advance_stage, retry, escalate, await_input, complete). When every skill mapped to a stage is collected, the work item auto-advances — discovery → brainstorming → specification → planning → implementation → verification → shipping → retrospective.

review and ship run the bundled pipeline DAGs, dispatching every ready step up to policy.budgets.max_parallel_agents; ox-agent run pending lists runs still awaiting output. The CLI reference covers the adapters (manual, spawn-cli, webhook) and the full command surface; Architecture explains why the packet is the boundary.

.ox-agent/
├── framework.yaml # binary + schema compatibility (required_version)
├── config.yaml # workflow profile, stage_skills
├── policy.yaml # autonomy + budgets (max_parallel_agents)
├── assets.lock # hash manifest of ox-owned assets
├── lifecycle/workflow.yaml # states + legal transition edges + gates
├── skills/ # materialized skill packages (owned by the binary)
├── workflows/ # stage-order profiles
├── pipelines/ # DAGs of skill steps (review, ship)
├── schemas/ # input/output contract schemas
├── integrations/ # harness adapters (manual.yaml default)
├── context/ # standards, decisions, specs/, project.yaml, index
├── work/{active,archived}/ # the spec trail: work items + artifacts
├── state/
│ ├── events.ndjson # append-only journal, the state spine
│ ├── snapshots/ # folded state checkpoints
│ └── input/ # durable human-input requests
├── discussions/ # append-only hash-chained threads
└── runtime/ # generated packets, runs, evals, and locks (gitignored)
Terminal window
ox-agent skills list # every materialized skill: enabled, drift, compat
ox-agent skills check # contract-validate every skill
ox-agent skills update # restore missing embedded files; --yes overwrites drift

Drop a directory with a skill.yaml, SKILL.md, and schemas/ into .ox-agent/skills/ and it becomes a project-local skill; skills update never touches it. Remote installs via ox-agent skills install <git-url> are pinned to a resolved commit SHA in remote-skills.lock.

The manual adapter works with anything that can read a file. To dispatch directly, add a spawn-cli integration (.ox-agent/integrations/myagent.yaml):

schema_version: 1
name: myagent
adapter: spawn-cli
command: "myagent run --packet {packet} --write-output {output}"
timeout_seconds: 600

{packet}, {output}, and {run_dir} expand to run-directory paths; the command runs with the project root as working directory. Remote execution needs those paths reachable: either a shared filesystem, or a command that copies the packet into a private remote directory and cleans it up — e.g. ssh buildbox 'install -d -m 700 ~/.ox-run' && scp "{packet}" buildbox:.ox-run/packet.json && ssh buildbox '/opt/run-skill ~/.ox-run/packet.json'; rc=$?; scp -q buildbox:.ox-run/output.json "{output}"; ssh buildbox 'rm -rf ~/.ox-run'; exit $rc — not world-readable /tmp, since packets can carry human-input answers — and copies output.json back to the local run dir before collect, keeping the remote run’s exit status. The CLI reference covers the full command surface.