arc-kit

Provider, skill, market, and project configuration manager for coding agents.

中文

What It Solves

When teams use multiple coding agents, the same setup work tends to be repeated in every tool:

provider profiles are switched by editing each agent's native config;
useful skills are copied into several agent directories by hand;
skill updates require another manual copy pass;
shared skill repositories must be cloned, scanned, and installed manually;
project onboarding depends on local, undocumented state.

arc-kit puts those workflows behind one local CLI.

Core Capabilities

Provider Management

Switch provider profiles for supported agents:

arc provider list
arc provider use <name> --agent codex
arc provider test

Project-level provider requirements can be declared in arc.toml and applied with arc project apply. Provider profiles share display_name, description, base_url, and api_key. Each agent maps credentials to its native configuration and receives additional profile settings. Auth-only profiles retain their existing login behavior.

Skill Management

Manage skills once under ~/.arc-cli/skills/, then install them into supported agents:

arc skill list
arc skill info <name>
arc skill install <name> --agent claude --agent codex

Skill sources are resolved by priority:

Source	Path	Purpose
local	`~/.arc-cli/skills/<name>/`	user-defined skills
market	remote git repositories	team or community shared skills
built-in	embedded in the binary	optional skills packaged from `built-in/skill/`

The built-in source mechanism is retained, but the current source tree bundles no skills. Non-interactive skill install requires a skill name even when no skills are available. Installing a skill that cannot be found exits with code 1; JSON mode also reports the failure.

Market Sync

Markets are git repositories that contain skills:

arc market list
arc market add <git-url>
arc market update
arc market remove <git-url-or-id>

arc market update rebuilds the catalog and refreshes only arc-tracked global skill installs.

Project Configuration

Put arc.toml in a repository to declare project requirements:

version = 1

[provider]
name = "official"

[[markets]]
url = "https://github.com/team/skills.git"

[skills]
require = ["team-review"]

Then run:

arc project apply
arc status

arc.toml supports only version, provider, markets, and skills. MCP and subagent management have been removed.

Installation

brew tap duoyuli/arc-kit https://github.com/duoyuli/arc-kit.git
brew install arc-kit

Target platform: macOS.

Command Overview

arc                     # Show help
arc status              # Show project, agent, catalog, and action status
arc version             # Show version
arc completion <shell>  # Generate shell completions
arc provider list       # List providers
arc provider use        # Switch provider
arc provider test       # Test provider connectivity
arc market list         # List market sources
arc market add <url>    # Add a market source
arc market remove <git-url-or-id>
arc market update       # Update all market sources
arc skill list          # List skills
arc skill install       # Install a skill
arc skill uninstall     # Uninstall a skill
arc skill info          # Show skill details
arc project apply       # Reconcile tracked project skills with arc.toml
arc project clean       # Remove tracked project skills, keeping arc.toml
arc project edit        # Edit arc.toml skills interactively

Use --format json for automation where supported:

arc status --format json
arc project apply --format json --agent codex

User Guide

Quick Start

brew tap duoyuli/arc-kit https://github.com/duoyuli/arc-kit.git
brew install arc-kit

arc --help
arc version
arc status

Add and install a skill:

arc market add https://github.com/example/skills.git
arc market update
arc skill install my-skill --agent claude --agent codex

Apply project requirements:

arc project apply
arc status

Create an arc.toml before running arc project apply. Missing or invalid project configuration exits with 1 in both text and JSON modes.

Interaction Modes

Human-oriented commands use interactive UI only when stdin and stdout are TTYs and --format json is not present:

arc provider use
arc skill install
arc project apply

Automation should use explicit arguments and JSON output where supported:

arc status --format json
arc project apply --format json --agent codex

--format json takes precedence over TTY detection.

Status

arc status reports:

detected coding agents;
whether the current repository has arc.toml;
missing, partial, or unavailable project skills;
provider alignment with project requirements;
recommended next actions.

JSON output contains these top-level modules:

project
agents
catalog
actions
tracking: global/project record counts, unresolved legacy records, pending operations, and metadata errors

Providers

Providers control how Claude Code and Codex connect to model APIs.

arc provider list
arc provider use
arc provider use official --agent codex
arc provider test

Provider config files:

~/.arc-cli/providers/claude.toml
~/.arc-cli/providers/codex.toml

Each profile has four common fields. display_name and description are required strings. API key profiles also require non-empty string base_url and api_key together. Auth-only profiles may omit both credentials or set both to empty strings.

Common field	Purpose	Claude Code output	Codex output
`display_name`	Name shown when switching	Metadata only	Metadata only
`description`	Profile description	Metadata only	Metadata only
`base_url`	Model API endpoint	`env.ANTHROPIC_BASE_URL`	`model_providers.OpenAI.base_url`
`api_key`	API key	`env.ANTHROPIC_AUTH_TOKEN`	`model_providers.OpenAI.experimental_bearer_token`

Other fields are handled by each agent:

Claude Code converts them to JSON under ~/.claude/settings.json's env object, preserving strings, numbers, booleans, arrays, and nested tables. Switching removes the previous profile's managed fields and preserves unrelated environment variables and settings.
Codex copies them unchanged into [model_providers.OpenAI] in ~/.codex/config.toml when applying an API key profile. Switching replaces that table and preserves unrelated settings and other provider tables.
Codex fixes model_provider = "OpenAI" and the native name = "OpenAI". Defaults are wire_api = "responses", requires_openai_auth = false, and http_headers = { "x-openai-actor-authorization" = "local-image-extension" }. Explicit extra fields replace these defaults; http_headers follows the same generic passthrough as other extra fields. provider test uses the resulting static headers.
Codex always writes http_headers as an inline table inside [model_providers.OpenAI], including custom or empty headers. Reapplying a profile converts an existing [model_providers.OpenAI.http_headers] section to the inline form; subsequent switches keep that format.
The native Codex name remains OpenAI; common credentials take precedence over their native aliases in extra fields. Display metadata is never written into native configuration.
Codex auth handling is unchanged: leaving an auth-only profile saves its login snapshot; returning restores it and removes the native model_provider selection. API key profiles still write only OPENAI_API_KEY to auth.json.

Example Claude Code profile in ~/.arc-cli/providers/claude.toml:

[deepseek]
display_name = "DeepSeek"
description = "DeepSeek API usage-based billing"
base_url = "https://api.deepseek.com/anthropic"
api_key = "sk-xxx"
ANTHROPIC_MODEL = "deepseek-flash[1m]"
ANTHROPIC_DEFAULT_OPUS_MODEL = "deepseek-flash[1m]"
ANTHROPIC_DEFAULT_SONNET_MODEL = "deepseek-flash[1m]"
ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek-flash"
CLAUDE_CODE_SUBAGENT_MODEL = "deepseek-flash"
CLAUDE_CODE_EFFORT_LEVEL = "max"
CLAUDE_CODE_AUTO_COMPACT_WINDOW = 786432

arc provider use deepseek --agent claude writes:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-flash[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-flash[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-flash",
    "CLAUDE_CODE_EFFORT_LEVEL": "max",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": 786432
  }
}

Example Codex profile in ~/.arc-cli/providers/codex.toml:

[global-infra]
display_name = "Global Infra"
description = "Subscription access"
base_url = "https://global-infra.net"
api_key = "sk-xxx"

arc provider use global-infra --agent codex writes:

model_provider = "OpenAI"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://global-infra.net"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "sk-xxx"
http_headers = { "x-openai-actor-authorization" = "local-image-extension" }

The native Codex fields are described in the Codex configuration reference. Use common base_url and api_key fields in Claude profiles instead of native credential names, and add missing display metadata to older profiles. Re-run provider use after upgrading to apply the current format.

Command rules:

arc provider is equivalent to arc provider list.
Non-interactive provider use requires a provider name. If a name exists for multiple agents, pass --agent.
Invalid provider files, missing required fields, incorrect common field types, or incomplete credential pairs cause provider commands to exit with 1 before switching.
provider test exits with 1 if any tested provider fails.

Skills

List and inspect skills:

arc skill list
arc skill info my-skill
arc skill list --format json

Install and uninstall skills:

arc skill install my-skill --agent claude
arc skill install my-skill --agent claude --agent codex
arc skill uninstall my-skill --agent claude
arc skill uninstall my-skill --all

Global skill paths:

Agent	Path
Claude Code	`~/.claude/skills/<name>`
Codex	`~/.codex/skills/<name>`
Cursor CLI	`~/.cursor/skills-cursor/<name>`
OpenCode	`~/.config/opencode/skills/<name>`
Gemini CLI	`~/.gemini/skills/<name>`
Kimi CLI	`~/.kimi/skills/<name>`
OpenClaw	`~/.openclaw/skills/<name>`

Project-level skill paths:

Agent	Path
Claude Code	`./.claude/skills/<name>`
Codex	`./.codex/skills/<name>`
Cursor CLI	`./.cursor/skills/<name>`
OpenCode	`./.opencode/skills/<name>`
Gemini CLI	`./.gemini/skills/<name>`
Kimi CLI	`./.kimi/skills/<name>`

OpenClaw uses directory copy for global skills and does not support project-level skills.

Markets

Markets are git repositories that contain skills.

arc market list
arc market add https://github.com/team/skills.git
arc market update
arc market remove <git-url-or-id>

arc market update pulls markets, rebuilds the catalog, and refreshes arc-tracked global skill installs. It does not manage manually placed files in native agent directories.

Tracking metadata is stored at:

~/.arc-cli/state/skills/installs.json

The v2 ledger records each actual destination independently. Global installs and multiple projects may use the same skill without replacing each other's records:

{
  "schema_version": 2,
  "installs": [
    {
      "scope": "project",
      "project_root": "/Users/alice/work/project-a",
      "agent": "codex",
      "skill": "team-review",
      "target_path": "/Users/alice/work/project-a/.codex/skills/team-review",
      "source_path": "/Users/alice/.arc-cli/skills/team-review",
      "strategy": "symlink",
      "source_fingerprint": "sha256:6cd3e861cdd33b9b276fd2a03fe253ad5674664d2a2911cb7944625fbff3b4f3",
      "target_fingerprint": null
    }
  ],
  "unresolved_legacy": []
}

target_path identifies the installed entry, not the source behind its symlink. Copy records also retain the installed copy's target_fingerprint. The shared install service commits each target separately under a process lock, with a journal and same-filesystem staging for recovery. A failed removal never discards its tracking record; a committed replacement is never rolled back merely because backup cleanup failed.

Old global arrays are read without mutation. A write operation backs them up as installs.v1.*.json and migrates uniquely verified destinations without requiring agent detection. Unverified originals remain in unresolved_legacy. Read-only commands report corrupt metadata; write operations can quarantine it as installs.corrupt.*.json. Existing targets are never automatically claimed after metadata loss, and unknown newer ledger versions are never overwritten.

New fingerprints use SHA-256 with explicit field boundaries. Legacy copies with an older fingerprint also need to match the current source before migration; if the source has changed or is unavailable, the original record and copy remain unresolved. A missing or corrupt ledger alongside pending operations requires manual review: targets and journals are preserved, and committed installations are never guessed to be uncommitted and rolled back.

Project Configuration

Project configuration lets a repository declare its provider, skill, and market requirements.

Common commands:

arc project apply
arc project apply --agent codex
arc project apply --all-agents
arc project edit
arc project apply --dry-run --agent codex --format json
arc project apply --adopt-existing --agent codex
arc project clean --agent codex
arc project clean --project-root /path/to/project --dry-run --format json

arc project apply:

connects markets declared in arc.toml;
switches to the required provider;
reconciles all required and tracked project skills for selected agents;
installs missing targets, refreshes changed sources, and removes unchanged arc-owned targets no longer required, including when the requirement list is empty.

An existing untracked required target is reported as unmanaged. Use --adopt-existing to explicitly take ownership of targets that match the resolved source. Unrelated manual skills, replaced links, and modified copies are preserved. Unavailable required sources block new target changes rather than being treated as removed requirements. A preflight issue blocks the whole new skill plan; runtime failures stop subsequent actions while keeping completed targets recorded.

--agent and --all-agents are mutually exclusive. Explicit agents constrain both installation and cleanup. Without a flag, previously tracked projects reuse agents from their records and pending operations. --all-agents combines that set with detected project-capable agents. Inspection, repair, adoption, refresh, and removal of recorded targets do not require a running/detected agent executable; creating a new unrecorded destination does.

project clean removes owned project installations but leaves requirements intact, so apply can recreate them. Missing or inaccessible project roots retain their records. A moved project is a new scope: its existing targets require explicit adoption, and historical records remain available for inspection. Global skill commands and market update do not rewrite project target entries or remove project records. Updating a shared source can still change content reached through existing project symlinks.

--dry-run reads local state without writing targets, logs, caches, lock files, migrations, or recovery data. Missing local source data, active writers, and pending recovery report unresolved/errors with exit 1; a valid plan exits 0, even when changes are planned. Normal scoped commands recover their pending operations before planning new actions. JSON and human output report the same per-target actions, paths, and conflicts. arc status is read-only and exposes this information under project.installations; global skill JSON identifies scope: "global" and exposes tracked global destinations.

Minimal arc.toml:

version = 1

[skills]
require = ["architecture-review"]

Fuller example:

version = 1

[provider]
name = "official"

[[markets]]
url = "https://github.com/team/skills.git"

[skills]
require = ["team-review"]

Rules:

arc.toml is the project configuration entry point.
arc project apply is the operation that changes local state.
arc project edit edits skill requirements interactively.
--agent and --all-agents choose project-level skill install targets.
arc.toml must not contain secrets.
[mcps] and [subagents] have been removed and are rejected as unknown fields.

Shell Completions

arc completion zsh
arc completion bash
arc completion fish
arc completion powershell
arc completion elvish

Generated files are written under:

~/.arc-cli/completions/

Re-run completion generation after upgrading arc-kit.

Recommended Workflows

Personal setup:

arc status
arc provider use
arc skill list
arc skill install <name>

Team onboarding:

arc project apply
arc status

Automation:

arc status --format json
arc project apply --format json --agent codex

Interaction and Automation Design

This section defines command semantics for humans, scripts, and coding agents.

Runtime Modes

arc-kit has two runtime modes:

Mode	Condition
Interactive	stdin and stdout are TTYs, and `--format json` is not specified
Non-interactive	no TTY, or `--format json` is specified

--format json takes precedence over TTY detection. A command run in a terminal with --format json must take the automation path and must not launch TUI or dialoguer flows.

JSON and Exit Codes

JSON output uses a top-level schema_version. Current schema version: "6". The install ledger uses its own independent numeric schema version 2.

arc status --format json contains:

project
agents
catalog
actions
tracking

Exit code conventions:

Scenario	Exit Code
success	0
configuration parse failure	1
`status` reports missing, partial, or unavailable skills	0
non-interactive missing required parameters	1
`arc provider test` has failures	1
JSON serialization failure	1

Some commands retain structured non-mutating failures with exit 0 and ok == false, such as arc project edit --format json. Project apply/clean and scoped installation operations exit 1 on unresolved requirements, ownership conflicts, unavailable state, or execution failure. Automation should inspect both the exit code and JSON result.

JSON Coverage

Read commands must support --format json unless explicitly registered as exceptions.

Required JSON read commands:

arc status
arc market list
arc skill list
arc skill info <name>
arc provider list
arc provider test
arc project edit structured failure result

Registered exceptions:

arc version
bare arc with no subcommand
arc completion

JSON output must not contain ANSI escape sequences.

Write Commands

If an interactive command provides a wizard, multi-select, confirmation, or editor, the non-interactive path must be explicit and must not read stdin.

Current one-shot paths:

Command	Non-interactive path
`skill install` / `skill uninstall`	explicit name plus target agent or `--all` where applicable
`provider use`	explicit provider name, plus `--agent` when ambiguous
`market add` / `market remove` / `market update`	fully parameterized by command arguments
`project apply`	Explicit targets for a first install; later calls reuse recorded agents, including cleanup-only calls; `--dry-run` previews and `--adopt-existing` explicitly adopts matching required targets
`project clean`	Current project, or `--project-root <path>` when the manifest is absent; optional agent filter and `--dry-run`
`project edit`	interactive-only editor; JSON path returns a structured failure without opening an editor

Project Configuration Design

arc.toml supports:

version
[provider]
[[markets]]
[skills]

[mcps] and [subagents] have been removed and are rejected as unknown fields.

arc project apply requires a valid arc.toml; a missing or invalid file exits 1 in text and JSON modes. project clean --project-root <path> can clean an explicitly selected existing project directory after its manifest has been removed.

UI Boundaries

Business logic belongs in arc-core.
CLI command definitions and user output belong in arc-cli.
TUI and dialoguer interactions belong only in arc-tui.
arc-core must not print to stdout or depend on UI libraries.

List-style TUIs must clip each rendered line to the current terminal width. Do not rely on terminal auto-wrapping.

Resource Family Baseline

The only complete resource family today is skill:

Verb	Interactive behavior	Non-interactive behavior
`list`	TTY browser with drill-down to details	pipeable text and stable JSON collection
`info`	detail view from list or direct lookup	explicit single-item lookup and stable JSON detail
`install`	omitting name launches a wizard	explicit name and target agent
`uninstall`	omitting name selects from installed items	explicit name and target agent or `--all`

When adding another resource family, evaluate the full list / info / install / uninstall set for both human and agent support.

Anti-Patterns

judging only by TTY while ignoring --format json;
mixing ANSI into JSON;
calling dialoguer::Input::interact() outside interactive mode;
placing filesystem or domain behavior in arc-cli when it belongs in arc-core;
adding a read command without JSON output.

Development Guide

Environment

Rust stable toolchain (Rust 1.89 or newer)
macOS target platform

git clone https://github.com/duoyuli/arc-kit.git
cd arc-kit
cargo check
cargo test

Required Checks

Before submitting code:

cargo fmt --all
cargo check
cargo clippy --all-targets -- -D warnings
cargo test

If CLI entry points, output formats, or interaction semantics changed, also run:

cargo run -p arc-cli -- --help
cargo run -p arc-cli -- status
cargo run -p arc-cli -- status --format json

Before version bumps, v* tags, or formal releases:

cargo fmt --all --check
cargo check
cargo clippy --all-targets -- -D warnings
cargo test

The black-box CLI contract checks (exit codes, stderr text, JSON failure shapes) live in arc-cli/tests/ and run as part of cargo test against an isolated ARC_KIT_USER_HOME.

Repository Structure

.
├── arc-cli/          # CLI, clap command table, user output, JSON structs
├── arc-core/         # domain logic, install engine, provider, market, skill, detect, paths, io
├── arc-tui/          # interactive UI; only this crate depends on dialoguer
├── built-in/         # market index and optional skill resources; no skills currently bundled
└── Cargo.toml

Module Ownership

Built-in skill tests use dedicated fixtures in arc-core/tests/fixtures/builtin_skills/; those fixtures are not embedded in the released binary.

arc-core: business logic, state, filesystem operations, provider application, market sync, skill registry, install engine, detection, and project resolution.
arc-cli: command definitions, command dispatch, user output, and JSON response shapes.
arc-tui: interactive terminal UI, selectors, fuzzy browsing, wizard flows, and themes.

Do not put business logic in arc-cli. Do not put dialoguer interaction in arc-core or arc-cli.

Documentation Requirements

Behavioral code changes must update the relevant README sections:

product-facing capability changes;
user workflows;
CLI semantics, JSON, or interaction changes;
build, test, release, or module-ownership changes;
matching README.zh-CN.md Chinese mirror content.

Code comments follow AGENTS.md and are written in Chinese; CLI prompts are English. Product usage and development guidance are maintained in README.md and README.zh-CN.md. Cross-module engineering documentation is managed through project-doc, with docs/index.md as its entry point once the library is established. The engineering library has not been created yet; establishing it must also update both READMEs with its scope and entry link.

Contribution Rules

Keep each change focused.
Include tests for behavior changes.
Avoid unrelated refactors.
Do not introduce unused dependencies.
Use arc-core::io atomic write helpers for persistent writes.
Keep terminal layout and interactive-mode checks near the CLI/TUI boundary.

Release Rules

Confirm the main push succeeds before pushing a release tag.
Push tags separately.
Do not run git push origin main --tags.

Roadmap Notes

P0: provider, market, and skill behavior must remain stable; changes need tests.
P1: strengthen market/provider black-box and edge-case tests.
P2: continue documenting configuration and provider schema behavior.

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex/skills/project-doc		.codex/skills/project-doc
.github/workflows		.github/workflows
Formula		Formula
arc-cli		arc-cli
arc-core		arc-core
arc-tui		arc-tui
built-in		built-in
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING.zh-CN.md		CONTRIBUTING.zh-CN.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Latest commit

History

Folders and files

Repository files navigation

arc-kit

What It Solves

Core Capabilities

Provider Management

Skill Management

Market Sync

Project Configuration

Installation

Command Overview

User Guide

Quick Start

Interaction Modes

Status

Providers

Skills

Markets

Project Configuration

Shell Completions

Recommended Workflows

Interaction and Automation Design

Runtime Modes

JSON and Exit Codes

JSON Coverage

Write Commands

Project Configuration Design

UI Boundaries

Resource Family Baseline

Anti-Patterns

Development Guide

Environment

Required Checks

Repository Structure

Module Ownership

Documentation Requirements

Contribution Rules

Release Rules

Roadmap Notes

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages