pi-linear-tools

pi-linear-tools is a Pi extension for the Pi coding agent that lets you manage Linear issues, projects, and milestones via LLM tools and CLI commands.

Install

As a pi package (recommended)

pi install npm:@fink-andreas/pi-linear-tools

As an npm package

npm install -g @fink-andreas/pi-linear-tools

Use pi-linear-tools as a CLI tool.

Initial configuration

After installation, run /linear-tools-config in pi.

When used without parameters, it starts the interactive setup flow and guides you through:

• authentication (API key)
• workspace selection
• default team selection

/linear-tools-config

Optional non-interactive commands:

/linear-tools-config --api-key lin_xxx
/linear-tools-config --default-team ENG
/linear-tools-config --team ENG --project "My Project"

Extension commands

• /linear-tools-config
• /linear-tools-help

LLM-callable tools

linear_issue

Actions: list, view, create, update, comment, start, delete

linear_project

Actions: list

linear_milestone

Actions: list, view, create, update, delete

CLI usage

If installed globally via npm install -g @fink-andreas/pi-linear-tools, CLI command pi-linear-tools is available:

pi-linear-tools --help
pi-linear-tools config
pi-linear-tools config --api-key lin_xxx
pi-linear-tools config --default-team ENG
pi-linear-tools config --team ENG --project "My Project"

Issue commands

# List issues
pi-linear-tools issue list --project "My Project"
pi-linear-tools issue list --project "My Project" --states "In Progress,Backlog"
pi-linear-tools issue list --project "My Project" --assignee me

# View issue details
pi-linear-tools issue view ENG-123
pi-linear-tools issue view ENG-123 --no-comments

# Create issue
pi-linear-tools issue create --title "Fix login bug" --team ENG
pi-linear-tools issue create --title "New feature" --team ENG --project "My Project" --priority 2 --assignee me

# Update issue
pi-linear-tools issue update ENG-123 --state "In Progress"
pi-linear-tools issue update ENG-123 --title "Updated title" --assignee me
pi-linear-tools issue update ENG-123 --milestone "Sprint 1"

# Comment on issue
pi-linear-tools issue comment ENG-123 --body "This is fixed in PR #456"

# Start working on issue (creates branch, sets state to In Progress)
pi-linear-tools issue start ENG-123
pi-linear-tools issue start ENG-123 --branch custom-branch-name

# Delete issue
pi-linear-tools issue delete ENG-123

Project commands

pi-linear-tools project list

Team commands

pi-linear-tools team list

Milestone commands

# List milestones
pi-linear-tools milestone list --project "My Project"

# View milestone details
pi-linear-tools milestone view <milestone-id>

# Create milestone
pi-linear-tools milestone create --project "My Project" --name "v1.0 Release"
pi-linear-tools milestone create --project "My Project" --name "Sprint 1" --target-date 2024-12-31 --status planned

# Update milestone
pi-linear-tools milestone update <milestone-id> --status inProgress

# Delete milestone
pi-linear-tools milestone delete <milestone-id>

Configuration storage

Settings path:

~/.pi/agent/extensions/pi-linear-tools/settings.json

Environment fallback:

• LINEAR_API_KEY (takes precedence over settings)

Debug/diagnostics environment flags:

• PI_LINEAR_TOOLS_USAGE_SUMMARY=true — append per-command Linear API usage summary to tool output markdown and include details.apiUsage
• LOG_LEVEL=debug — enable detailed file logging
• PI_LINEAR_TOOLS_LOG_TO_CONSOLE=true — mirror logs to console (normally file-first logging)
• PI_LINEAR_TOOLS_LOG_FILE=/custom/path.log — override log file path

Development

npm install
npm test
npm run release:check
node index.js --help

Local extension debug flow (unpublished code)

Use project-local extension loading with a generated wrapper file:

npm run dev:sync-local-extension

Then in pi:

/reload

If install/remove sources changed, restart pi before validating.

Release checklist: see RELEASE.md. Post-release verification checklist: see POST_RELEASE_CHECKLIST.md.