Fleet management toolkit for AI agent repos — baseline validation, skill surface sync, and MCP profile management.
Deprecation notice: this standalone repository is now a public compatibility snapshot. Active private development moved to the canonical Codex harness repository at
codex-harness-staging/codexkit, where this module is nested undercodexkit/. The Go module path remainsgithub.com/hairglasses-studio/codexkitfor the compatibility window, so existing installs and imports can continue to work. See DEPRECATED.md.Public portfolio context: codexkit is the sanitized public slice of a larger private fleet-management workflow. It shows the reusable validation, sync, and projection patterns without publishing private repo inventory, workstation state, credentials, or tenant details.
See PUBLIC_BOUNDARY.md for the explicit include/exclude contract.
For a quick review path:
- Read DEPRECATED.md for the compatibility-window contract.
- Run the self-contained commands in docs/GETTING_STARTED.md.
- Review the data flow in docs/ARCHITECTURE.md.
- Use docs/PORTFOLIO_PROOF.md for the architecture diagram, walkthrough plan, tradeoffs, and interview prompts.
- Check PUBLIC_BOUNDARY.md before adding examples or generated artifacts.
- Use the workspace commands only against paths you control.
For dry-run sync demos, use the synthetic fixture in
examples/minimal-agent-repo instead of a
private workspace checkout.
- Baseline validation — checks ensuring every repo has canonical agent configs, valid project-local Codex config, valid skill surfaces, and protocol compliance
- Skill sync — mirrors
.agents/skills/to.claude/skills/andplugins/directories with drift detection - MCP sync — translates
.mcp.jsonserver entries to.codex/config.tomlblocks - Source contract check — validates workspace manifest, skill mirrors, MCP generated blocks, runtime inventory artifacts, and global MCP projections behind one command
- Surface index — maps baseline repos to canonical skills, MCP sources, generated mirrors, runtime projection, and consolidation decisions
- Configuration index — classifies repo, dotfiles, Claude, Codex, AGY, user-home, root-home, secret, and runtime state without emitting secret values
- Global MCP projection — generates Codex, Claude, and Gemini workspace-global MCP provider overlays from repo-local policies
- Fleet audit — runs baseline + skill + MCP checks across all repos in a workspace
- Performance audit — scans for Codex performance bottlenecks and regression budgets
- Discovery-first MCP tools — operations grouped by module with compact catalog search and on-demand schema lookup
go install github.com/hairglasses-studio/codexkit/cmd/codexkit@latest
go install github.com/hairglasses-studio/codexkit/cmd/codexkit-mcp@latestRepo-local wrapper scripts (scripts/run-codexkit-mcp.sh, scripts/skill-surface-sync.sh, scripts/codex-mcp-sync.sh) use a shared workspace Go environment when one is available. By default they reuse the shared ~/.cache/go-build and stage temp work under short repo roots at ~/.gt/<repo-id> instead of /tmp.
Use this path to validate the public toolkit without any private workspace, host-specific runner, or local operator state.
git clone https://github.com/hairglasses-studio/codexkit.git
cd codexkit
# Run the authoritative repository gate.
make ciExpected result:
. PASS (31 checks)
# Validate a single repo
codexkit baseline check /path/to/workspace/example-repo
# Audit the entire fleet
codexkit fleet audit /path/to/workspace
# Show skill drift without applying
codexkit skills diff /path/to/workspace/example-repo
# Sync MCP configs
codexkit mcp sync /path/to/workspace/example-repo
# Validate all repo-controlled workspace source contracts
codexkit workspace source-contract-check /path/to/workspace
# Write and later verify a diffable source-contract artifact
codexkit workspace source-contract-check /path/to/workspace \
--skill-validator=off \
--json-out /path/to/artifacts/workspace-source-contract-2026-05-10.json
codexkit workspace source-contract-check /path/to/workspace \
--skill-validator=off \
--json-path /path/to/artifacts/workspace-source-contract-2026-05-10.json
# Generate and verify the baseline repo surface index
codexkit workspace surface-index /path/to/workspace \
--skill-validator=off \
--json-out /path/to/artifacts/repo-surface-index-2026-05-10.json \
--markdown-out /path/to/artifacts/repo-surface-index-2026-05-10.md
codexkit workspace surface-index-check /path/to/workspace --skill-validator=off
# Generate and verify the workspace-global MCP provider projection
codexkit workspace global-mcp-projection /path/to/workspace \
--json-out /path/to/artifacts/workspace-global-mcp-projection-2026-05-10.json \
--markdown-out /path/to/artifacts/workspace-global-mcp-projection-2026-05-10.md
codexkit workspace global-mcp-projection-check /path/to/workspace
# Generate and verify the wider agent primitive index
codexkit workspace primitive-index /path/to/workspace \
--json-out /path/to/artifacts/workspace-agent-primitives-2026-05-10.json \
--markdown-out /path/to/artifacts/workspace-agent-primitives-2026-05-10.md
codexkit workspace primitive-index-check /path/to/workspace
# Inventory and check the strict Claude/Codex/AGY configuration plane
codexkit workspace config-index /path/to/workspace \
--user-home /path/to/user-home --root-home /path/to/root-home \
--json-out /path/to/artifacts/provider-config-index.json \
--markdown-out /path/to/artifacts/provider-config-index.md
codexkit workspace config-index-check /path/to/workspace \
--user-home /path/to/user-home --root-home /path/to/root-homecodexkit workspace source-contract-check validates the repo-controlled source contract from a full workspace checkout, not from this repository alone. On self-hosted CI, set HG_STUDIO_ROOT to that checkout; the path must contain codexkit/, workspace/manifest.json, and workspace/mcp-global-policy.json.
For stricter skill checks, install either the npm skills-ref CLI or the PyPI skills-ref package, which provides the agentskills CLI. codexkit skills check and codexkit workspace source-contract-check detect both validator entrypoints. Use --skill-validator=host to require an installed validator, --skill-validator=pinned to use pinned uvx/npx fallback commands, or --skill-validator=off to suppress external validation.
Use --json-out <path> to write the stable JSON source-contract artifact, and --json-path <path> to fail when a saved artifact no longer matches the live workspace report. The self-hosted baseline workflow uses --skill-validator=off for artifact comparison so optional host-installed validators do not change the saved report shape.
codexkit workspace surface-index generates repo-surface-index-*.json and .md, one row per baseline repo. It records canonical skill files, generated skill mirrors, MCP source/config/profile files, runtime projection aliases, source-contract status, and consolidation matrix state. The companion surface-index-check command fails when those generated artifacts drift.
codexkit workspace global-mcp-projection generates workspace-global-mcp-projection-*.json and .md. It records the runtime MCP source set plus Codex, Claude, and Gemini provider overlay entries derived from .mcp.json and .codex/mcp-profile-policy.json. The companion global-mcp-projection-check command fails when those generated artifacts drift.
Codex workspace-global overlays are intentionally opt-in: repo profiles must set global_codex: true or come from workspace-root foundational servers before they are written to user-scope Codex config. Claude and Gemini continue to project review/research profiles by default, so a zero Codex entry count can be a valid policy state when repo-local .codex/config.toml files are the Codex source of truth.
codexkit workspace primitive-index generates workspace-agent-primitives-*.json and .md. It records Claude hooks/settings, local overlays, provider agents, output styles, plugin manifests, nested MCP files, and instruction files that are outside the narrower skill/MCP source contract. Canonical and generated hook wiring failures fail primitive-index-check; local overlays remain audit-visible warnings.
codexkit workspace config-index inventories tracked and untracked provider configuration, canonical dotfiles, provider homes, and redacted runtime buckets. It never hashes secret/authentication files or copies values into output. Provider caches, vendored marketplaces, scratch workers, and archived provenance remain out of the active-policy lane. config-index-check rejects unowned active configuration, reports legacy Gemini/Copilot/Cline projections once per repository or provider-home surface, enforces operator-selected autonomy only at the user-global provider homes, and rejects unguarded provider-home deletion.
{
"mcpServers": {
"codexkit": {
"command": "codexkit-mcp",
"args": ["--workspace", "/path/to/workspace"]
}
}
}Codex and Responses API clients should configure Tool Search and
defer_loading on the client-side tool or MCP server definition. The MCP
server itself returns complete standard inputSchema objects from
tools/list; tool_catalog, tool_search, and tool_schema provide a compact
namespace-aware discovery path. Profile enabled_tools lists are bounded, and
approval policy remains a client/operator decision rather than an authorization
claim made by catalog metadata.
See Codex 0.167.0 compatibility for the current model routes, stable feature surface, and MCP protocol status.
| Tool | Description |
|---|---|
baseline_check |
Validate repo baseline against 14 canonical checks |
baseline_check_all |
Fleet-wide baseline validation |
skill_sync |
Sync skills from .agents/skills/ to mirrors |
skill_diff |
Show skill drift (dry-run) |
skill_list |
List skills from surface.yaml |
mcp_sync |
Sync MCP server config to Codex format |
mcp_diff |
Show MCP config drift (dry-run) |
mcp_list |
List registered MCP servers |
mcp_runtime_inventory |
Build a manifest-backed MCP runtime projection inventory |
workspace_global_mcp_projection |
Build the Codex, Claude, and Gemini workspace-global MCP provider projection |
fleet_audit |
Full audit across all workspace repos |
fleet_report |
Summary report of fleet health |
perf_audit |
Scan for performance bottlenecks |
perf_report |
Render performance audit as Markdown |
workspace_manifest_generate |
Generate workspace/manifest.json from live repos and docs metadata |
workspace_check |
Validate workspace manifest, repo directories, go.work, and consolidation matrix |
workspace_source_contract_check |
Validate workspace source contracts behind one read-only report |
workspace_surface_index |
Build a baseline repo index of agent surfaces and runtime projections |
workspace_primitive_index |
Build a workspace index of hooks, provider agents, plugin manifests, nested MCP files, and related agent primitives |
workspace_config_index |
Build a redacted provider configuration and dotfiles inventory |
workspace_config_check |
Check strict-provider ownership and autonomy-default policy |
codexkit/
├── baselineguard/ # 14-check repo validation engine
├── configindex/ # Redacted repo/dotfiles/provider-home configuration inventory
├── skillsync/ # Skill surface mirror management
├── mcpsync/ # MCP-to-Codex config translation
├── sourcecontract/ # Workspace-wide source-contract orchestration
├── surfaceindex/ # Baseline repo surface index artifacts
├── primitiveindex/ # Workspace-wide agent primitive inventory artifacts
├── fleetaudit/ # Fleet-wide audit orchestration
├── perfaudit/ # Performance bottleneck scanner
├── mcpserver/ # MCP server (JSON-RPC over stdio)
├── internal/toml/ # Zero-dependency TOML writer
├── cmd/codexkit/ # CLI entrypoint
└── cmd/codexkit-mcp/ # MCP server entrypoint
All packages implement the ToolModule interface for uniform registration and aggregation.
CI runs on GitHub Actions through the shared hairglasses-studio workflow
(required check ci / gate); make ci runs the same gate locally.
make ci # JSON/TOML, format, tidy, vet, build, race tests, public boundary, baseline
make baseline # repo baseline; permits only the recognized unstaged managed-launcher approval overlay
make baseline-strict # repo baseline with no local overlay exception
make test # race-enabled Go tests onlyThe equivalent component commands are:
GOWORK=off go build ./... # Build all
GOWORK=off go vet ./... # Lint
GOWORK=off go test -count=1 -race ./... # Test
GOWORK=off go run ./cmd/codexkit baseline check .MIT