How It Works

The problem agex solves

Every developer using Claude Code, Cursor, or another agentic tool has gone through the same process: you write a CLAUDE.md, iterate on it for weeks, discover what constraints actually work, and end up with something genuinely useful. Then you start a new project and start from scratch — or copy-paste from your last repo, hoping it still applies.

There's no npm-equivalent for agent configurations. No discoverable registry. No versioning. No community signal about what works across different stacks.

agex treats agent configurations as the artifact type they actually are: something worth publishing, versioning, discovering, and importing — just like any other dependency.

Supported platforms

agex currently supports five agentic coding tools. Each has different conventions for how it reads context and what kinds of artifacts it accepts.

Claude Code

Made by Anthropic. A terminal-based agentic coding tool that works in any codebase.

Claude Code has the richest artifact support — it can use every artifact type agex supports.

Cursor

An AI-native IDE built on VS Code (Anysphere).

Cursor rules support alwaysApply, globs, and description frontmatter in .mdc files for fine-grained control over when rules are applied.

Codex

OpenAI's agentic coding CLI. Reads AGENTS.md for project instructions.

Gemini CLI

Google's terminal-based agentic coding tool. Also uses AGENTS.md.

OpenCode

Open-source agentic coding CLI. Uses the AGENTS.md convention.

Artifact categories

All content on agex is organized into seven categories. See Artifacts for the full reference.

The agex.toml manifest

agex.toml is the dependency manifest for your project's agent configuration. It lives at the root of your repo and declares:

1. What tools you use — so the CLI knows where to write files
2. What remote artifacts you depend on — fetched from the hub
3. What local files you want to publish — pushed to the hub as artifacts

[project]
name  = "my-app"
tools = ["claude-code", "cursor"]
stack = ["nextjs", "typescript", "postgres"]

[rules]
main    = "@rkrebs/nextjs-claude@2"   # remote, pinned to version 2
local   = "local:CLAUDE.md"           # local file

[skills]
deploy  = "@rkrebs/vercel-deploy-recipe"

[mcp]
db      = "@rkrebs/postgres-mcp"

The tools field is the key one — it tells the CLI where to materialize each artifact. A mcp-server artifact goes to .mcp.json for Claude Code, and .cursor/mcp.json for Cursor. A CLAUDE.md artifact goes to CLAUDE.md if it's local, or .claude/rules/{slug}.md if it's a remote artifact (to avoid overwriting your own config).

How file placement works

When you run agex sync, the CLI resolves every artifact reference in agex.toml and writes files to the correct locations for each tool in your tools array.

For example, with tools = ["claude-code", "cursor"] and an MCP server artifact, the CLI writes to both .mcp.json and .cursor/mcp.json — keeping the entries for each tool in sync automatically.

For shared file types like CLAUDE.md, remote artifacts (pulled from the hub) are written to a namespaced location — .claude/rules/{slug}.md — so they never overwrite your own CLAUDE.md. Local artifacts (local:) go directly to CLAUDE.md because they are your config.

JSON artifacts (MCP servers, hooks) use a merge strategy: the artifact's JSON is merged into the existing file rather than replacing it. Each merged entry is tagged with a _agex_ref identifier so it can be cleanly removed later with agex remove.

See File Placement for the full rule table.

The full workflow

Starting a project from scratch

# 1. Install the CLI and log in (one-time)
npm install -g agex
agex login

# 2. Detect your stack and generate agex.toml
agex init

# 3. Discover what the community uses
agex search "nextjs claude"
agex info @rkrebs/nextjs-claude

# 4. Add what looks useful
agex add @rkrebs/nextjs-claude
agex add @someone/postgres-mcp

# 5. All files are now on disk in the right places
# CLAUDE.md → .claude/rules/nextjs-claude.md
# .mcp.json → merged with postgres-mcp entry

Sharing your configs

# Push a single artifact to the hub
agex push CLAUDE.md

# Or bundle everything in agex.toml as a project
agex push .

When you push CLAUDE.md, the CLI auto-detects the artifact type, prompts for a title and optional description, and publishes it. If it already exists (matched by slug), it creates a new version instead.

When you push ., the CLI reads agex.toml, uploads any local: file references as individual artifacts, then creates or updates the project on the hub linking everything together.

Keeping configs up to date

# After editing CLAUDE.md locally:
agex push CLAUDE.md --changelog "Add testing conventions"

# After a new artifact version is released:
# Update the version pin in agex.toml, then:
agex sync

Onboarding a new team member or new machine

git clone <your-repo>
cd your-repo
agex sync   # pulls all artifacts from agex.toml and writes them to disk

Authentication

agex uses GitHub OAuth for web sessions and GitHub device flow for the CLI. There are no API tokens to manage — the CLI handles the full auth flow with a single command.

agex login
# → Prints a code like ABCD-1234
# → Opens github.com/login/device
# → You enter the code and authorize
# → CLI stores the session locally

Your GitHub username becomes your agex username. All artifacts you publish are namespaced under it: @yourusername/artifact-slug.

Identity and trust

agex uses GitHub identity as the trust primitive. There are no verified accounts, sponsored placements, or editorial curation — ranking is entirely driven by community upvotes from real practitioners.

An artifact with 200 upvotes from engineers who actually use it every day is worth more than any editorial endorsement. This is the same bet Hacker News and npm made, and it scales the same way.

What's coming

• Feed — a Hacker News-style discussion board for agentic coding, built on the same GitHub identity
• Registry — a curated directory of agentic tools and MCP servers with structured metadata, compatibility tags, and community reviews
• Guides — community-maintained living documents (getting started guides, task-specific recipes, framework-specific patterns)
• MCP server — an agex MCP server so your AI agent can search and pull artifacts from the hub directly within a session