Getting Started

Welcome to BeTheTamer. Tame your code chaos by managing projects directly inside your source files.

Installation

Install via the Visual Studio Code Marketplace or by searching "BeTheTamer" in the Extensions view (Ctrl+Shift+X).

Try the Demo Project

Want to see it in action without messing up your own code? We've included a demo!

1. Clone/Download this extension.
2. Open the demo folder in VS Code.
3. Open the BeTheTamer view in the Activity Bar.
4. You'll see a pre-populated board with tickets from Backend, Frontend, and Docs!

Your First Ticket

To create a ticket, simply write a comment in any file:

// @ticket Fix login bug
//   @id: T4787
//   @status: doing
//   @priority: high
// @end

Ticket Syntax

BeTheTamer uses a flexible comment-based syntax. Start with @ticket and end with @end.

Work Item Types

Properties

These properties apply to both Tickets and Epics.

Commands

Access these via the Command Palette (Cmd+Shift+P):

• BeTheTamer: Generate Board - View all tickets in a visual Kanban board. Supports Interactive Drag & Drop.
• BeTheTamer: Create Ticket - UI helper to insert a ticket snippet.
• BeTheTamer: Generate Project Map - Generate a Markdown-based map of your project's context, checkpoints, and tickets.
• BeTheTamer: Import TODOs - Scan your workspace for TODO/FIXME comments and convert them into tickets.
• BeTheTamer: Export Context - Generate a minified JSON for AI agents.
• BeTheTamer: Generate Agent Rules - Create a rule file for Cursor/Windsurf.

CLI Usage (Universal)

Run bethetamer help in your terminal to see all options. The CLI works in any environment (IntelliJ, Neovim, CI/CD).

• bethetamer list [--status <status>] - List tickets (optional filter).
• bethetamer read <ID> - View detailed ticket info.
• bethetamer check - Validate ticket syntax and IDs (Great for CI/CD gates).
• bethetamer export-board [--format md|html] - Generate a standalone board.
• bethetamer init [--rules|--ignore] - Generate configuration files.
• bethetamer activate <KEY> - Activate your Pro license globally.
• bethetamer export - (Pro) Generate AI context JSON.

Configuration

BeTheTamer is configured using standard Visual Studio Code settings. You can manage these globally or per-project.

Settings File

To configure per specific project, create a .vscode/settings.json file in your root

Basic Syntax

Start a ticket with @ticket or @epic.

// @ticket Refactor login flow
//   @status: todo
// @end

// @epic User Authentication
//   @status: doing
// @end

Available Options

Icon Style Preview

• Minimal: Native monochrome icons (Clean)
• Colorful: Emojis only (🔥, 🚀)
• Mixed: Native icons + Emojis (Best visibility)

Board Customization

Want your brand colors? Set theme to customized:

{
    "bethetamer.boardTheme": "custom",
    "bethetamer.customBackground": "linear-gradient(90deg, #FF9A9E 0%, #FECFEF 99%, #FECFEF 100%)"
}

Ignore Patterns

To exclude files or directories (like node_modules), create a .bethetamerignore file in your project root. It uses standard glob syntax:

**/node_modules/**
**/dist/**
src/tests/fixtures/**

AI Mastery & Cost Savings

BeTheTamer isn't just a management tool; it's an AI optimization layer. By structuring your tasks, you help AI agents understand your project effectively.

Cost Savings

Standard AI workflows read entire files to understand context, wasting tokens. BeTheTamer generates a compact map (JSON) of your active tickets.

Agent Rules

Run BeTheTamer: Generate Agent Rules to create a .cursor/rules/be_the_tamer.mdc file. This teaches your AI agent:

• How to find tickets (@ticket)
• How to log progress (@log)
• How to manage state transitions (@status)

Views & History

Ticket Explorer

Access the BeTheTamer icon in the Activity Bar to see a tree view of all tickets, grouped by status.

• Click a ticket to jump to the code.
• Hover to see details like priority and assignee.

History Tracking

Use the @log field to create a permanent history of work directly in the ticket. This creates a timeline that both humans and AI can review.

// @ticket Implement Authentication
//   @id: Te5bf
//   @status: done
//   @log: Created login form UI
//   @log: Integrated Firebase Auth
//   @log: Fixed mobile responsive layout
// @end

AI Assistance Prompt

To integrate BeTheTamer with your favorite AI coding assistant, use this system instruction.

You are an intelligent project manager integrated into the codebase.
Before creating any code or tasks, PLEASE READ the project rules located at:
- Your Agent Rules file (e.g., `.cursor/rules/be_the_tamer.mdc` or `AGENT_RULES.md`)

These files contain the strict syntax for creating tickets (@ticket) and managing checkpoints. 
Follow them precisely.

CI/CD & Commit Hooks

Ensure no broken tickets enter your codebase by adding bethetamer check to your pipeline.

# Example: .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx bethetamer check --status todo,doing

This command exits with an error code if it finds invalid tickets (missing IDs, duplicate IDs) or tickets in specific statuses if filtered.

Troubleshooting

Tickets Not Appearing?

• Check File Type: Ensure your file extension is supported (js, ts, py, java, etc.).
• Check Ignore Patterns: Verify the file isn't excluded by .bethetamerignore.
• Refresh: Click the Refresh icon in the BeTheTamer view.

Extension Not Activating?

• VS Code Version: Ensure you are on VS Code 1.85.0 or higher.
• Reload Window: Run Developer: Reload Window in the command palette.

Performance Issues?

For large monorepos (10k+ files), use the .bethetamerignore file to exclude heavy directories like node_modules, dist, or coverage.

Feedback & Support

found a bug? Have a feature idea? We'd love to hear from you!

In-Editor Reporting

You can send feedback directly from VS Code without leaving your editor:

1. Open Command Palette (Cmd+Shift+P).
2. Run BeTheTamer: Send Feedback / Report Issue.
3. This will open our GitHub Issues page with a pre-filled template.