codexkit

README

codexkit

Fleet management toolkit for AI agent repos — baseline validation, skill surface sync, and MCP profile management.

Engineering context: codexkit automates the operational overhead of maintaining consistent agent configurations across a fleet of repositories. The same patterns that production platforms need for fleet-wide config validation, drift detection, and automated remediation.

What It Does

• Baseline validation — 14 checks ensuring every repo has canonical agent configs, required profiles, 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
• Fleet audit — runs baseline + skill + MCP checks across all repos in a workspace
• Performance audit — scans for Codex performance bottlenecks and regression budgets
• 12 MCP tools — all operations available via MCP server for AI agent consumption

Install

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

Usage

CLI

# Validate a single repo
codexkit baseline check ~/hairglasses-studio/mcpkit

# Audit the entire fleet
codexkit fleet audit ~/hairglasses-studio

# Show skill drift without applying
codexkit skill diff ~/hairglasses-studio/ralphglasses

# Sync MCP configs
codexkit mcp sync ~/hairglasses-studio/dotfiles

MCP Server

{
  "mcpServers": {
    "codexkit": {
      "command": "codexkit-mcp",
      "args": ["--workspace", "~/hairglasses-studio"]
    }
  }
}

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

Architecture

codexkit/
├── baselineguard/   # 14-check repo validation engine
├── skillsync/       # Skill surface mirror management
├── mcpsync/         # MCP-to-Codex config translation
├── 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.

Build

go build ./...           # Build all
go vet ./...             # Lint
go test -count=1 -race ./...  # Test

License

MIT

Documentation

Overview

Package codexkit provides the ToolModule interface and shared types used by all codexkit packages.

Index

• Variables
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Call(toolName string, params map[string]any) (any, error)
  • func (r *Registry) HasTool(name string) bool
  • func (r *Registry) ListModules() []string
  • func (r *Registry) ListTools() []ToolDef
  • func (r *Registry) Register(m ToolModule) error
• type ToolDef
• type ToolModule

Variables

var PortableFrontmatterKeys = map[string]bool{
	"name":          true,
	"description":   true,
	"allowed-tools": true,
	"reload":        true,
}

PortableFrontmatterKeys are the only keys allowed in portable skill frontmatter per the Agent Skills open standard (Dec 2025).

Types

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds all registered ToolModules and dispatches tool calls.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty module registry.

func (*Registry) Call

func (r *Registry) Call(toolName string, params map[string]any) (any, error)

Call dispatches a tool call by name.

func (*Registry) HasTool

func (r *Registry) HasTool(name string) bool

HasTool checks if a tool is registered.

func (*Registry) ListModules

func (r *Registry) ListModules() []string

ListModules returns the names of all registered modules.

func (*Registry) ListTools

func (r *Registry) ListTools() []ToolDef

ListTools returns all registered tool definitions.

func (*Registry) Register

func (r *Registry) Register(m ToolModule) error

Register adds a module and indexes its tools. Init is called once.

type ToolDef

type ToolDef struct {
	// Name is the tool identifier (e.g. "baseline_check").
	Name string `json:"name"`

	// Description is a short human-readable summary.
	Description string `json:"description"`

	// Schema is the JSON Schema for the tool's input parameters.
	// nil means the tool takes no parameters.
	Schema map[string]any `json:"inputSchema,omitempty"`

	// Handler executes the tool with the given parameters and returns
	// a result or error.
	Handler func(params map[string]any) (any, error) `json:"-"`
}

ToolDef describes a single tool exposed by a module.

type ToolModule

type ToolModule interface {
	// Name returns the module identifier (e.g. "baselineguard").
	Name() string

	// Tools returns the tool definitions provided by this module.
	Tools() []ToolDef

	// Init performs any one-time setup. Called before first tool use.
	Init() error
}

ToolModule is the interface that all codexkit packages implement. It is modeled after claudekit's ToolModule pattern: each package registers itself as a named module exposing a set of typed tool definitions that can be aggregated by the MCP server or CLI.