Projects

A project is a curated bundle of artifacts that work together for a specific stack or workflow. Where an artifact is a single file, a project is the complete agentic setup for a codebase.

What goes in a project

A project can include artifacts from any of the four categories:

• Rules — the CLAUDE.md, .cursorrules, or AGENTS.md that gives the agent codebase context
• Skills — on-demand workflows for common tasks (deployment, migrations, PR review)
• MCP servers — tools the agent can call (database access, web search, etc.)
• Hooks — lifecycle scripts (linting before tool calls, logging after)
• Subagents — specialized agents for specific domains (frontend, testing, docs)

Defining a project with agex.toml

Run agex init in your project root to generate an agex.toml. You can then add remote artifacts or reference local files.

[project]
name        = "my-nextjs-app"
description = "Next.js 15 + TypeScript + Tailwind agentic setup"
tools       = ["claude-code", "cursor"]
stack       = ["nextjs", "typescript", "tailwind", "postgres"]
author      = "rkrebs"
repository  = "https://github.com/rkrebs/my-nextjs-app"
license     = "MIT"

[rules]
# Remote artifact from the hub
main = "@rkrebs/nextjs-claude"

# Local file reference — pushed automatically with agex push .
local-rules = "local:CLAUDE.md"

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

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

[hooks]
lint = "@rkrebs/eslint-pre-tool-hook"

[subagents]
frontend = "@rkrebs/frontend-agent"

Publishing a project

agex push .

This command:

1. Pushes any local: file references as new artifacts (or updates them if they already exist)
2. Creates or updates the project on the hub with all artifact linkages
3. Prints a summary and the hub URL

Pulling a project

Anyone can pull your project into their own codebase:

agex add @rkrebs/my-nextjs-app   # adds to agex.toml
agex sync                         # materializes all artifacts

Or in one step:

agex add @rkrebs/my-nextjs-app && agex sync

Local references

The local: prefix lets you reference a file in your repo that isn't yet on the hub. When you run agex push ., local references are automatically uploaded as artifacts first, then linked into the project.

[rules]
main = "local:CLAUDE.md"

This is the recommended workflow when iterating on a config — work locally, push when ready.