Getting Started

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

Fastest way to start

Generate your SurfContext starter kit

Fill in your project details and download a ready-to-use SurfContext package.

Project name

What is your project about?

Tech stack (optional)

Generates CONTEXT.md, CLAUDE.md, AGENTS.md, surfcontext.json, and .context/ directory

After downloading:

Unzip into your project root
Edit CONTEXT.md with your full project details
Open your project in any supported AI coding agent — it discovers your context automatically

Or set up manually

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, knowledge docs, and guides.

Terminal

mkdir -p .context/agents .context/docs .context/guides

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": "3.0",
  "source": "manual",
  "platforms": ["claude", "codex", "cursor"],
  "canonical": {
    "rootContext": "CONTEXT.md",
    "docsDir": ".context/docs",
    "agentsDir": ".context/agents",
    "guidesDir": ".context/guides"
  },
  "generation": {
    "claude": {
      "rootContext": "CLAUDE.md",
      "method": "sed-copy"
    },
    "codex": {
      "rootContext": "AGENTS.md",
      "method": "sed-copy"
    }
  },
  "discoveryOrder": [
    "CONTEXT.md",
    "surfcontext.json",
    ".context/docs/",
    ".context/guides/",
    ".context/agents/",
    "plans/"
  ]
}

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 any supported AI coding agent. It 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 + discovery order
  .context/
    agents/
      code-reviewer.md    # Your agent definition
    docs/                 # Evergreen knowledge docs
    guides/               # Living how-to documents
  CLAUDE.md               # Platform-specific (generated)
  AGENTS.md               # Platform-specific (generated)

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
→ Add living guides to .context/guides/ for implementation how-tos with gotcha callouts (new in v3)
→ Check out the tools page for automated setup options