Asana plugin for OpenCode - manage tasks, projects, and boards with full CRUD operations
A comprehensive Asana integration plugin for OpenCode that enables full task and project management capabilities through natural language commands.
- 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
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
``bash`
# 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:`
env`
ASANA_ACCESS_TOKEN=your-token-here
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.
After setting up the token, test the connection:
`bash`
opencode run "Test Asana connection and return user details"
How to find GIDs:
- Look at the URL when viewing items in Asana web app
- Use the list/get tools to retrieve them programmatically
- 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$3
- asana-get-project - Get project details
- asana-get-project-sections - List project sections/columns
- asana-create-section - Create new section in project$3
- 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$3
- 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$3
- asana-search-tasks - Search tasks in workspace
- asana-get-my-tasks - Get tasks assigned to current user$3
- 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 taskUsage Examples
$3
`bash
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"
`$3
bash
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"
`$3
bash
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
$3
- - Personal Access Token from Asana Developer Console$3
No optional environment variables currently supported.Troubleshooting
$3
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
$3
Enable debug logging by setting:
bash
export DEBUG=asana-plugin
`$3
Use these commands to find resource GIDs:
bash
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"
``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
- Rate Limit: Approximately 150 requests per minute
- Pagination: Large datasets are automatically paginated
- Field Selection: Only requested fields are returned to optimize bandwidth
- 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
- v1.0.1 - Current version with full Asana API integration
- v1.0.0 - Initial release
This plugin follows OpenPets standards. See the OpenPets Development Guide for development guidelines.