AgentSys: an orchestration runtime for Claude Code, Codex, OpenCode, Cursor and Kiro

The part of agentic coding that AgentSys takes over

The README opens with a blunt framing: AI models can write code, and that is no longer the hard part. What remains is task selection, branch management, code review, artifact cleanup, CI, PR comments and deployment. AgentSys positions itself as the runtime that orchestrates agents across those steps.

The audience is narrow and specific. This is not a library you import into an application. It is a marketplace and installer that sits on top of an existing coding agent. The README lists five supported hosts: Claude Code, Codex CLI, OpenCode, Cursor and Kiro. If you do not already use one of those, AgentSys has nothing to attach to.

The unit of distribution is the plugin. Each of the 24 plugins lives in its own standalone repository under the agent-sh organisation, and the agentsys repository itself is the marketplace that ties them together. That split matters for how you evaluate the project: reading this repository tells you how installation, validation and orchestration work, not what any individual plugin does.

Gated phases, single-responsibility agents and state that survives a session

The architectural claim is that agents are small and pipelines are strict. Each agent has one responsibility, a model assignment, and defined inputs and outputs. Pipelines enforce phase gates so an agent cannot skip ahead. State persists across sessions, which is the mechanism behind the claim that work survives interruptions.

The more interesting design decision is the split between deterministic and probabilistic work. The README states the principle as code does code work and AI does AI work. Detection uses regex, AST analysis and static analysis, which are fast and consume no tokens. Judgment is reserved for LLM calls: synthesis, planning, review. The stated result is 77 percent fewer tokens for the /drift-detect plugin compared with multi-agent approaches.

Findings carry a certainty grade. HIGH means definitely a problem and is described as safe to auto-fix; MEDIUM means probably a problem and needs context; LOW means it might be a problem and needs human judgment. That grading is the practical safety valve. A pipeline that auto-fixes only HIGH findings can run unattended; anything that treats all findings as equal cannot.

The README also reports benchmarks run in March 2026 on /can-i-help and /onboard against the glide-mq repository, measured with claude -p --output-format json. In one comparison, Sonnet with AgentSys cost $0.66 and produced 6,084 output tokens, against $1.10 and 2,841 tokens for Opus without it. Treat those numbers as the project's own measurements on one repository, not as a general cost model.

Installing AgentSys and running a first pipeline

The package is published on npm as agentsys and exposes two binaries: agentsys and agentsys-dev. The README gives two installation routes, the marketplace or the npm installer, and states that plugins are fetched automatically from their repositories.

The first step is a global install so the CLI is on your path.

npm install -g agentsys

After that, run the installer. The 6.0.2 release notes say the installer now reports failures and exits non-zero when Claude Code rejects a plugin, so check the exit code rather than the printed message.

agentsys install

For hosts other than Claude Code, the release notes point at an explicit flag rather than a shell script. The two adapter install.sh scripts were deleted in 6.0.2 precisely because they could remove a working install and still report success.

agentsys --tool codex
agentsys --tool opencode

The repository ships a development CLI with validation targets, which is useful if you want to confirm the install is coherent before trusting a pipeline. These are the npm script names from package.json.

npm run validate
npm run validate:plugins
npm run validate:cross-platform

One caveat on the first run: the README does not document a rollback command for a plugin that installs but misbehaves. Removing a plugin means going through the host tool's own plugin management, which the README does not describe.

Where AgentSys is the wrong tool

The clearest limitation is host coupling. AgentSys does not run agents itself. It orchestrates plugins inside Claude Code, Codex CLI, OpenCode, Cursor or Kiro, so a change in any host's plugin interface is a change AgentSys has to absorb. The 6.0.2 release notes are a good illustration: resolving the Claude Code executable with where.exe instead of an assumed claude.cmd, and launching .cmd shims through cmd.exe at every spawn site. That is maintenance work created entirely by depending on another CLI's launch behaviour on Windows.

The installer also spawns external processes. The deleted adapter scripts existed because a shell script could delete a working install and report success, which means the installer is doing real filesystem work inside your agent's plugin directory. If you are not comfortable with a global npm package writing into your editor's configuration, this is the wrong tool.

Second, the plugin split cuts both ways. Because each plugin is a separate repository, the agentsys repository cannot tell you whether a given plugin is maintained. The README does not document a per-plugin support policy or a deprecation path, so evaluating a plugin means reading that plugin's repository separately.

Third, the benchmark section is one repository deep. The README states the certainty levels came from testing on over 1,000 repositories, but the cost tables cover /can-i-help and /onboard against glide-mq. If your codebase looks nothing like a JavaScript messaging library, the token savings are unverified for you.

How AgentSys differs from writing your own slash commands

The obvious alternative is the built-in customisation each host already offers: slash commands, skills and subagents defined in your own repository. That approach has no install step, no global package and no cross-host abstraction layer. You write a command file, commit it, and it works in the one tool your team uses.

The difference in approach is where the structure lives. With hand-written commands, the prompt and the pipeline are the same artefact, and phase gating is whatever the model decides to do next. AgentSys separates them: detection runs as deterministic code, judgment is an LLM call, and the pipeline enforces gates between phases. That is what makes certainty grading and auto-fix boundaries possible at all.

The cost of that separation is portability overhead. A hand-written Claude Code command does nothing in Codex CLI. AgentSys maintains adapters so the same plugin set targets five hosts, which is why the repository carries an adapters directory and a validate:cross-platform script. If your team has standardised on one host and will not move, the adapter layer is weight you are carrying for no benefit.

A second alternative is the linter ecosystem around agent configuration. The README points at agnix, a CLI and LSP linter from the same organisation with 423 rules covering Claude Code, Codex, OpenCode, Cursor, Kiro and several other tools. That is a different job: agnix validates configuration files, while AgentSys installs and runs the pipelines those files describe.

Maintenance cost, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-09-05, so this is a live codebase. The release history shows a 6.0.0 on 2026-05-29, 6.0.1 on 2026-07-22 and 6.0.2 on 2026-08-28. Two patch releases inside three months of a major version, with a Windows install fix and a CI change to run the suite on Windows as well as Linux, suggests the project is still absorbing platform differences rather than coasting.

The upgrade cost is not just npm. Because plugins are fetched from separate repositories, an agentsys upgrade can change which plugin versions get installed. The npm scripts reveal the intended safety net: preflight, preflight:all and preflight:release, plus gen-docs:check, expand-templates:check and gen-adapters:check, all of which are check modes that fail rather than write. If you fork or vendor this, those are the targets to run in CI.

On licensing, the repository is MIT. That permits commercial use and modification, and it requires the copyright notice and permission notice to be preserved. The README does not state a separate licence for the individual plugin repositories, so if you plan to redistribute a plugin rather than install it, check that plugin's own LICENSE file. Nothing here is legal advice; the practical point is that a permissive core licence does not automatically extend to every repository in the organisation.

Editorial conclusion

Adopt AgentSys if you already run Claude Code, Codex CLI, OpenCode, Cursor or Kiro and want task selection, review and cleanup turned into repeatable pipelines rather than ad hoc prompts. Skip it if you work in a single agent session without plugins, or if you cannot accept an installer that shells out to another CLI. Before installing, check that your tool is on the supported list and that your Node version satisfies the package engines field, then run agentsys install and confirm the exit code rather than trusting the printed output.

Frequently asked questions

Official sources

1. agent-sh/agentsys on GitHub
2. License: MIT
3. Project website
4. README
5. Releases