Skip to content
hairglasses-studioPublic

About

Deprecated public compatibility snapshot; active private Codex harness development lives in hairglasses-studio/codex-harness-staging/codexkit.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

219 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

codexkit

Go CI License: MIT MCP

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 under codexkit/. The Go module path remains github.com/hairglasses-studio/codexkit for 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.

Start Here

For a quick review path:

  1. Read DEPRECATED.md for the compatibility-window contract.
  2. Run the self-contained commands in docs/GETTING_STARTED.md.
  3. Review the data flow in docs/ARCHITECTURE.md.
  4. Use docs/PORTFOLIO_PROOF.md for the architecture diagram, walkthrough plan, tradeoffs, and interview prompts.
  5. Check PUBLIC_BOUNDARY.md before adding examples or generated artifacts.
  6. 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.

What It Does

  • 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/ and plugins/ directories with drift detection
  • MCP sync — translates .mcp.json server entries to .codex/config.toml blocks
  • 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

Install

go install github.com/hairglasses-studio/codexkit/cmd/codexkit@latest
go install github.com/hairglasses-studio/codexkit/cmd/codexkit-mcp@latest

Repo-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.

5-Minute Public Quickstart

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 ci

Expected result:

.                    PASS (31 checks)

Usage

CLI

# 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-home

Workspace Source Contract

codexkit 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.

MCP Server

{
  "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.

MCP Tools

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

Architecture

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.

Local CI

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 only

The 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 .

License

MIT

About

Deprecated public compatibility snapshot; active private Codex harness development lives in hairglasses-studio/codex-harness-staging/codexkit.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages