agx

agx

One config for every coding agent.
Skills, MCP servers, and instructions — scoped to the directory you're in.

Codex · Claude Code · Pi

What it looks like

# ~/.config/agx/agx.d/main.yaml, listed in agx.yaml
packages:
  mattpocock:
    git: https://github.com/mattpocock/skills.git

mcp:
  context7:   { url: https://mcp.context7.com/mcp, auth: none }
  github:     { url: https://api.githubcopilot.com/mcp/, auth: keychain }
  playwright: { command: [npx, -y, '@playwright/mcp@latest'] }

instructions:
  house-rules:
    text: Use pnpm, not npm. Write conventional commits.

scopes:
  - add:                                  # everywhere
      skills: [mattpocock/tdd, mattpocock/grill-me, mattpocock/diagnosing-bugs]
      instructions: [house-rules]
      mcp: [context7, github]
  - directory: ~/work                     # work projects only
    add:
      skills: [mattpocock/pr]
  - directory: ~/work/acme-web            # just this repo
    add:
      mcp: [playwright]

$ cd ~/work/acme-web
$ agx claude   # 4 skills, house rules, context7 + github + playwright
$ agx codex    # same
$ agx pi       # same

$ cd ~/oss/blog
$ agx claude   # no pr skill, no playwright

Features

Install

Download agx from the releases page and put it on your PATH.

xattr -d com.apple.quarantine ./agx

mise use -g github:tarik02-org/agx

nix profile install github:tarik02-org/agx

{ config, pkgs, ... }: {
  imports = [ inputs.agx.homeManagerModules.default ];
  programs.agx = {
    enable = true;
    settings.mcp.docs = {
      url = "https://docs.example.com/mcp";
      headers.X-Api-Key = config.lib.agx.secret "docs-key"; # !secret docs-key
    };
    harnesses.codex.package = pkgs.codex; # `codex` runs through agx
  };
}

go install github.com/tarik02-org/agx/cmd/agx@latest

Get started

agx skill add mattpocock/skills --skill tdd --skill grill-me
agx mcp add context7 https://mcp.context7.com/mcp --auth none
agx mcp add playwright --scope here -- npx -y @playwright/mcp@latest
agx explain
agx claude

Every command shows a diff before it writes. Continue with the getting started guide.

Integrations

Any tool that starts Codex, Claude Code, or Pi can run them through agx: point it at a shim instead of the agent's own binary. See Integrations for T3 Code.

Docs

Getting started · Configuration · Harnesses · MCP servers · Skills & packages · Secrets · Sessions · Integrations · Daemon · Troubleshooting · Security · CLI reference

Working on agx itself? See the development notes and the changelog.

_{MIT licensed}