Metadata-Version: 2.4
Name: supafly
Version: 0.1.0
Summary: Portable context for AI coding agents. Write once in .supafly/, sync to Claude Code, Codex, Cursor, and more.
Author: aaftabskillgigs
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/aaftabskillgigs/supafly
Project-URL: Repository, https://github.com/aaftabskillgigs/supafly
Project-URL: Issues, https://github.com/aaftabskillgigs/supafly/issues
Keywords: ai,agents,context,claude,cursor,codex,copilot,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.61.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 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.

```text
.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

```bash
pip install -e .
```

## Quick Start

```bash
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)

```bash
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:

```yaml
# .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:

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

```yaml
# .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:

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

Or locally via the pre-commit hook:

```bash
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:

```yaml
# .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:

```bash
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/`:

```yaml
# .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:

```yaml
# .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:

```yaml
# .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
