# agex.dev

## What is agex?

agex.dev is a community-driven platform for agentic coding practitioners. It is the central hub where developers who ship code with AI agents come to discover tools, share configurations, discuss workflows, and learn from each other.

The agentic coding ecosystem is fragmented. Tools are reviewed in static blog posts. MCP servers are cataloged in directories with no community signal. Agent rule files (CLAUDE.md, .cursorrules, AGENTS.md) are scattered across GitHub gists and forum threads. Skills, hooks, and subagent definitions live in random repos with no discoverability. Discussion happens across dozens of subreddits and vendor-specific forums. agex brings all of this together in one place, organized around what practitioners actually need.

## Vision

agex sits at the intersection of three models:

- **HuggingFace** — for sharing and distributing artifacts (rules, skills, MCP configs, hooks, plugins) with a CLI-first workflow. Like `huggingface-cli` for models, `agex` is the CLI for agentic coding artifacts.
- **GitHub** — for version-controlled, unified storage with project-level organization. No more bloated git repos with scattered markdown files. agex is the canonical home for your agentic setup, referenced by a thin `agex.toml` pointer. Users and orgs organize artifacts into projects that can be pulled in as a unit.
- **Hacker News** — for community discussion, tool sharing, and surfacing what practitioners actually care about.

The CLI-agent era (Claude Code, Codex, Gemini CLI, Aider) means developers live in the terminal. agex must be CLI-native — the web hub is for browsing and community, the CLI is for daily workflow integration.

## The agex Ecosystem

### 1. The Hub (agex.dev — web)

The browsable registry and community platform.

#### Artifact Categories

agex organizes shareable agentic coding artifacts into four top-level categories, reflecting how the agentic coding extension ecosystem actually works:

##### Rules (always-on context)

Agent configuration files that load every session. These define project conventions, coding standards, and "always do X" instructions.

- **CLAUDE.md** — Claude Code project context and instructions
- **.cursorrules / .cursor/rules/** — Cursor AI rules
- **AGENTS.md** — Agent-agnostic project instructions
- **Copilot Instructions** — GitHub Copilot custom instructions
- **Other agent rules** — Any tool-specific rule file

##### Skills (on-demand knowledge & workflows)

Reusable markdown files containing knowledge, workflows, or instructions that agents load on demand. Skills are the most flexible extension type.

- **Reference skills** — API docs, style guides, schema references
- **Action skills** — invocable workflows triggered with `/<name>` (deploy, review, audit)
- **Recipes** — task-specific how-to guides (e.g. "set up monorepo with Claude Code")

##### Tools (external connections & automation)

MCP servers, CLI tools, and integrations that connect agents to external services.

- **MCP Servers** — database connectors, Slack, browser control, etc.
- **CLI Tools** — standalone agentic CLI tools
- **Extensions/Plugins** — IDE extensions, agent plugins
- **Bundles/Plugins** — packaged combinations of skills + hooks + MCP + subagents

##### Automation (workflow automation)

Hooks, subagent definitions, and agent team configurations.

- **Hooks** — deterministic scripts that run on agent lifecycle events (pre-edit lint, post-commit notify)
- **Subagent definitions** — custom worker agents with instructions and preloaded skills
- **Agent team configs** — multi-agent coordination setups
- **CI/CD integrations** — agent-powered pipeline steps

#### Feed (Community Discussion)

A Hacker News-style link and discussion feed focused exclusively on agentic coding. Users submit links, write text posts, and discuss. Content is ranked by upvotes and recency.

Posts are tagged by topic (e.g. `claude-code`, `cursor`, `mcp`, `rules`, `workflow`, `release`, `discussion`).

#### Projects (GitHub-style Organization)

Users and organizations can create **projects** that bundle artifacts together for a specific use case or repository. A project is like a GitHub repo for your agentic setup:

- A project references multiple artifacts: rules, skills, MCP configs, hooks
- Projects can be pulled in as a unit with `agex pull @user/project-name`
- Each project has an `agex.toml` manifest that declares its artifacts
- Projects can be forked, versioned, and commented on
- Organizations can maintain shared projects (e.g. `@mycompany/standard-setup`)

This replaces the pattern of checking in CLAUDE.md, .cursorrules, hooks, etc. into every repo. Instead, you reference a project on agex and pull it in.

#### User Profiles

Each user has a public profile showing:
- Their shared artifacts with version history
- Their projects
- Tools they use ("I use this" stack)
- Community contributions (posts, comments, reviews)
- Reputation earned through contributions
- Organizations they belong to

### 2. The CLI (`agex`)

The CLI is what makes agex sticky in a CLI-agent world. It is the primary distribution mechanism.

```
agex init                              # creates agex.toml, detects your stack
agex login                             # GitHub OAuth device flow
agex pull @user/artifact               # pulls a single artifact
agex pull @user/project                # pulls all artifacts in a project
agex push                              # shares an artifact to the hub
agex search "react typescript skills"  # find artifacts by type/stack
agex browse                            # interactive TUI browser
agex sync                              # sync local artifacts with hub versions
agex clean                             # remove cached/materialized files
agex add @user/skill-name              # add an artifact to current project
agex remove @user/skill-name           # remove from current project
```

Key design decisions:
- The CLI reads `agex.toml` and materializes artifacts locally
- Artifacts are cached locally in `.agex/cache/`, `agex clean` removes them
- Progressive fetch: main content by default, `--full` for all reference files, `--file` for specific ones
- Annotations: `agex annotate @user/config "note"` stores local notes in `.agex/annotations/` that persist across sessions and auto-append on future fetches — agents get smarter over time
- Structured feedback: `agex feedback @user/config up --label accurate` sends quality signals to authors
- The CLI should be lightweight — no heavy runtime dependencies
- Should work as a Claude Code plugin that reads the toml on init

### 4. The MCP Server (`agex-mcp`)

An MCP server that exposes agex as tools for AI agents. Agents can search, fetch, annotate, and rate artifacts directly without the CLI.

Tools:
- `agex_search` — search artifacts by query, category, tags
- `agex_get` — fetch artifact content by @user/slug
- `agex_list` — list all artifacts with filters
- `agex_annotate` — read/write/clear local annotations
- `agex_feedback` — rate artifacts with structured labels

Resource:
- `agex://registry` — full artifact registry as JSON

Distributed as `agex-mcp` binary alongside the CLI. Configurable in Claude Code, Cursor, etc.

### 3. The Manifest (`agex.toml`)

A lightweight project manifest that replaces bloated config files with versioned pointers:

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

[rules]
claude = "@rkrebs/nextjs-claude@v2"
cursorrules = "@community/react-best-practices@latest"

[skills]
deploy = "@devops/vercel-deploy@v1"
review = "@community/code-review-checklist@latest"
api-docs = "@rkrebs/rest-api-patterns@v3"

[mcp]
database = "@tools/supabase-mcp@latest"
slack = "@tools/slack-mcp@v2"

[hooks]
pre-edit = "@tooling/eslint-check@latest"
post-commit = "@tooling/conventional-commits@v1"

[subagents]
security-reviewer = "@security/owasp-checker@latest"
```

This solves the bloat problem — your project has a thin `agex.toml` pointer file instead of dozens of config files copied from gists. The CLI materializes the actual files from the hub.

## Key Design Principles

- **Practitioner-first, not vendor-first.** Content is organized by what you're trying to accomplish, not by which company made the tool. agex is neutral ground.
- **CLI-native.** The terminal is where agentic coding happens. The CLI is not an afterthought — it's the primary workflow integration point.
- **Project-centric.** Artifacts are organized into projects, not scattered individually. A project is a complete agentic setup you can pull into any repo.
- **Community signal over marketing.** Real usage data, honest reviews, and upvotes from practitioners. No sponsored placements or pay-to-rank.
- **Trust signaling.** Artifacts have source badges (official, maintainer, community). Structured feedback (accurate, outdated, incomplete) flows to authors. Quality is surfaced, not just popularity.
- **Self-improving agents.** Annotations persist across sessions. Agents discover gaps, annotate locally, and are smarter next time. Feedback loops improve content for everyone.
- **Artifacts are content.** Rules, skills, hooks, and configs are valuable knowledge artifacts that deserve to be discoverable, shareable, and versioned.
- **Simple and fast.** Developer audience expects speed. No bloat, no unnecessary JavaScript, fast page loads.
- **Open contribution.** Anyone with a GitHub account can submit artifacts, share projects, write guides, and participate in discussions.
- **No bloat.** The `agex.toml` pattern keeps projects clean. Artifacts live on the hub, not scattered across repos.

## Information Architecture

```
hub.agex.dev (dev: /app)
├── /                             # Dashboard (your projects, starred, activity)
├── /configs                      # Browse all artifacts (rules, skills, tools, automation)
│   ├── /configs/new              # Create/upload artifact
│   └── /configs/@user/slug       # Artifact detail (versions, comments, pull command)
├── /projects                     # Browse projects (bundled artifact sets)
│   ├── /projects/new             # Create project
│   └── /projects/@user/slug      # Project detail (manifest, included artifacts)
├── /feed                         # HN-style discussion feed
│   ├── /feed/new
│   ├── /feed/top
│   └── /feed/:id
├── /tools                        # Tool & resource registry
│   ├── /tools/:slug
│   └── /tools/submit
├── /u/:username                  # User profile
└── /org/:orgname                 # Organization profile

agex.dev (marketing)
├── /                             # Landing page
├── /login                        # GitHub OAuth login
├── /about, /docs, /blog          # Marketing pages
```

## User Model

- Authentication via GitHub OAuth (NextAuth).
- Users have a profile showing their submissions, reviews, and activity.
- Organizations for team-shared projects and artifacts.
- Reputation is earned through contributions (submissions, reviews, helpful comments).
- No anonymous posting — GitHub identity provides accountability.

## Tech Stack

- Next.js (App Router) with React
- Tailwind CSS + shadcn/ui for styling (+ ReactBits, Magic UI for effects)
- Node.js server layer
- Supabase Postgres database
- Drizzle ORM
- NextAuth v5 with GitHub OAuth
- Markdown rendering with syntax highlighting
- CLI: Node/Bun for initial development, potentially Go for distribution