Getting Started

Add SurfContext to your project in 5 steps. No dependencies, no build step, no lock-in.

Create CONTEXT.md

Create a CONTEXT.md file in your project root. This is your canonical project context -- the single source of truth that all AI agents will read.

CONTEXT.md

# My Project

Brief description of what this project does and why it exists.

## Key Files

| Path | Purpose |
|------|---------|
| `src/` | Application source code |
| `tests/` | Test files |
| `.context/agents/` | Agent definitions |
| `.context/docs/` | Knowledge documents |

## Architecture

Describe your system architecture at a high level. Include
frameworks, data flow, and deployment targets.

## Stack & Development

**Stack**: TypeScript, React, Node.js
**Run locally**: `npm run dev`
**Run tests**: `npm test`
**Lint**: `npm run lint`

## Conventions

- List any coding conventions your project follows
- Include naming patterns, file organization rules, etc.

Create .context/ directory

Set up the context directory with subdirectories for agents and knowledge docs.

Terminal

mkdir -p .context/agents .context/docs

Add your first agent definition:

.context/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools:
  - Read
  - Grep
  - Glob
model: sonnet
---

# Code Reviewer

You review pull requests and code changes for:

- Security vulnerabilities
- Performance issues
- Code style consistency
- Test coverage gaps

## Rules

- Always explain *why* something is a problem, not just *what*
- Suggest specific fixes, not vague improvements
- Check for proper error handling in all async operations

Add surfcontext.json

Create a surfcontext.json manifest to declare your target platforms and generation settings.

surfcontext.json

{
  "version": "2.0",
  "source": "manual",
  "platforms": ["claude", "codex", "cursor"],
  "canonical": {
    "rootContext": "CONTEXT.md",
    "docsDir": ".context/docs",
    "agentsDir": ".context/agents"
  },
  "generation": {
    "claude": {
      "rootContext": "CLAUDE.md",
      "method": "sed-copy"
    },
    "codex": {
      "rootContext": "AGENTS.md",
      "method": "sed-copy"
    }
  }
}

Generate platform files (optional)

Generate platform-specific config files from your canonical context. For now, a simple copy works. The SurfContext CLI will automate this.

Terminal

# Copy CONTEXT.md to generate platform files
cp CONTEXT.md CLAUDE.md
cp CONTEXT.md AGENTS.md

# Add a generated-file header (optional but recommended)
# You can also use the SurfContext CLI when available:
# npx surfcontext generate

Open in your AI tool

Open your project in Claude Code, Cursor, Codex CLI, or any supported tool. The AI agent will automatically discover and read your project context.

That's it. Your final project structure looks like this:

Final Structure

my-project/
  CONTEXT.md              # Your canonical context (source of truth)
  surfcontext.json        # Platform targeting config
  .context/
    agents/
      code-reviewer.md    # Your agent definition
    docs/                 # Add knowledge docs as needed
  CLAUDE.md               # Generated for Claude Code
  AGENTS.md               # Generated for Codex CLI

Next steps

--Read the full specification for detailed requirements and examples
--Add knowledge docs to .context/docs/ for architecture decisions, API references, and domain knowledge
--Define more agents in .context/agents/ for specialized tasks
--Check out the tools page for automated setup options