Agent Arche

A selective Codex engineering harness: install only the skills a project needs, optionally add lean hooks and indexed memory, or opt into explicit multi-agent orchestration.

Install

npx agent-arche install

The interactive CLI first selects a setup profile, then an installation scope, project type, and project stage. Those answers determine which grouped skills are initially checked; the user can still select or deselect anything before installation.

| Setup profile | Purpose | |---|---| | General Engineering | The existing technology-agnostic engineering harness | | Commerce Stack | Shopify + Klaviyo + Django skills, integrations, and orchestration specialists |

| Scope | Installs | Runtime posture | |---|---|---| | Skills only | Selected .agents/skills/ and .codex/agent-arche.json | Lowest overhead | | Skills + hooks | Selected skills, config, safety hooks, context compiler | Lean established-project setup | | Skills + hooks + memory | Above plus indexed durable memory/ | Recommended | | Full orchestration | Above plus orchestrator and specialized Codex agents | Highest usage |

Usage warning: Full orchestration costs substantially more usage than a comparable single-agent run. Every subagent performs separate model and tool work. Choose it only when independent workstreams, noisy exploration, tests, or review benefit from delegation.

The installation metadata always lives at .codex/agent-arche.json, including Skills-only installs. Commerce Stack Skills-only does not install or configure MCP servers.

Non-interactive examples

npx agent-arche --profile=general --skills-only --select-skills=implement,git --yes
npx agent-arche --profile=commerce --skills-hooks --project-type=full-stack --project-stage=established --yes
npx agent-arche --profile=general --skills-hooks --project-type=backend --project-stage=established --yes
npx agent-arche --profile=general --skills-hooks --select-skills=implement,design,code-review --yes
npx agent-arche --profile=commerce --skills-memory --all-skills --yes
npx agent-arche --profile=general --orchestration --select-skills=implement,security-review --yes

The skill step opens with recommendations computed from the setup profile, installation scope, project type, and project stage. Users can deselect any recommendation or select additional skills before installation. --yes accepts the computed recommendations when no explicit skill selection is supplied.

The selector keeps a fixed-height, cursor-following viewport. Use ↑/↓ to move, ←/→ to collapse or expand groups, Space to toggle a skill or group, Enter to confirm, and Esc to cancel.

| Input | Recommendation effect | |---|---| | Every project | Core implementation, diagnosis, testing, review, security, Git, and handoff skills | | Commerce Stack | Adds Klaviyo operations and recommendation workflows, Django commerce integration, end-to-end debugging, and selected official Shopify skills | | Full-stack | Adds frontend design, SEO, and PostgreSQL workflows | | Backend | Adds PostgreSQL workflows; leaves frontend skills unchecked | | Frontend | Adds design and SEO workflows; leaves backend-specific skills unchecked | | General / other | Keeps only the applicable core set | | Greenfield | Adds project-startup | | Established | Leaves project-startup unchecked | | Full orchestration | Adds planning and architecture workflows used by delegated work |

These are checkbox defaults, not locked bundles. Use --profile, --project-type, and --project-stage for non-interactive selection, or --select-skills to override recommendations with an exact set.

Update the files managed by the recorded scope and skill selection with:

npx agent-arche update

Legacy metadata under .agents/ is still detected; the next update writes canonical metadata under .codex/.

How it works

flowchart LR
    A[User request] --> P{Setup profile}
    P --> B{Installed scope}
    B -->|Skills| C[Matching selected skill]
    B -->|Hooks| D[Lean SessionStart policy]
    B -->|Memory| E[Context compiler]
    B -->|Full orchestration| F[Orchestrator]
    D --> C
    E --> G[Top ranked context snippets]
    G --> C
    F --> H[Bounded specialized subagents]
    H --> I[Evidence summaries]
    I --> F
    C --> J[Scoped implementation and checks]
    F --> J

The harness follows progressive disclosure:

1. Codex sees only installed skill names and descriptions.
2. It loads a skill body only when its trigger matches.
3. The context compiler ranks project evidence deterministically.
4. The model receives at most a small task-specific context pack rather than a full memory map.
5. Full orchestration delegates only tasks that divide cleanly.

Selectable skills

| Group | Skills | |---|---| | Core engineering | implement, diagnosing-bugs, tdd, code-review, karpathy-guidelines | | Security and backend | security-review, postgres-patterns | | Frontend and growth | design, seo | | Planning and architecture | project-startup, to-spec, to-tickets, grill-with-docs, codebase-design, improve-codebase-architecture | | Delivery and communication | git, handoff, caveman | | Klaviyo and commerce operations (Commerce Stack) | klaviyo-operations, klaviyo-product-recommendations, klaviyo-customer-agent, commerce-integration-debugging, django-commerce-backend | | Shopify AI Toolkit, official (Commerce Stack) | shopify-admin, shopify-liquid, shopify-custom-data, shopify-use-shopify-cli, shopify-dev |

project-startup is optional. Install it only for a new or unconfigured project. Established projects can omit it entirely.

Full orchestration automatically installs the orchestrate routing skill in addition to the user selection.

Every Agent Arche-authored skill includes agents/openai.yaml for consistent desktop UI labels and explicit invocation prompts. The vendored official Shopify skills retain their upstream package structure. Codex routing still depends on the concise name and description in SKILL.md; optional UI metadata is not a replacement for those trigger fields.

The official Shopify skill scripts disclose usage telemetry to Shopify. Set OPT_OUT_INSTRUMENTATION=true to opt out. See Commerce Stack and NOTICE for sources and the vendored snapshot.

Commerce Stack MCPs

The three Commerce Stack scopes that include .codex/config.toml configure:

• Klaviyo's official remote MCP at https://mcp.klaviyo.com/mcp, read-only by default and requiring OAuth login;
• Shopify's official @shopify/dev-mcp for current developer docs, schemas, and validation;
• Context7 for current Django documentation lookup.

Django does not currently publish an official MCP server. Agent Arche does not install a community package that exposes a project's models, admin, or API automatically. That requires a separate project-specific security decision.

Lean hooks

The hook bundle deliberately contains only:

• SessionStart: a short instruction to use matching installed skills and the context compiler.
• PreToolUse: a narrow blocklist for catastrophic shell operations.

It does not force Caveman, preload Karpathy, read _MOC.md, write memory after every task, or run per-prompt/post-tool instrumentation.

Review and trust project hooks in Codex with /hooks.

Indexed memory

flowchart TD
    Q[Task and known paths] --> R[context.cjs query]
    M[Fixed-size manifest] --> R
    C[Durable cards and ADRs] --> R
    B[arche: breadcrumbs] --> R
    X[Sessions, reviews, archive, MOC] -. cold by default .-> R
    R --> K[Top 3-6 ranked snippets]
    K --> A[Agent context]

Use:

node .codex/context/context.cjs index --refresh
node .codex/context/context.cjs query --task "fix session expiry" --paths "src/auth/session.ts"
node .codex/context/context.cjs check
node .codex/context/context.cjs harvest

Memory is written only for durable novelty: decisions, cross-cutting constraints, reusable patterns, recurring gotchas, or an explicit unfinished handoff. _MOC.md stays fixed-size and exists for humans/Obsidian, not model retrieval.

See Memory design and Architecture.

Full orchestration

Full orchestration installs project-scoped agents under .codex/agents/:

• orchestrator
• code_explorer
• implementation_worker
• reviewer
• test_runner

Commerce Stack also installs:

• klaviyo_specialist
• shopify_specialist
• django_integration_specialist

The orchestrator starts with at most three concurrent subagents, favors parallel read-heavy work, prevents overlapping write ownership, and requires evidence summaries rather than raw logs. Simple tasks remain single-agent.

See Orchestration.

Codex files

| Path | Purpose | |---|---| | .agents/skills/ | Only selected skill packages | | .codex/agent-arche.json | Canonical installed profile, scope, and skill selection | | .codex/config.toml | Runtime settings for hook-enabled scopes | | .codex/hooks.json, .codex/hooks/ | Lean lifecycle hooks | | .codex/context/ | Deterministic context index/query compiler | | .codex/agents/ | Full-orchestration custom agents only | | memory/ | Indexed durable project knowledge |

Durable project instructions belong in applicable AGENTS.md files. .codex/instructions.md is not used as a parallel instruction system.

Validate

npm run check
npm run build:dist
npm pack --dry-run

Credits

Agent Arche adapts and combines ideas from several open-source projects. The installed workflows may differ materially from their upstream versions:

• mattpocock/skills — engineering workflow and deep-module skill foundations.
• vercel-labs/skills — reference for the redesigned interactive skill-selection CLI experience.
• DietrichGebert/ponytail — inspiration for sparse, machine-searchable source breadcrumbs and deterministic harvesting.
• cyxzdev/Uncodixfy, pbakaus/impeccable, and Leonxlnx/taste-skill — design workflow inspiration.
• JuliusBrussee/caveman — explicit compressed communication mode.
• Akindu23/my-agent-skills — Karpathy-style coding guardrails and PostgreSQL patterns.
• Clack and picocolors — CLI prompt and terminal-color libraries.
• Official OpenAI Codex documentation — custom-agent configuration and subagent usage boundaries.
• Shopify AI Toolkit — official vendored Shopify skills and Dev MCP configuration.

See upstream repositories and this package's dependency lockfile for their licenses. Agent Arche itself is MIT licensed.

The component-by-component attribution map is in NOTICE.md.