universal-agent-toolkit

Cross-project guardrails for AI coding agents.

Why We Built This

AI agents move fast, but they can repeat bad patterns across projects:

• duplicate code and files
• broken edits that pass unnoticed
• billing/retry loops
• inconsistent provider setup per repo

universal-agent-toolkit gives one simple CLI to apply the same guardrails everywhere.

What It Solves

• Syncs agent provider folders into any project quickly.
• Keeps provider hook/rule setup consistent across repos.
• Runs checks that catch common AI coding mistakes early.

Quick Start

Run from any project root:

npx universal-agent-toolkit
# or from this repo
pnpm start

Single CLI menu includes provider sync, tests, dedup, Docker verify, and Cursor maintenance tools.

The toolkit also self-checks for newer npm releases when you run the CLI, and this repo's pre-commit / pre-push hooks do the same. Disable with AI_GUARD_AUTO_UPDATE=0.

This opens a simple menu:

• Add providers
• Sync all
• Bridge rules
• Toggle Claude config between Z.AI and native Claude
• Set Z.AI Claude model mapping
• Launch one-off native Claude or Z.AI Claude sessions
• Launch one-off Codex sessions with model/thinking overrides
• Forward into the standalone Agent OS CLI
• Dedup scan
• Run tests

Most Useful Commands

# Interactive menu
npx universal-agent-toolkit

# Add selected providers only
npx universal-agent-toolkit providers

# Sync everything
npx universal-agent-toolkit sync --all

# Toggle Claude Code global config
npx universal-agent-toolkit claude-provider
npx universal-agent-toolkit claude-provider status
npx universal-agent-toolkit claude-provider zai
npx universal-agent-toolkit claude-provider claude

# Launch Claude Code with a provider for this session only
# These do not rewrite ~/.claude/settings.json, so both can run at the same time.
npx universal-agent-toolkit claude-launch zai
npx universal-agent-toolkit claude-launch claude
npx universal-agent-toolkit claude-launch zai -- -p "Reply with ok"

# Same launchers after global install
claude-zai
claude-native

# Launch Codex with model/thinking for this session only
# Uses Codex's documented --model flag and -c model_reasoning_effort=... override.
npx universal-agent-toolkit codex-launch --model gpt-5.5 --thinking xhigh
npx universal-agent-toolkit codex-launch --model gpt-5.4 --effort high -- --no-alt-screen
codex-launch --model gpt-5.5 --thinking xhigh

# Forward to standalone Agent OS
npx universal-agent-toolkit agent-os -- doctor

# Install global Codex/Claude hooks, including strict orchestrator-mode guards.
# The main agent delegates repo reading/searching/editing to agent-os workers.
AI_GUARD_PLATFORM=codex bash install.sh
AI_GUARD_PLATFORM=claude bash install.sh

# Set the Z.AI model mapping used by Claude Code
npx universal-agent-toolkit claude-model glm-5.1
npx universal-agent-toolkit claude-model glm-5-turbo
npx universal-agent-toolkit claude-model glm-4.7
npx universal-agent-toolkit claude-model glm-4.5-air
npx universal-agent-toolkit claude-model default
npx universal-agent-toolkit claude-model --opus glm-5.1 --sonnet glm-5-turbo --haiku glm-4.5-air

# Dedup scan + safe automatic fixes + rescan
npx universal-agent-toolkit dedup --fix-safe

# Python function dedup report
npx universal-agent-toolkit dedup --language python --json

# Scan all supported languages in one report
npx universal-agent-toolkit dedup --language all --json

# Dedup scan + aggressive automatic fixes + rescan
npx universal-agent-toolkit dedup --fix-aggressive

# Legacy shortcut still supported
npx universal-agent-toolkit --providers codex,gemini,core

Cross-Project Workflow

In each new repo:

cd /path/to/project
npx universal-agent-toolkit

Pick the providers you want (.claude, .codex, .cursor, .gemini, .opencode, .clinerules, .kilo, optional .ai-guard core), and the toolkit syncs them into that project.

Claude Provider Toggle

The CLI can also toggle your global Claude Code user config in ~/.claude/settings.json between:

• native Claude
• Z.AI's Anthropic-compatible endpoint

The toggle only manages the Z.AI-specific env keys documented by Z.AI:

• ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
• API_TIMEOUT_MS=3000000

If a prior Z.AI config exists, the toolkit stores a small backup in ~/.claude/.universal-agent-toolkit-zai-backup.json so you can switch off and back on without re-entering the API key. Unrelated Claude settings stay intact.

For concurrent sessions, use the launch command instead of the global toggle:

• claude-launch zai starts Claude Code through Z.AI for only that process.
• claude-launch claude starts Claude Code through native Claude for only that process.
• claude-zai and claude-native are global-install shortcuts for the same behavior.

The launcher writes a temporary settings file and passes it to Claude Code with --settings, so the global provider setting is not changed while the session runs.

Current Z.AI Coding Plan models documented for Claude Code:

• glm-5.1 - 200K context
• glm-5-turbo - 200K context
• glm-4.7 - 200K context
• glm-4.5-air - 128K context

The CLI supports both documented presets and explicit slot mappings:

• claude-model glm-5.1 This writes the documented high-end mapping: opus=glm-5.1, sonnet=glm-5-turbo, haiku=glm-4.5-air.
• claude-model default This removes the explicit model mapping keys so Claude Code falls back to Z.AI's current server-side defaults.
• claude-model --opus ... --sonnet ... --haiku ... This lets you set each Claude internal slot directly.

Codex Launch

The Codex launcher is a one-process wrapper. It does not rewrite ~/.codex/config.toml.

• codex-launch --model gpt-5.5 --thinking xhigh
• codex-launch --model gpt-5.4 --effort high
• universal-agent-toolkit codex-launch --list-models

Official Codex docs support --model at launch and command-line config overrides with -c; the wrapper maps --thinking / --effort to -c model_reasoning_effort="...".

Agent OS Bridge

The Agent OS bridge keeps this toolkit thin. It forwards arguments to the standalone agent-os CLI without importing Agent OS internals:

• AGENT_OS_BIN=/path/to/agent-os universal-agent-toolkit agent-os -- doctor
• sibling /Applications/Github/universal-agent-os dev CLI when src/bin/agent-os.ts and local tsx exist
• sibling build output at /Applications/Github/universal-agent-os/dist/src/bin/agent-os.js
• global agent-os

The bridge streams Agent OS stdio and keeps the caller's current working directory, so running it from any project targets that project.

Dedup Languages

The dedup report supports language filters:

• --language auto - current default JavaScript/TypeScript behavior
• --language python - Python function duplicate report
• --language typescript
• --language javascript
• --language all

Python scanning uses Python AST extraction when python3 is available and falls back to indentation parsing if needed. Python/all-language runs generate reports only; automatic fixes remain limited to JavaScript/TypeScript.

The Python report is tuned for precision: same-name-only matches are ignored unless the bodies also match, tiny property/accessor methods are skipped, and short coercion helpers must be exact matches before they appear in the report.

License

MIT