Belifoa ("Better Linear for Agent") is an agent-first Linear client and Model Context Protocol (MCP) server engineered to solve short authentication expirations, heavy GraphQL payload token bloat, and tool selection sprawl when AI agents interact with Linear.
- 🌟 Why Belifoa?
- ✨ Key Features
- 📊 Objective Benchmarking Results
- 🚀 Quick Start & CLI Usage
- 🛠️ MCP Server Integration
- 🛡️ Profile Resolution & Agent Isolation
- 🧩 Skills, Plugins & Git Hooks
- 🧪 Testing & Benchmarks
- 📄 License
Standard Linear integrations for LLM agents suffer from three major inefficiencies:
- Short-Lived Auth Sessions: Standard OAuth integrations expire frequently, breaking long-running autonomous AI agent loops.
- Heavy Payload Token Bloat: Raw Linear GraphQL API responses contain thousands of tokens of unnecessary metadata (
__typename, nested node arrays, hex colors, avatar URLs) that consume agent context windows. - Tool Sprawl & Multi-Turn Overhead: 30+ fine-grained tools confuse LLM tool-calling logic and increase multi-turn latency.
Belifoa eliminates these bottlenecks:
- Persistent Personal API Key Auth: Uses Linear Personal API Keys (
lin_api_...) that stay valid continuously unless revoked. - 70–80% Prompt Token Reduction: Formats Linear data into clean, compact CLI tables, Markdown cards, or minified JSON optimized for token efficiency.
- Unified Multimodal Access: One core tool usable via CLI, MCP Server, Antigravity Skill, Plugin, and Git Hooks.
- ⚡ Token-Efficient Context Formatting: CLI defaults to ANSI-styled
cli_table, while MCP tools default to lightweightmarkdownandcompact_jsonto maximize token budget. - 🔐 Multi-Profile & Workspace Isolation: Manage multiple Linear accounts and team profiles seamlessly without cross-project state leakage.
- 🏷️ Single-MCP Multi-Workspace Isolation: One MCP server instance exposes 8 unprefixed
belifoa_*tools; any saved workspace is targeted per call via the optionalprofileNameargument (defaults to the active profile). No pinning one MCP instance per workspace. - 📂 Automatic Ancestor & Submodule Resolution: Automatically traverses parent/child directories to auto-detect project configuration from
.belifoarc.json,.belifoa, or.mcp.jsonin submodules. - 💬 Explicit Active Profile Banner: Displays a 1-line context header (
[belifoa] Active Profile: myrehat (Workspace: MyRehat, Default Team: MYR)) on CLI and MCP outputs for instant target workspace verification. - 🎛️ Standardized CLI Flags: Uniform
-p/--profile,-w/--workspace, and-t/--teamflag support across all subcommands (list,issue list,my-issues,search,create,update,close). - 🔗 First-Class Hierarchy & Relations: Easily link
parentId,blockedBy, andblocksdependencies in issue CRUD and MCP tool calls. - 🌿 Git Branch Helper Output: Get ready-to-use Linear git branch slugs (
belifoa branch ENG-123) and checkout branches directly (--checkout). - 📦 MCP Bulk Issue Creation: Batch create multiple backlog items in a single API roundtrip via
belifoa_manage_issue({ action: "bulk_create" }). - 🔄 Self-Correcting Error Payloads for LLMs: Returns structured JSON errors with valid suggestions (
availableTeams,availableStates,availableUsers,availableProfiles) on invalid parameters so AI agents self-correct in 1 turn. - 🚀 Zero-Installation Direct Execution: Run instantly using
bun x github:ImBIOS/belifoa#canaryorpnpm add github:ImBIOS/belifoa.
Belifoa includes an automated benchmarking suite to measure payload optimization performance:
| Scenario | Paradigm / Format | Payload Size | Est. Tokens | Context Savings (%) |
|---|---|---|---|---|
| Issue Search | Official Raw Linear MCP (JSON) | 6,437 B | ~1,694 | 0% (Baseline) |
| Belifoa Compact JSON | 562 B | ~147 | 91% | |
| Belifoa Markdown Table | 764 B | ~200 | 88% | |
| Issue Detail | Official Raw Linear MCP (JSON) | 3,369 B | ~887 | 0% (Baseline) |
| Belifoa Compact JSON | 1,317 B | ~347 | 61% | |
| Belifoa Markdown Card | 1,279 B | ~337 | 62% |
(For full benchmark methodology, see BENCHMARK_RESULTS.md)
You can execute Belifoa directly from GitHub without publishing to npm:
# Set long-lived Linear API key
bun x github:ImBIOS/belifoa#canary auth set <lin_api_...>
# Check authentication status
bun x github:ImBIOS/belifoa#canary auth status
# List issues assigned to you
bun x github:ImBIOS/belifoa#canary my-issues
# Search issues by query and team (relevance-ranked: rows show a Match column with t:/d:/l:/c: token hits; comments are indexed)
bun x github:ImBIOS/belifoa#canary search "auth bug" --team ENG
# Fetch the next page of results (cursor printed in the result footer)
bun x github:ImBIOS/belifoa#canary search "auth bug" --team ENG --after <cursor>
# Inspect issue details
bun x github:ImBIOS/belifoa#canary issue ENG-123
# Create issue with full metadata fields
bun x github:ImBIOS/belifoa#canary create --team ENG \
--title "Implement Token Cache" \
--description "Optimize context payload retention" \
--priority 1 \
--assignee "jane@example.com" \
--project "Q3 Security" \
--estimate 5 \
--due-date "2026-08-15" \
--labels "backend,security" \
--state "In Progress"
# Update an existing issue and add a comment
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"
# Delete / archive a comment by ID (id is shown in `issue` comment output)
bun x github:ImBIOS/belifoa#canary comment delete <comment-id>
bun x github:ImBIOS/belifoa#canary comment archive <comment-id>
# List active team labels
bun x github:ImBIOS/belifoa#canary labels
# Bulk import issues from JSON file
bun x github:ImBIOS/belifoa#canary import --file tasks.json --team ENGTo make belifoa available globally in your PATH:
# Clone repository and link globally:
pnpm link --global # or bun link
# Verify global binary:
belifoa --version
belifoa my-issuesBelifoa runs natively as a Model Context Protocol (MCP) server for AI code editors and autonomous agent frameworks like Cursor, Antigravity, OpenCode, and Claude Desktop.
{
"mcpServers": {
"belifoa": {
"command": "bun",
"args": ["x", "github:ImBIOS/belifoa#canary", "mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}The server exposes one unprefixed tool set (
belifoa_get_issue,belifoa_manage_issue, …); passprofileNamein any tool call to target another saved workspace, or pin the launch profile withmcp --profile <name>/BELIFOA_PROFILE.
To support concurrent AI agents operating across multiple projects and teams without profile conflicts, Belifoa enforces a strict precedence hierarchy when resolving workspace credentials:
- CLI / MCP Parameter:
--profile <name>flag orprofileNametool argument. - Environment Variable:
BELIFOA_PROFILEenvironment variable. - Project-Local Config:
.belifoarc.jsonor.belifoafile in current working directory tree (process.cwd()). - Global Config Fallback:
activeProfiledefined in~/.config/belifoa/config.json.
- Antigravity Skill: Integrate
skills/linear-agent/SKILL.mddirectly into your AI agent's skill directory for autonomous issue lookup and updates. - Git Commit Hooks: Automate issue linking and status sync on git commits and branch pushes.
Run unit tests and verification builds locally:
# Run unit tests
pnpm test
# Run build verification
pnpm run build
# Run benchmark suite
pnpm run benchmarklinear • linear-api • mcp • mcp-server • model-context-protocol • ai-agent • agentic-ai • antigravity • token-optimization • context-window • cli • bun • typescript • linear-agent • developer-tools
MIT © ImBIOS