BTW (Bring The Workflow)

AI-aware workflow package manager for developers

BTW lets you share and manage AI coding workflows across different tools (Claude, Cursor, Windsurf, Copilot) without vendor lock-in. Package your AI instructions, rules, and configurations in GitHub repositories and inject them into any project with a single command.

Why BTW?

• No Vendor Lock-in: Your workflows are plain YAML and markdown in Git repos
• Tool Agnostic: One workflow, multiple AI tools (Claude, Cursor, Windsurf, Copilot)
• Shareable: Share workflows via GitHub - just btw add user/repo
• Version Controlled: Track changes, roll back, collaborate on AI instructions
• Zero Config in Projects: Keep AI config out of your project repos

Installation

npm install -g @sanarberkebayram/btw

Requirements:

• Node.js 18.0.0 or higher
• Git

Quick Start

# Add a workflow from GitHub
btw add sanarberkebayram/game-agent

# List installed workflows
btw list

# Inject into your project (for Claude)
btw inject game-agent

# Remove when done
btw remove game-agent

Commands

| Command | Description | |---------|-------------| | btw add <source> | Install a workflow from GitHub or local path | | btw list | List installed workflows | | btw inject <id> | Inject workflow into current project | | btw inject -i | Interactive mode - toggle inject/remove workflows | | btw update [id] | Update workflow(s) from source | | btw remove <id> | Remove an installed workflow | | btw uninstall | Uninstall BTW and remove all workflows |

Examples

# Add from GitHub (shorthand)
btw add user/repo

# Add from GitHub (full URL)
btw add https://github.com/user/repo

# Add from local directory
btw add ./my-workflow

# List with details
btw list --detailed

# Inject for specific AI tool
btw inject my-workflow --target cursor

# Interactive mode - browse and toggle workflows
btw inject --interactive

# Update a workflow from its source
btw update my-workflow

# Update all workflows
btw update --all

# Force overwrite existing config
btw inject my-workflow --force

Creating a Workflow

Create a btw.yaml in your repository with agents referencing external files:

version: "1.0"
id: my-workflow
name: My Workflow
description: A helpful AI workflow
author: your-name

targets:
  - claude
  - cursor

agents:
  - id: main-agent
    name: Main Agent
    description: Primary agent for this workflow
    file: agents/main-agent.md  # Path relative to btw.yaml
    tags:
      - general

Then create the agent file at agents/main-agent.md:

You are an expert assistant specialized in...

Your responsibilities:
1. Help with task A
2. Provide guidance on B
3. Review and improve C

Push to GitHub and share:

btw add your-username/your-workflow

Note: You can also use inline system_prompt instead of file for simple agents.

Supported AI Tools

| Tool | Status | Config Location | |------|--------|-----------------| | Claude | Supported | .claude/instructions.md | | Cursor | Planned | .cursorrules | | Windsurf | Planned | .windsurfrules | | Copilot | Planned | .github/copilot-instructions.md |

Documentation

• Getting Started - Installation and first steps
• Commands Reference - Complete CLI documentation
• Manifest Reference - Full btw.yaml specification
• Creating Workflows - Build and publish workflows

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  GitHub Repo    │────▶│      BTW        │────▶│  Your Project   │
│  (btw.yaml)     │     │  (CLI Manager)  │     │  (.claude/...)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

1. Add: BTW clones the workflow repo to ~/.btw/workflows/
2. Inject: BTW reads the manifest and writes config to your project
3. Use: Your AI tool picks up the injected configuration
4. Update: Pull latest changes with btw add --force

Directory Structure

BTW stores data in ~/.btw/:

~/.btw/
├── workflows/           # Installed workflows
│   └── owner/repo/
│       └── btw.yaml
├── cache/              # Temporary files
└── state.json          # Installation state

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BTW_HOME | BTW home directory | ~/.btw | | BTW_DEBUG | Enable debug output | false | | BTW_NO_COLOR | Disable colors | false | | BTW_DEFAULT_TARGET | Default AI target | claude |

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

# Clone the repo
git clone https://github.com/sanarberkebayram/btw.git
cd btw

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Link for local development
npm link

License

MIT

Author

sanarberkebayram