q

The quartermaster for your AI coding agents.

Define once. Run everywhere. Install anything into any harness.

Quick Start · What q Does · Manifest Reference · Commands · Examples

Claude Code and Codex have the same concepts, but different configuration models. Skills, mcps, subagents, hooks, prompts, and permissions are locked inside .claude/ or .codex/ with no way to share.

q bridges the gap: install anything into either harness from anywhere, or define your agent once in agent.spec and run it in both.

Install

bun add -g @tburnam/q

Quick Start

# Install a Claude Code plugin directly into Codex
q install codex https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design/skills/frontend-design

# Add an agent to your local registry
q add ./examples/agents/software-engineer

# Run it in either harness — same agent, different runtime
q claude software-engineer
q codex software-engineer

What q Does

Native Install

You already have Claude Code or Codex configs — skills, plugins, hooks scattered across .claude/ and .codex/. q lets you install anything into either harness from any source: local directories, GitHub repos, or nested monorepos. It handles format translation automatically.

# Install the Claude Code frontend-design plugin into Codex
q install codex https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design/skills/frontend-design
# -> Installed 'frontend-design' to .codex/ (project)

# Install a local agent into Claude Code at user scope
q install claude ./my-agent user
# -> Installed 'my-agent' to ~/.claude/plugins/my-agent/ (user)

# Install into both harnesses at once
q install ./my-agent

No agent.spec required. q detects Claude plugins, Codex skills, SKILL.md files, and MCP configs automatically.

agent.spec — Define Once, Run Everywhere

For teams building sophisticated agent configurations, agent.spec is a single YAML manifest that defines your entire agent — prompt, skills, subagents, hooks, MCPs, permissions — and runs identically in Claude Code or Codex.

q claude software-engineer    # launches Claude Code
q codex software-engineer     # same agent, launches Codex
q codex web-engineer          # or any other agent

q transpiles everything at runtime: models, permissions, hooks, sandbox policies. Your persistent Claude and Codex configs are never touched.

q add — The Registry Flow

# Add from a local directory
q add ./my-agent

# Add from GitHub
q add owner/repo

# Add from a nested monorepo path
q add owner/repo/tree/main/agents/my-agent

q add discovers agent.spec files under the source and copies each agent bundle into your local registry (.qspec/). If no spec is found, it falls back to raw source detection — Claude plugins, Codex skills, and SKILL.md directories all work.

Agent Structure

Each agent is a directory with an agent.spec manifest and the files it references.

my-agent/
├── agent.spec              # manifest (YAML)
├── prompt.md               # system prompt
├── permissions.json        # tool allow/deny rules
├── hooks.json              # lifecycle hooks
├── mcps.json               # MCP server configs
├── skills/
│   └── implementation/
│       └── SKILL.md        # skill definition
├── commands/
│   └── ship.md             # markdown command
├── agents/
│   ├── worker.md           # subagent (Claude format, supports both)
│   └── reviewer.toml       # subagent (Codex format, supports both)
└── scripts/
    └── preflight.py        # hook scripts

Manifest Reference

agent.spec is YAML. Here's the full shape:

version: 1
name: software-engineer
description: General software engineer with implementation and release workflows.

system_prompt_file: prompt.md
model: sonnet
effort: high

permissions: permissions.json
hooks: hooks.json
mcps: mcps.json

skills:
  - source: skills/implementation-playbook
  - name: ship-release
    source: commands/ship.md

subagents:
  - source: agents/worker.md
  - name: release-manager
    system_prompt_file: agents/release-manager.md
    skills:
      - implementation-playbook

# Runtime-specific overrides
claude:
  model: sonnet
  tools: [Agent, Read, Grep, Bash]

codex:
  model: gpt-5.4
  sandbox_mode: workspace-write
  approval_policy: on-request

Shared Fields

| Field | Description | |:------|:------------| | name / description | Agent identity | | system_prompt / system_prompt_file | The agent's instructions | | model / effort | Runtime intent (effort: low, medium, high, xhigh) | | skills | Skill directories, markdown commands, or inline prompts | | subagents | Child agents with their own prompts, skills, and overrides | | permissions | Tool allow/deny lists (JSON file or inline) | | hooks | Lifecycle hooks with runtime token rewriting | | mcps | MCP server definitions (stdio or HTTP) |

Runtime Overrides

Every level supports escape hatches for harness-specific config:

Top level       →  claude: { }  /  codex: { }
Per skill       →  claude: { }  /  codex: { }
Per subagent    →  claude: { }  /  codex: { }

Hooks & Runtime Tokens

One hooks.json file drives both harnesses. q extracts the right events for each runtime.

Shared events (work in both Claude Code and Codex):

| Event | Description | Can Block? | |:------|:------------|:-----------| | SessionStart | Session begins | No | | PreToolUse | Before tool runs | Yes | | PostToolUse | After tool completes | No | | UserPromptSubmit | User sends prompt | Yes | | Stop | Agent finishes turn | Yes |

Codex PreToolUse/PostToolUse currently fire for the Bash tool only. Claude fires them for all tools.

Claude Code supports 20 additional events (SessionEnd, PermissionRequest, SubagentStart, TaskCreated, TeammateIdle, etc.) — put them in the claude block and they'll be ignored by Codex.

{
  "before_run": [
    { "command": "python3 ${Q_BUNDLE_ROOT}/scripts/preflight.py" }
  ],
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo 'tool called'" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "echo 'turn complete'" }] }
    ]
  },
  "claude": {
    "hooks": {
      "PostToolUseFailure": [
        { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo 'tool failed'" }] }
      ]
    }
  },
  "codex": {
    "notify": {
      "command": "python3",
      "args": ["${Q_BUNDLE_ROOT}/scripts/codex_notify.py"]
    }
  }
}

Available tokens — automatically rewritten at runtime:

| Token | Resolves to | |:------|:------------| | ${Q_BUNDLE_ROOT} | Root of the agent directory | | ${CLAUDE_PLUGIN_ROOT} | Claude plugin directory | | ${CODEX_HOME} | Codex home directory | | ${Q_CODEX_HOME} | Agent-scoped Codex home |

Commands

| Command | Description | |:--------|:------------| | q add <source> | Add agent(s) to the local registry | | q remove <name> | Remove an agent from the registry | | q create <name> | Scaffold a new agent directory | | q list | List installed agents | | q claude [name] | Run an agent in Claude Code (partial name matching) | | q codex [name] | Run an agent in Codex (partial name matching) | | q install [claude\|codex] <source> | Install natively (default: both) | | q uninstall [claude\|codex] <name> | Uninstall natively (default: both) |

Sources — local path, GitHub slug (owner/repo), tree path (owner/repo/tree/ref/path), full URL, or installed agent name. Agent names support partial matching.

Scope — q install defaults to project scope (.claude/, .codex/ in cwd). Pass user as the last argument to install globally (~/.claude/, ~/.codex/).

Examples

The repo ships with ready-to-use agents:

| Agent | Focus | Skills | Subagents | |:------|:------|:-------|:----------| | software-engineer | General development | implementation-playbook, test-discipline, ship-release | implementation-worker, bug-hunter, release-manager | | web-engineer | Frontend & UI | frontend-standards, accessibility-qa, run-ui-audit | ui-builder, browser-debugger, design-reviewer | | pr-review-toolkit | Code review | review-pr | 6 specialized reviewers |

# Try one out
q add ./examples/agents/software-engineer
q claude software-engineer

Development

# Run from source
bun run src/cli.ts --help

# Build
bun run build

# Test + validate
bun run check

Requirements — Bun >= 1.3 · claude and/or codex on PATH · git (for GitHub imports)

License

MIT