- Runs in Linux
- Ensure you have a Linear API key in your .env file. You can requeest one in the Settings->API section in the Linear app. See the example .env file.
- You need an OPENAPI key as well,OPENAI_API_KEY in your linux environment.
- The script run.sh in the project directory should run the app, spawn the web page and get access to Linear (project and issue data should prepopulate).
- During execution, an insights.md file is created along with the output. The file customerRequests.csv will have the raw customer request data.
Note the python requirements - a few packages are requrired. Developed with Python 3.13.5
You can download the customer records only using: 'npx ts-node src/customerRequests.ts'- there is an optional debug flag ---debug that will show diagnostic information.
You can process the downloaded records using: 'python3 feedback_analysis/analyze_feedback.py CustomerRequests.csv" - there is an optional debug flag --debug that will show diagnostic information. If you run it in this mode, only
Webpage will be here: http://localhost:3100/picker.html
Good luck. Have fun. I did!
Export customer requests from Linear, cluster and summarize them, and view the insights in a simple web UI.
- Picker web UI (served by Node/TypeScript)
- Select one of: All customer records (entire workspace), a single project, or a single issue
- Start an export and automatically run an analysis
- Live logs via SSE and an embedded insights view
- Exporter (TypeScript)
- Generates
CustomerRequests.csvfrom the selected scope
- Generates
- Analyzer (Python)
- Clusters requests, generates titles/summaries (optionally via OpenAI), and writes
insights.htmlandinsights.md
- Clusters requests, generates titles/summaries (optionally via OpenAI), and writes
- Node.js 18+ (20+ recommended)
- Python 3.10+
- A Linear API key (required)
- Optional: OpenAI API key (improves cluster titles/summaries)
- Clone and install
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>
npm install- Configure environment
cp .env.example .env
# Edit .env and set LINEAR_API_KEY (and optional OPENAI_API_KEY)- Run the picker server and open the UI
# Development (ts-node)
npm run dev
# Open http://localhost:3100/picker.html (or use PICKER_PORT in .env)- Click “Analyze Customer Requests”
- Exports the selected scope to
CustomerRequests.csv - Runs
./run_analysis.sh(createsfeedback-analysis/.venv, installs Python deps, executes analyzer) - Streams logs and embeds
insights.htmlresults in the page
# Export only
npm run export
# Analyze only (uses CustomerRequests.csv)
npm run analyze# Compile TypeScript -> dist/
npm run build
# Start compiled server
npm run start:dist
# Open http://localhost:3100/picker.html./bootstrap.sh
# Builds TS, installs Node/Python deps, prepares a Python venv, and prints next stepsLINEAR_API_KEY(required): Linear API key with read access to projects/issuesPICKER_PORT(optional): UI/server port (default 3100)OPENAI_API_KEY(optional): enables better titles/summaries
CustomerRequests.csv— exported input datapain_point_summary.csv— examples per clusterinsights.html— embeddable HTML report (the UI injects only the<body>)insights.md— Markdown report
npm run dev— start the picker server in ts-nodenpm run picker— alias for devnpm run build— compile todist/npm run start:dist— run compiled servernpm run export— run the exporternpm run analyze— run the Python analysis viarun_analysis.sh
- Missing LINEAR_API_KEY
- Set it in
.envand restart the server
- Set it in
- Python dependency issues
- Run
npm run analyzeonce to create venv and installfeedback-analysis/requirements.txt
- Run
insights.htmlnot fully rendering in the UI- The UI injects only the
<body>contents; the generator already inlines key styles for labels
- The UI injects only the
- LLM not used
- Ensure
OPENAI_API_KEYis set in.env(when running via the server) or exported in your shell (when running Python directly)
- Ensure
public/— static assets for the UI (picker.html, images)src/— TypeScript sourcescustomerRequests-server.ts— web server + APIs + SSEcustomerRequests.ts— CSV exporter
feedback-analysis/— Python analyzeranalyze_feedback.py— clustering, summaries, and report writerrequirements.txt— Python dependencies
run_analysis.sh— sets up venv and runs the analyzer.env.example— environment template
If you’d like a Dockerfile (single-image Node+Python) or CI workflow, I can add those too.