supafly 0.1.0

Portable context for AI coding agents. Write once in .supafly/, sync to Claude Code, Codex, Cursor, and more.

Supafly

Portable context for AI agents. BYOM = Bring Your Own Memory.

Write your project context once in .supafly/. Supafly compiles it into the native format for every AI coding tool.

.supafly/                        canonical source
    |
    v
supafly sync
    |
    +--> CLAUDE.md               Claude Code
    +--> .claude/rules/*.md      Claude Code (scoped)
    +--> AGENTS.md               Codex
    +--> .cursor/rules/*.mdc     Cursor
    +--> .windsurf/rules/*.md    Windsurf (planned)
    +--> .github/copilot-instructions.md  Copilot (planned)

Install

pip install -e .

Quick Start

supafly init                   # creates .supafly/ with starter templates
supafly sync                   # renders target files from .supafly/
supafly diff                   # preview what would change
supafly validate               # lint config and frontmatter
supafly sync --check           # exit non-zero if outputs are stale (for CI)
supafly init --hook            # install a git pre-commit hook

Run Locally (dev)

PYTHONPATH=src python3 -m supafly

---

Top 10 Practical Examples

1. New Developer Onboarding — Zero Config

You join a team. Clone the repo. Open Claude Code, Cursor, or Codex. Context is already there — no one has to explain "read the wiki" or "check the CLAUDE.md".

git clone repo
cd repo
# .supafly/ already synced -> CLAUDE.md, AGENTS.md, .cursor/rules/ all present
# Every AI tool knows the stack, conventions, and current priorities on first prompt

2. Multi-Tool Team — One Source of Truth

Your team has 3 devs on Cursor, 2 on Claude Code, 1 on Codex. Instead of maintaining 3 separate instruction files that drift apart, everyone edits .supafly/:

.supafly/project.md      <- "We use Next.js 14, pnpm, Postgres"
.supafly/rule-testing.md  <- "Always use vitest, no jest"

supafly sync ->
  CLAUDE.md              (claude dev sees the rules)
  AGENTS.md              (codex dev sees the rules)
  .cursor/rules/*.mdc    (cursor devs see the rules)

One edit, all tools updated.

3. Feature Freeze Announcement

Product says "freeze all non-critical work until release". You add one file and every agent on the team knows:

# .supafly/current-focus.md
---
kind: instruction
title: Current Focus
priority: high
targets:
  - claude
  - codex
  - cursor
---
FEATURE FREEZE until April 18. Bug fixes only.
Do not introduce new dependencies or refactor existing code.

supafly sync — now every AI tool on the team refuses to build new features.

4. Scoped Rules for Monorepos

Frontend and backend live in the same repo but have different conventions. Use scopes so each agent only gets relevant rules in context:

# .supafly/rule-frontend.md
---
kind: instruction
title: Frontend Rules
scopes:
  - "src/web/**/*.tsx"
targets:
  - claude
  - cursor
---
Use functional components. Tailwind only. No CSS modules.

# .supafly/rule-backend.md
---
kind: instruction
title: Backend Rules
scopes:
  - "src/api/**/*.py"
targets:
  - claude
  - codex
---
Use FastAPI. All endpoints need OpenAPI docstrings. No ORM — raw SQL only.

Claude Code gets scoped .claude/rules/rule-frontend.md and .claude/rules/rule-backend.md. Cursor gets .cursor/rules/rule-frontend.mdc with globs: ["src/web/**/*.tsx"].

5. CI Gate — Stale Context Detection

Add a CI check so PRs can't merge if someone edited .supafly/ but forgot to run sync:

# .github/workflows/supafly.yml
- name: Check context is current
  run: supafly sync --check

Or locally via the pre-commit hook:

supafly init --hook
# Now every commit runs supafly sync --check
# Fails if generated files are out of date

6. Architecture Decision Records

Your team decides to migrate from REST to GraphQL. Record it so every agent respects the decision going forward:

# .supafly/decision-graphql-migration.md
---
kind: decision
title: GraphQL Migration
description: Moving public API from REST to GraphQL
priority: high
targets:
  - claude
  - codex
  - cursor
---
As of April 2026, all new public endpoints must use GraphQL.
Existing REST endpoints remain until client migration is complete.
Do not add new REST routes under /api/v2/.

Every agent now knows the boundary — no one accidentally scaffolds a new REST endpoint.

7. Switching AI Tools Without Losing Context

You've been using Cursor for 6 months with detailed .cursorrules. Now you want to try Claude Code. Without Supafly, you'd manually rewrite everything into CLAUDE.md. With Supafly:

supafly import cursor          # pulls .cursorrules into .supafly/
supafly sync                   # generates CLAUDE.md from the same source
# Now both tools have identical context

8. Per-Developer Local Notes

You have personal shortcuts, environment quirks, or scratch context that shouldn't be shared. Use .supafly/local/:

# .supafly/local/identity.md
---
kind: note
title: My Setup
priority: low
---
I run on M4 Max. My local Postgres is on port 5433 not 5432.
When I say "run tests" I mean the fast suite, not the integration tests.

This stays gitignored but still renders into your local agent context.

9. Open Source Project — Contributor Agent Guidance

You maintain an open source library. Contributors use different AI tools. Add .supafly/ to your repo and every contributor's agent immediately knows:

# .supafly/rule-general.md
---
kind: instruction
title: Contribution Rules
priority: high
targets:
  - claude
  - codex
  - cursor
---
- All PRs need tests
- Use conventional commits (feat:, fix:, docs:)
- No breaking changes without an RFC
- Run `make lint` before submitting
- Target Python 3.11+

No more PRs where the AI ignored your test requirements because the contributor didn't set up their tool.

10. Handoff Notes Between Sessions

You're halfway through a refactor and need to pick it up tomorrow. Leave a breadcrumb:

# .supafly/session-handoff.md
---
kind: session
title: Auth Refactor Handoff
description: State of the auth middleware rewrite
priority: high
targets:
  - claude
  - codex
---
## What's done
- Extracted token validation into auth/validator.py
- All routes in /api/admin/* use the new middleware

## What's left
- /api/public/* still uses the old middleware
- Tests in test_auth.py need updating for the new response format
- Do NOT touch auth/legacy.py — it's load-bearing until public routes migrate

Next session, your agent starts with full context on where you left off.

---

The Common Thread

Supafly turns "agent context" from a per-tool, per-person artifact into a shared, version-controlled, portable project resource. Write it once in .supafly/, and every tool on every machine gets it.

---

Current Status

• Renderers: Claude Code, Codex, Cursor
• CLI: init, sync, diff, validate, sync --check, init --hook
• TUI: Textual app shell with workspace inspection