agent-cargo

Frontend-focused cargo for AI coding agents. Materializes universal JS/HTML/CSS agent instructions, agents, skills, rules, and tool adapters (Codex) into downstream projects from layered presets, and keeps them in sync without ever overwriting local changes.

Status: pre-release (0.1.0 in development).

Presets

agent-cargo is a frontend tool: every built-in preset targets a frontend stack. Enable them in order (core always first):

| Preset | Scope | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | core | Any JS/HTML/CSS frontend project — universal operating principles, generic specialist agents, code review / documentation / git workflow skills. | | react-next | React and Next.js projects — performance, composition, a11y, security, TypeScript conventions. | | component-library | A concrete monorepo harness modeled on the component-library repo: React 19.2 + Next.js 16 (App Router), Turborepo/npm workspaces, Sanity CMS (GraphQL/GROQ codegen), apps/web + apps/docs-web, packages/{ui,sections-ui,widgets-ui,lib,hooks}, design tokens, Figma rules, Husky, and the repomix snapshot capability. Paths are concrete, not templated. |

Why agent-cargo

Other tools in this space generate agent configs from a single source. agent-cargo instead gives agent instructions a package-manager lifecycle (init → diff → sync → check):

• Committed, not gitignored. Managed files are committed to your repo by default, so agents see instructions in fresh clones, worktrees, and CI checkouts without running anything first.
• Conflicts, not overwrites. Locally edited managed files are detected via per-file checksums and surfaced as conflicts you resolve — never silently overwritten, no .bak litter.
• Pinned, not global. Installed as a dev dependency, so your team and CI run the same version of the instructions and upgrade deliberately, like any other dependency.
• Verified adapters only. An adapter ships only after the tool's discovery contract is verified against official docs, and it writes only surfaces the tool natively reads.

Quick start

npm install -D agent-cargo
npm exec -- agent-cargo init --package-manager npm

For a project with repo-specific rules and repository snapshots:

npm exec -- agent-cargo init \
  --preset core --preset react-next --preset component-library \
  --package-manager npm --install

Space-separated values are also accepted: --preset core react-next component-library.

Commands

| Command | Purpose | | -------------------- | --------------------------------------------------------- | | agent-cargo init | Initialize the cargo in the current project. | | agent-cargo sync | Apply managed-file updates from the installed version. | | agent-cargo diff | Preview what sync would change (read-only). | | agent-cargo check | Validate config, manifest, and managed files. | | agent-cargo add | Enable a capability (repomix) and install its dependency. | | agent-cargo update | Update a capability dependency to the tested version. |

Options and details (common options, init flags, what init creates): docs/commands.md.

Configuration

.agent-cargo.json in the project root; presets, tools, and packageManager are required. Full reference: docs/configuration.md. JSON Schema: schemas/agent-cargo-config.schema.json.

Repomix snapshots

The component-library preset enables the repomix capability by default. For an existing project, enable presets, install the dependency and generate the first snapshot:

# 1. Add presets to .agent-cargo.json, then materialize their files
agent-cargo sync

# 2. Install the repomix dependency and its npm scripts
agent-cargo add repomix --install --yes

# 3. Generate a snapshot
npm run repomix:generate

# 4. Attach the pre-push hook (snapshot freshness check)
agent-cargo sync --enable-repomix-pre-push

Details (workspace discovery, generation modes, hooks, drift check): docs/repomix.md.

Documentation

• docs/concepts.md — presets, managed files and ownership, conflict model, adapters
• docs/commands.md — CLI reference
• docs/configuration.md — configuration reference
• docs/repomix.md — Repomix capability

Development

npm install
npm run verify   # lint + format + type-check + tests
npm pack --dry-run --json

Vendored Vercel skills under presets/react-next/skills/ are refreshed from vercel-labs/agent-skills:

npm run skills:check    # detect drift against upstream (network)
npm run skills:update   # re-sync snapshots and update the pinned commit

Minimum runtime: Node.js >= 24 (ESM only).

Platform: macOS only. agent-cargo is developed and tested on macOS. Windows and Linux are not supported.

License

MIT. See LICENSE.