Ox-Agent quickstart
-
Install the binary:
Terminal window curl -fsSL \https://github.com/oxidean/Ox-Agent/releases/latest/download/install.sh \| bashIt lands in
~/.local/bin— the only thing you install globally. Windows usesinstall.ps1; Install covers platforms, pinning, andupdate. -
From the repository you want to manage:
Terminal window ox-agent init --integrateox-agent doctorinitmaterializes skills, workflows, and contracts into.ox-agent/and refuses to overwrite an existing one.--integratewiresAGENTS.mdand.agents/skills(plus.claude/skills) so your agent harness discovers the materialized skills.doctorvalidates the setup — it warns when no integration is detected, and fails when a git rule would keep.ox-agent/out of source control. -
Open the repository in your agent and invoke a skill:
> /brainstorm add a health-check endpointSkills are how you talk to the system:
/brainstormfor divergent options,/specifyfor the spec,/multi-stage-planfor the staged implementation plan. Using skills maps the bundled set to the lifecycle stages they serve. -
Answer when it asks. A skill that needs a decision files a durable request instead of blocking your chat:
Terminal window ox-agent input listox-agent input respond IN-0001 --by <you> --answer "..." -
Watch the trail:
Terminal window ox-agent status # active work itemsox-agent events WI-0001 # the journal so far
What your agent does under the hood
Section titled “What your agent does under the hood”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.
What lands in the repo
Section titled “What lands in the repo”.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)Maintaining the skill set
Section titled “Maintaining the skill set”ox-agent skills list # every materialized skill: enabled, drift, compatox-agent skills check # contract-validate every skillox-agent skills update # restore missing embedded files; --yes overwrites driftDrop 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.
Dispatching to an agent CLI
Section titled “Dispatching to an agent CLI”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: 1name: myagentadapter: spawn-clicommand: "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.