Asana Plugin for OpenCode

A comprehensive Asana integration plugin for OpenCode that enables full task and project management capabilities through natural language commands.

Core APIs Used

• Asana REST API v1.0 - Primary API for all Asana operations
• Authentication: Personal Access Token (PAT) authentication
• Base URL: https://app.asana.com/api/1.0

Setup Instructions

1. Generate Asana Personal Access Token

Step-by-step instructions:

1. Log in to Asana

   • Go to https://app.asana.com
   • Sign in with your Asana account

2. Access Developer Settings

   • Click your profile picture in the top right corner
   • Select "My Apps" from the dropdown menu
   • Or navigate directly to: https://app.asana.com/0/my-apps

3. Create Personal Access Token

   • Click the "+ New personal access token" button
   • Enter a descriptive name (e.g., "OpenCode Integration")
   • Click "Create"
   • Important: Copy the token immediately - you won't be able to see it again

4. Set Environment Variable

   # For Unix/macOS/Linux
   export ASANA_ACCESS_TOKEN="your-token-here"
      
   # For Windows (PowerShell)
   $env:ASANA_ACCESS_TOKEN="your-token-here"
      
   # For Windows (Command Prompt)
   set ASANA_ACCESS_TOKEN=your-token-here

5. Permanent Setup Add the environment variable to your shell profile (~/.bashrc, ~/.zshrc, etc.) or create a .env file:

   ASANA_ACCESS_TOKEN=your-token-here

2. Required Permissions

The Personal Access Token needs these permissions:

• View tasks, projects, and workspaces
• Create and edit tasks
• Add comments and attachments
• Manage projects and sections
• Read user information

Note: Personal Access Tokens inherit the permissions of the user who created them.

3. Test Connection

After setting up the token, test the connection:

opencode run "Test Asana connection and return user details"

Key Concepts

GIDs (Global IDs)

Asana uses GIDs (Global IDs) as unique identifiers for all resources:

• Workspaces have GIDs
• Projects have GIDs
• Tasks have GIDs
• Users have GIDs
• Sections (columns) have GIDs

How to find GIDs:

• Look at the URL when viewing items in Asana web app
• Use the list/get tools to retrieve them programmatically

Workspaces vs Projects

• Workspace: Top-level organization (company/team)
• Project: Container for tasks within a workspace
• Section: Columns within projects (for board view)

Available Commands

Connection & Discovery

• asana-test-connection - Test API connection and get user info
• asana-get-workspaces - List all accessible workspaces
• asana-get-projects - List projects in a workspace
• asana-get-users - Get users in a workspace

Project Management

• asana-get-project - Get project details
• asana-get-project-sections - List project sections/columns
• asana-create-section - Create new section in project

Task Operations

• asana-get-tasks - Get tasks from project
• asana-get-section-tasks - Get tasks from specific section
• asana-get-task - Get detailed task information
• asana-create-task - Create new task
• asana-update-task - Update existing task
• asana-move-task-to-section - Move task between columns
• asana-delete-task - Delete a task

Task Management

• asana-get-subtasks - Get subtasks of a task
• asana-create-subtask - Create subtask
• asana-add-comment - Add comment to task
• asana-get-task-stories - Get task activity/comments

Search & Filtering

• asana-search-tasks - Search tasks in workspace
• asana-get-my-tasks - Get tasks assigned to current user

Tags & Followers

• asana-get-tags - Get tags in workspace
• asana-add-tag-to-task - Add tag to task
• asana-remove-tag-from-task - Remove tag from task
• asana-add-follower-to-task - Add follower to task

Usage Examples

Basic Workflow

# 1. Test connection
opencode run "Test Asana connection and return user details"

# 2. List workspaces
opencode run "List all workspaces accessible to the authenticated user"

# 3. Get projects from workspace
opencode run "List all projects in workspace 123456789"

# 4. Get tasks from project
opencode run "Get tasks from project 987654321"

Task Management

# Create a task
opencode run "Create a new task in project 987654321 with name 'Review documentation' and notes 'Check API documentation for accuracy'"

# Move task to Done section
opencode run "Move task 555555555 to section 777777777"

# Add comment
opencode run "Add comment 'Documentation review completed successfully' to task 555555555"

Search Operations

# Search for specific tasks
opencode run "Search for tasks in workspace 123456789 with text 'urgent'"

# Get my tasks
opencode run "Get tasks assigned to the current user in workspace 123456789"

Environment Variables

Required

• ASANA_ACCESS_TOKEN - Personal Access Token from Asana Developer Console

Optional

No optional environment variables currently supported.

Troubleshooting

Common Issues

1. "Plugin not configured" error

   • Ensure ASANA_ACCESS_TOKEN is set correctly
   • Test the token with: opencode run "Test Asana connection"

2. "Invalid token" error

   • Verify the token wasn't revoked
   • Check for typos in the token
   • Create a new token if needed

3. "Access denied" errors

   • Verify the user has permission to access the requested resources
   • Check if the project/workspace GIDs are correct

4. Rate limiting

   • Asana has rate limits - wait a moment between requests
   • The plugin automatically handles rate limiting with retries

Debugging

Enable debug logging by setting:

export DEBUG=asana-plugin

Finding GIDs

Use these commands to find resource GIDs:

# Get workspace GIDs
opencode run "List all workspaces accessible to the authenticated user"

# Get project GIDs from workspace
opencode run "List all projects in workspace YOUR_WORKSPACE_GID"

# Get section GIDs from project
opencode run "Get all sections in project YOUR_PROJECT_GID"

Security Best Practices

1. Token Security

   • Never commit tokens to version control
   • Use environment variables, not hardcoded values
   • Rotate tokens regularly
   • Use descriptive names for tokens to track usage

2. Permissions

   • Only grant necessary permissions
   • Regularly review token access
   • Delete unused tokens

3. Access Control

   • Use service accounts for integrations when possible
   • Limit token scope to specific workspaces if needed

API Limits

• Rate Limit: Approximately 150 requests per minute
• Pagination: Large datasets are automatically paginated
• Field Selection: Only requested fields are returned to optimize bandwidth

Support

• Asana API Documentation: https://developers.asana.com/docs
• Personal Access Tokens: https://developers.asana.com/docs/personal-access-tokens
• Rate Limits: https://developers.asana.com/docs/rate-limits

Version History

• v1.0.1 - Current version with full Asana API integration
• v1.0.0 - Initial release

Contributing

This plugin follows OpenPets standards. See the OpenPets Development Guide for development guidelines.