agex.toml
The project manifest — declares your project metadata and all artifact dependencies.
agex.toml is the manifest file that lives at the root of your project. It declares:
- Your project's metadata (name, stack, tools, author)
- Remote artifact dependencies from the hub
- Local file references that should be pushed and linked
Run agex init to generate one automatically based on your project's detected stack.
Full example
[project]
name = "my-nextjs-app"
version = "1.0.0"
description = "Production Next.js setup with TypeScript, Tailwind, and Postgres"
author = "rkrebs"
tools = ["claude-code", "cursor"]
stack = ["nextjs", "typescript", "tailwind", "postgres", "drizzle"]
repository = "https://github.com/rkrebs/my-nextjs-app"
license = "MIT"
[rules]
# Remote artifact — pulled from the hub
main-rules = "@rkrebs/nextjs-claude@2"
# Local file — pushed to hub when you run `agex push .`
local-rules = "local:CLAUDE.md"
[skills]
deploy = "@rkrebs/vercel-deploy-recipe"
migrate = "@rkrebs/drizzle-migration-skill"
[mcp]
database = "@rkrebs/postgres-mcp"
websearch = "@someone/brave-search-mcp"
[hooks]
pre-tool = "@rkrebs/eslint-pre-tool-hook"
[subagents]
frontend = "@rkrebs/frontend-specialist"
testing = "@rkrebs/test-writer-agent"Sections
[project]
| Key | Required | Description |
|---|---|---|
name | Yes | Project name (used as the slug on the hub) |
version | No | Semantic version string |
description | No | Short description shown on the hub |
author | No | GitHub username of the author |
tools | No | Agentic tools used (determines file placement) |
stack | No | Tech stack tags for discoverability |
repository | No | Git repository URL |
license | No | License identifier (e.g. MIT) |
The tools array is critical — it tells the CLI which platform-specific locations to write files to when syncing. Supported values: claude-code, cursor, codex, gemini-cli, opencode.
[rules], [skills], [mcp], [hooks], [subagents]
Each section maps a local name (used as the key in your manifest) to an artifact reference.
[rules]
my-name = "@username/artifact-slug"
my-name = "@username/artifact-slug@3" # pinned to version 3
my-name = "local:path/to/file.md" # local file referenceSections and their artifact categories:
| Section | Category | Typical types |
|---|---|---|
[rules] | Rules | claude-md, cursorrules, agents-md, gemini-md |
[skills] | Skills | skill-action, skill-reference, skill-recipe |
[mcp] | MCP Servers | mcp-config, mcp-server-code |
[hooks] | Hooks | hook, hook-config |
[agents] | Agents | subagent, agent-team, agent-prompt |
[commands] | Commands | command, slash-command |
[cli-tools] | CLI Tools | cli-tool, cli-extension |
Artifact references
@username/slug # latest version
@username/slug@3 # pinned to version 3
local:relative/path.md # local fileThe @ prefix is optional — @rkrebs/my-config and rkrebs/my-config are equivalent.
Version pinning
By default, agex sync fetches the latest version of each artifact. Pin to a specific version to avoid unexpected changes:
[rules]
rules = "@rkrebs/nextjs-claude@2"To upgrade a pinned artifact, update the version number and re-run agex sync.