linear-agent

name	linear-agent
description	Better Linear for Agent (Belifoa) - Efficiently query, manage, and create Linear issues with minimal token consumption and persistent authentication.

Linear Agent (Belifoa Skill)

Belifoa provides a high-performance, agent-friendly interface for Linear.

Core Capabilities

• Persistent Auth: Uses LINEAR_API_KEY (Personal API Key) or ~/.config/belifoa/config.json.
• 70%+ Token Footprint Savings: Formatted Markdown tables/cards instead of massive, raw GraphQL API JSON objects.
• Smart Zero-Config Repo, Team & Submodule Resolution: Auto-detects matching workspace profile and team key from Git remote URL, .belifoarc.json, or .mcp.json traversing parent and submodule directory trees.
• Single-MCP Multi-Workspace: One MCP server instance exposes 8 unprefixed belifoa_* tools; target any saved workspace per call with the optional profileName argument (defaults to active profile). No need to pin one MCP instance per workspace.
• Explicit Active Profile Banner: Prints a 1-line context header ([belifoa] Active Profile: myrehat (Workspace: MyRehat, Default Team: MYR)) on CLI & MCP outputs for immediate visual confirmation.
• Standardized CLI Flags: Consistent -p/--profile, -w/--workspace, and -t/--team across all CLI subcommands (list, issue list, my-issues, search, create, update, close).
• Git Branch Helper: Generate and checkout standard Linear branch names (belifoa branch ENG-123 -b or --checkout).
• Idempotency & Duplicate Prevention: Avoid duplicate issues with --check-existing / --idempotent in creation & import commands or checkExisting parameter in MCP tools.
• Hierarchy & Relations: Support for parentId, blockedBy, and blocks dependencies in issue CRUD and MCP tools.
• Batch Issue Operations: Create multiple issues in a single API roundtrip via belifoa_manage_issue({ action: "bulk_create", issues: [...] }).
• Self-Correcting LLM Errors: Structured JSON errors returning valid availableTeams, availableStates, availableUsers, and availableProfiles on invalid inputs so agents self-correct in 1 turn.
• Relevance-Ranked Search: Search results are re-ranked by title/description/label/comment token overlap (not raw Linear ordering). Every row shows a Match column (t: title, d: description, l: labels, c: comments) so you can judge why each issue matched. Zero-overlap noise rows are dropped when real matches exist.
• Comment-Aware Search: Issue comments are indexed for scoring, so issues discussed in comments surface in search even when the title/description don't contain the query.
• Cursor Pagination: search / list / my-issues accept -a, --after <cursor>; results print a next-page cursor when more rows exist (MCP: after param). Compact JSON wraps as {count, hasNextPage, endCursor, issues} when more pages exist.

Usage Modes

1. Direct CLI Execution (Zero MCP Overhead)

Agents can execute CLI commands directly in terminal using bun x github:ImBIOS/belifoa#canary:

# List my assigned issues
bun x github:ImBIOS/belifoa#canary my-issues

# Search issues (relevance-ranked, Match column shows where tokens hit; add --after for next page)
bun x github:ImBIOS/belifoa#canary search "login bug" --team ENG

# Get detailed issue view
bun x github:ImBIOS/belifoa#canary issue ENG-123

# Get git branch name slug or checkout branch
bun x github:ImBIOS/belifoa#canary branch ENG-123 -b

# Create an issue (with hierarchy, relations, and duplicate prevention)
bun x github:ImBIOS/belifoa#canary create --team ENG --title "Fix race condition in auth" --priority 1 --parent ENG-100 --blocked-by ENG-99 --check-existing

# Update an existing issue
bun x github:ImBIOS/belifoa#canary update ENG-123 --state "In Progress" --assignee me -c "Started working on fix"

# Close or resolve an issue
bun x github:ImBIOS/belifoa#canary close ENG-123 -c "Fixed in PR #42"

# List workspace labels
bun x github:ImBIOS/belifoa#canary labels

2. Streamlined MCP Tools

When MCP is connected via bun x github:ImBIOS/belifoa#canary mcp (or ... mcp --profile <name> to pin a launch profile), one server exposes 8 tools targeting any workspace via the optional profileName argument (defaults to active profile):

• belifoa_auth_status({ profileName: "myrehat" }) — active + all saved profiles, org, viewer
• belifoa_auth_switch({ profileName: "playzuzu" }) — activate profile or default team
• belifoa_set_api_key({ apiKey: "lin_api_...", profileName: "playzuzu" }) — save new profile key
• belifoa_get_issue({ id: "ENG-123", format: "markdown" })
• belifoa_search_issues({ query: "auth bug", teamKey: "ENG" }) — re-ranked; rows show Match (t:/d:/l:/c:); pass after from endCursor to page
• belifoa_get_my_issues({ after: "..." }) — cursor pagination supported
• belifoa_manage_issue({ action: "create", title: "Subtask fix", parentId: "ENG-100", blockedBy: ["ENG-99"] })
• belifoa_manage_issue({ action: "comment", issueId: "ENG-123", commentBody: "..." })
• belifoa_manage_issue({ action: "update", issueId: "ENG-123", state: "In Progress" })
• belifoa_manage_issue({ action: "close", issueId: "ENG-123", commentBody: "Fixed in PR #42" })
• belifoa_manage_issue({ action: "delete_comment", commentId: "..." }) — permanently delete a comment (id from belifoa_get_issue comments)
• belifoa_manage_issue({ action: "archive_comment", commentId: "..." }) — soft-delete, keeps history
• belifoa_manage_issue({ action: "bulk_create", issues: [{ title: "Task 1" }, { title: "Task 2" }] })
• belifoa_get_workspace() — teams, projects, and labels in one call