OpenSpace/agentpilot/docs/host-coding.md

Use AgentPilot in your coding agent

Use /agentpilot (or your host’s spelling below) to prepare and run an RSI experiment. The current agent fills in missing task/eval inputs, then starts the existing Arena or core runner when its adapter and evaluation are ready. If a prerequisite is missing, it explains what is needed; it does not replace AgentPilot with its own editing loop.

Install once

From the repository root:

python install.py --host codex

The installer creates a dedicated runtime in ~/.local/share/agentpilot/host-runtime, installs the core package, checks it, and adds the agentpilot skill. With uv installed it selects Python 3.12; otherwise run the installer with Python 3.11+ and working venv/pip support. Runtime installation may download Python or build dependencies. It does not change model settings or credentials, install project dependencies, or start a model or benchmark run. Its output gives the exact Python launcher and skill path.

Use --prefix /path/to/runtime to choose a different runtime, and --skill-dir /path/to/skills to choose a host's skill root. Re-run the same command from an updated checkout to update. An update checks skill-file conflicts before replacing the runtime, preserves unrelated files, and refuses to overwrite a skill changed outside this installer. It never commits or pushes.

If you prefer uv's tool installation:

uv tool install --python 3.12 ./agentpilot
agentpilot setup --host codex

Supported hosts

Use python install.py --host NAME. All hosts use the same skill; the installer selects the host's skill directory and invocation.

Host	NAME	Default skill directory	Invocation
Codex	codex	~/.agents/skills	$agentpilot or /skills; optional desktop plugin below.
Claude Code	claude-code	~/.claude/skills	/agentpilot
OpenCode	opencode	~/.config/opencode/skills	CLI: /agentpilot (verified with 1.19.5); V2 also supports @agentpilot.
Cursor	cursor	~/.cursor/skills	/agentpilot
GitHub Copilot CLI	copilot	~/.copilot/skills	/agentpilot
Meta Muse Code	muse	~/.agents/skills	/agentpilot
CodeBuddy Code	codebuddy	~/.codebuddy/skills	/agentpilot
Hermes Agent	hermes	~/.hermes/skills	/agentpilot
nanobot	nanobot	Its configured workspace/skills	$agentpilot
DeepSeek Harness	dsh	~/.agents/skills	/agentpilot with skill support enabled.
Grok Build	grok	~/.grok/skills	/agentpilot
WorkBuddy	workbuddy	ZIP export	Import the emitted ZIP through Skills, then select it.

OpenCode, Hermes and DSH respect XDG_CONFIG_HOME, HERMES_HOME and DSH_AGENTS_HOME, respectively. nanobot reads its default config, falling back to workspace environment settings; use --skill-dir for a separate instance. For another compatible host, use --host generic --skill-dir /its/documented/skills/path.

The host needs skill support, local file editing, and command execution. Having a CLI alone does not establish those capabilities. WorkBuddy ZIPs contain an absolute runtime launcher: export on the machine where the skill will run. WorkBuddy and CodeBuddy are distinct products; no WorkBuddy CLI or slash spelling is assumed. Grok Build is the local coding agent, not Grok Bot. Muse here means Meta Muse Code. Restart the host or open a new chat if a new skill is not visible.

The directory integrations follow AutoSwarm's host setup and the host documentation linked in the registry. Installing a skill lets the host prepare inputs and operate AgentPilot. The formal worker separately needs an adapter for task input, execution options and results; merely having a CLI is insufficient.

Optional Codex plugin and @ entry

The repository also contains a local Codex plugin. With a Codex CLI that supports plugins, install the runtime, skill and plugin together:

python install.py --host codex --plugin

--plugin registers this checkout as a local marketplace and installs its AgentPilot plugin in Codex. The equivalent plugin-only commands are:

codex plugin marketplace add .
codex plugin add agentpilot@agentpilot-local

Alternatively open the repository in Codex and install AgentPilot from the agentpilot-local source in Plugins. Start a new chat and select the installed plugin with @. Its onboarding skill locates or installs the core runtime and loads the same coding workflow. This is a local plugin with local execution; it has not been published to the public plugin directory. Plugin availability and @ selection depend on the client; setup --host codex alone installs a skill, not a plugin. See the official plugin guide.

Other components

python install.py --host claude-code --components agentpilot openspace rsi-arena

This adds /agentpilot, /openspace, and /rsi-arena in Claude Code (the names use $ in Codex CLI). The last two are guided entrypoints to their existing setup flows: OpenSpace still needs its runtime and MCP connection, and Arena still needs the selected benchmark's dependencies, tasks, and model setup. They are installed only when requested and are not included in ordinary coding runs. Colon namespaces belong to a host's plugin system, not these skill names.

Start in a project

$agentpilot Help me improve this project's performance and make it run faster.

A bare invocation also works. The agent reads the project, infers a useful goal where possible and prepares suitable checks. It runs an initial measurement when an evaluator is available. For a performance task, this includes a representative workload and correctness checks. It asks only for essential information it cannot infer. Preparation uses the host's ordinary tools and needs no separate session or JSON plan.

The agent assesses readiness from the actual configuration and evaluation results. With a compatible adapter, working evaluation, model/worker access and budget, it continues into proposer → worker → eval → policy feedback through the existing runner. The runner owns candidate changes, run records and recovery. Ordinary project tests still need an environment adapter to enter this loop.

Datasets and evaluation

Already configured: give the agent the runtime configuration or existing run directory. It follows the Arena integration, core environment, or Arena benchmark guide appropriate to that configuration. The formal UCB/Textual Policy Learning loop and its persisted state remain unchanged.

Missing task or eval: the current agent inspects the project, prepares the missing inputs and checks the actual evaluator. It can use the existing preparation interfaces without dispatching another worker. It then launches the configured runner if ready; otherwise it reports the missing prerequisite. Automatic formal integration of arbitrary projects is not yet supported. The built-in Arena setup targets Harbor/Terminus 2 on AIME or Terminal-Bench; other projects need an implemented environment adapter.

Custom eval: give the command and success criterion, for example: Use python evaluation/check.py; preserve output quality while reducing runtime. The agent verifies that it measures the goal and detects relevant failures. Formal runs also require the corresponding task source, worker and environment adapter. A passing test command or static configuration check alone is insufficient.

Model access: the Arena research runner can reuse a configured worker CLI's model/login for proposer and Memory policy calls when their API credentials are absent. Use --proposer-access worker --policy-access worker to select this explicitly. Task evaluation and UCB embeddings retain their provider requirements; custom core adapters own their own provider assembly. CLI calls retain budget allowances with external billing, so login reuse does not make the entire loop free. See worker access.

A/B/C datasets: use the selected formal environment's protocol. A provides development evidence, B supplies validation feedback, and C is held out until final evaluation. Do not use C to guide subsequent improvement. Discovering project tests does not automatically create these splits.

Inspect and resume

The installer returns an absolute launcher using its own Python. It accepts core commands such as validate-config, run and resume; use the environment where the selected adapter and provider dependencies are actually installed. Configuration validation alone does not prove that an evaluator runs.

An optional read-only helper suggests existing pytest, unittest, Node, Cargo and Go test commands:

agentpilot project inspect --cwd /path/to/project

It neither executes checks nor creates a session. The agent can also discover and run tests directly with the project's usual tools.

Continue preparation from the conversation and project artifacts. Resume experiments using their original runner and run identity. There is no separate host improvement loop. Re-running installation updates managed skills while protecting local edits.

The installed skill contains the routing rules; formal workflow details are loaded only when relevant. The agent chooses how to prepare incomplete inputs; the configured runner owns policy learning and evaluation. Commit restrictions still apply: a runner that creates candidate commits cannot be used under a blanket no-commit instruction.