aha-studio

module
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: MIT

README

Aha Studio

Go CI Go Lint Go SAST Docs Docs Visualization License

CLI tools for Aha! product management with AQL (Aha Query Language), MCP server integration, local SQLite sync, and Neo4j graph analytics.

Overview

Aha Studio provides two command-line tools:

Binary Purpose
aha-studio AQL query CLI with SQLite sync and interactive shell
aha-mcp-server MCP server (71 tools) for Claude Desktop and AI assistants

Features

  • 🔍 AQL (Aha Query Language) - SQL-like syntax for querying Aha.io data
  • 🛠️ 71 MCP Tools - Features, Ideas, Releases, Initiatives, Graph queries, and more
  • 📡 OmniSignal provider - Normalizes Aha Ideas into vendor-neutral signals for the ProductContext signal pipeline
  • 💾 Local SQLite sync - Offline queries and fast local caching
  • 🔗 Neo4j integration - Graph analytics and relationship queries
  • 🌐 Browser automation - Strategic template creation via headless Chrome

Installation

# Install AQL CLI
go install github.com/grokify/aha-studio/cmd/aha-studio@latest

# Install MCP Server
go install github.com/grokify/aha-studio/cmd/aha-mcp-server@latest

Configuration

Set the following environment variables:

export AHA_SUBDOMAIN=mycompany    # Required: your Aha.io subdomain
export AHA_API_KEY=xxx            # Required: your Aha.io API key
export AHA_DEFAULT_PRODUCT=PROD   # Optional: default product for queries

For Neo4j graph features (optional):

export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password

For browser automation (optional):

export AHA_EMAIL=user@example.com
export AHA_PASSWORD=secret

Quick Start

AQL CLI
# Basic query
aha-studio query "FROM features LIMIT 10"

# Query with filter
aha-studio query "FROM ideas WHERE status = 'Shipped' LIMIT 5"

# Interactive shell
aha-studio shell

# Sync data to SQLite for offline queries
aha-studio sync --product PROD

# Export features to Excel ordered by rank
aha-studio query -o xlsx -f features.xlsx \
  "SELECT reference_num, name, position, tag_list, workspace FROM features ORDER BY position ASC"
MCP Server (Claude Desktop)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aha": {
      "command": "aha-mcp-server",
      "env": {
        "AHA_SUBDOMAIN": "mycompany",
        "AHA_API_KEY": "your-api-key"
      }
    }
  }
}

AQL Syntax

AQL provides a SQL-like interface for querying Aha.io data:

-- Basic query
FROM features LIMIT 10

-- Filter by status
FROM ideas WHERE status = 'In Progress'

-- Order by field
FROM releases ORDER BY release_date DESC LIMIT 5

-- Select specific fields
SELECT name, status, created_at FROM features WHERE tag = 'v2'

-- Aggregate queries
SELECT status, COUNT(*) as count FROM features GROUP BY status
Supported Entities
Entity Description
features Product features
ideas Customer ideas
releases Product releases
epics Feature epics
initiatives Strategic initiatives
goals Product goals
users Workspace users
products Products/workspaces
comments Entity comments
requirements Feature requirements
tags Entity tags

MCP Tools

The MCP server provides 71 tools organized by category.

Backend Legend: Tools marked with 🌐 require browser credentials. Tools marked with 🔗 require Neo4j.

Query Tools (Aha API)
Tool Description
query Execute AQL queries
describe_aql Get AQL syntax help
Get Tools (Aha API)
Tool Description
get_feature Get feature by reference
get_idea Get idea by reference
get_release Get release by reference
get_initiative Get initiative by reference
get_epic Get epic by ID
get_goal Get goal by ID
get_comment Get comment by ID
get_requirement Get requirement by ID
get_user Get user by ID
get_current_user Get current authenticated user
get_key_result Get key result by ID
get_persona Get persona by ID
get_team Get team by ID
get_workflow Get workflow by ID
get_strategic_model Get strategic model by ID
List Tools (Aha API)
Tool Description
list_ideas List ideas with filters
list_products List all products
list_features List features with filters
list_release_features List features for a release
list_epics List epics with filters
list_product_epics List epics for a product
list_goals List goals with filters
list_product_goals List goals for a product
list_initiatives List initiatives with filters
list_product_initiatives List initiatives for a product
list_feature_requirements List requirements for a feature
list_users List workspace users
list_workflow_statuses List workflow statuses
list_releases List releases for product
list_custom_fields List custom field definitions
list_custom_field_options List options for select custom fields
list_strategic_models List strategic models
list_product_strategic_models List strategic models for a product
search_documents Search documents via GraphQL
Create Tools (Aha API)
Tool Description
create_feature Create a new feature in a release
create_epic Create a new epic in a release
create_goal Create a new goal in a product
create_initiative Create a new initiative in a product
create_requirement Create a new requirement for a feature
create_product Create a new product
create_strategic_model Create a new strategic model
Update Tools (Aha API)
Tool Description
update_feature Update feature fields
update_epic Update epic fields
update_goal Update goal fields
update_initiative Update initiative fields
update_requirement Update requirement fields
update_release Update release fields, including description (Aha's release theme)
update_idea Update idea fields
update_product Update product fields
update_strategic_model Update strategic model fields
update_comment Update comment body
change_feature_status Change feature workflow status
assign_feature_release Assign feature to release
assign_user_to_feature Assign user to feature
Comment Tools (Aha API)
Tool Description
add_feature_comment Add comment to feature
add_idea_comment Add comment to idea
list_feature_comments List comments for a feature
list_idea_comments List comments for an idea
list_epic_comments List comments for an epic
Delete Tools (Aha API)
Tool Description
delete_requirement Delete a requirement
delete_comment Delete a comment
Template Tools
Tool Description
list_predefined_templates List strategic templates
🌐 browser_create_template Create template via browser automation
Graph Tools (Neo4j) 🔗
Tool Description
graph_sync Sync Aha data to Neo4j
graph_query Execute Cypher query
graph_find_path Find path between entities
graph_search Full-text search
graph_initiative_impact Initiative impact analysis
graph_release_deps Release dependency analysis

Development

Building
go build ./cmd/aha-studio
go build ./cmd/aha-mcp-server
Testing
go test ./...
Linting
golangci-lint run

License

This project is licensed under the MIT License - see the LICENSE file for details.

Directories

Path Synopsis
aql
ast
Package ast defines the abstract syntax tree types for AQL (Aha Query Language).
 Package ast defines the abstract syntax tree types for AQL (Aha Query Language).
lexer
Package lexer provides tokenization for AQL queries.
 Package lexer provides tokenization for AQL queries.
parser
Package parser provides a recursive descent parser for AQL queries.
 Package parser provides a recursive descent parser for AQL queries.
validator
Package validator provides semantic validation for AQL queries.
 Package validator provides semantic validation for AQL queries.
Package browser provides browser automation for Aha! using w3pilot.
 Package browser provides browser automation for Aha! using w3pilot.
Package cache provides caching for AQL query results.
 Package cache provides caching for AQL query results.
cmd
aha-mcp-server command
Command aha-mcp-server runs an Aha! MCP server that exposes tools for managing product management data from Aha!
 Command aha-mcp-server runs an Aha! MCP server that exposes tools for managing product management data from Aha!
aha-studio command
Package main provides the aha-studio CLI entry point.
 Package main provides the aha-studio CLI entry point.
Package config provides configuration file support for Aha Studio.
 Package config provides configuration file support for Aha Studio.
Package executor executes AQL query plans against the Aha API.
 Package executor executes AQL query plans against the Aha API.
Package graph provides Neo4j graph database integration for Aha Studio.
 Package graph provides Neo4j graph database integration for Aha Studio.
Package httpserver provides an HTTP API server for AQL queries.
 Package httpserver provides an HTTP API server for AQL queries.
Package mcp provides MCP server integration for Aha Studio using OmniSkill.
 Package mcp provides MCP server integration for Aha Studio using OmniSkill.
Package omnisignal provides an OmniSignal provider for Aha Ideas.
 Package omnisignal provides an OmniSignal provider for Aha Ideas.
Package planner converts AQL ASTs to execution plans.
 Package planner converts AQL ASTs to execution plans.
Package repl provides an interactive shell for AQL queries.
 Package repl provides an interactive shell for AQL queries.
Package result provides result types for AQL query execution.
 Package result provides result types for AQL query execution.
Package schema defines entity and field metadata for AQL queries.
 Package schema defines entity and field metadata for AQL queries.
Package studio provides AQL (Aha Query Language) - a JQL-like query layer for Aha.io.
 Package studio provides AQL (Aha Query Language) - a JQL-like query layer for Aha.io.
Package sync provides SQLite-based offline caching for Aha Studio.
 Package sync provides SQLite-based offline caching for Aha Studio.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.